Language Switcher WordPress Plugin
This is the third page describing the Language Switcher plugin for WordPress. If you didn't start on the first page, you might want to go back and start there.
Also... As of April 2010, this plugin is no longer being maintained. Please see note on the top of the plugin home page.
There are two types of text in WordPress: text that is stored in the WordPress database (posts, categories, options settings, etc.) and "static" text (text that is typed directly into various PHP files in WordPress, your Theme, or your plugins). These types of text have two different methods for translation using the Language Switcher.
Translating Database-Stored Text
Most text that is stored in the WordPress database is "filtered" before it is displayed to your site visitors. Plugins such as the Language Switcher can define filters, which are actually PHP functions, and WordPress will pass the text through the filtering functions before sending it to the viewer's web browser. The Language Switcher has defined filtering functions for post and page content, post and page titles, category and tag names, blogroll link descriptions and titles, and your site's overall title and description.
The Language Switcher's filters take multi-lingual text with special language tags embedded in it, figure out which language the site viewer wants to see, and output just the text in the desired language. Here is an example of how to type in multi-lingual text:
[lang_en]This is the post text in English[/lang_en]A few notes:
[lang_es]Esto es el texto del artículo en español[/lang_es]
[lang_all]I want this text to appear for all languages[/lang_all]
This text that is not in a language tag will also appear for all languages.
- In this example, "en" and "es" are the language codes for English and Spanish. Make sure the language codes in your language tags match the codes you entered in the Language Switcher's options page when you set up your site.
- You can use the special language tags in your posts, pages, post and page titles, categories and tags, blogroll (link titles and descriptions), overall site title, and overall site description/tag line. Site visitors can also use them when writing comments (if they know about them). If you are using WordPress 2.5 or later, and install the extra fixes from the download section, you can also put language tags into your sidebar widget titles, for the widgets that come with WordPress, and also into the body of Text widgets.
- For backwards compatibility with Polyglot and other plugins, you can also use an alternate form for the language tags, with <lang_en> instead of [lang_en] (etc.), but this often causes problems, especially when using WordPress's visual post editor.
- You can indicate that certain text applies to all languages, by enclosing the text in [lang_all] tags, or by leaving it outside language tags, as shown above
- If you are using the special WordPress <!--more--> tag to tell WordPress to put excerpts on site pages, you will need to make sure to put text for all of your languages both above and below that tag, because the extraction of the excerpt happens before WordPress sends your post through the Language Switcher filter to choose which language to display.
- If you have the "post slug" in your permalink structure, you will probably want to manually edit the post slug when you write a post. You can find the "post slug" section on the right side of the post write/edit screen (you will have to click the "+" sign to expand it).
- If you are migrating from the Polyglot plugin, you should not have to do anything different to your posts, categories, etc. to have Language Switcher work.
Translating Static Text
As mentioned in the Fixing Plugins and Themes section of this site, static text in plugins, WordPress, and themes is internationalized using "gettext". The basic idea is that any time WordPress, your theme, or a plugins puts text on the screen (as long as the text is enclosed in one of the gettext functions), WordPress puts the text through a translator, which basically looks up the phrase in a dictionary file and outputs the phrase in the appropriate language. Without Language Switcher, WordPress allows you to specify a single language in your configuration file, and make the built-in site components and menus appear in that language (see the WordPress in Your Language page for more information).
The Language Switcher plugin goes beyond this basic translation functionality by letting the site viewer choose which language to translate the static text of your site into. So, once you have internationalized your themes and plugins, you will need to translate them into the languages you are using for your site (aside from English, which is the default). Here are the steps to follow to translate your themes, plugins, content, and WordPress:
- Find the language codes you entered for the languages in your site in the Language Switcher's Options page.
- To translate the core of WordPress (which includes things such
as the names of days of the week and months),
download or create WordPress language files for all languages other
than English that you are going to use. What you are looking for are
files like es_ES.po and
es_ES.mo (substituting your language's 2-letter code for "es",
and an appropriate country code for "ES"; it is also fine to have files
without a country code, such as es.po and es.mo). They can be found in a couple of places:
- Visit the WordPress in Your Language page, find your language, and hopefully locate the two files you need in the downloads for that language, or on a referenced web site somewhere. Make sure the files you download are intended for the WordPress version you are using.
- The WordPress Localization page also has some language files.
- The WordPress Language Repository also has some files -- on that page, find your language/country, then click "trunk" and then "messages", and if you are lucky, they will be there.
- You can also start from scratch if you have to -- instructions are on the Translating WordPress page.
- Run the translation
tool of your choice to translate themes and plugins. (I recommend using
poEdit, if you are a Windows user.)
- If you downloaded a plugin or theme that was internationalized and came with a POT file, run the translation software on that POT file to create PO and MO files for the languages you need.
- If you internationalized your plugins or theme yourself, you'll need to create a new PO/MO file. To do that, use your translation software to make a new PO file, point it at the theme directory, plugin directory, or plugin file, and ask it to update itself ("Update from Sources" in the "Catalog" menu in poEdit). The translation software should then look through the plugin or theme you are trying to translate, to find any text that needs translating. Note: every time you modify a theme or plugin, you will need to do this step again, so I encourage you to do the modifications above before starting on translations.
- Translate all the terms your translation software finds, and save the PO and MO files. (In poEdit, make sure you have "Automatically compile MO file on save" checked in the "Editor" tab of the Preferences, which you can open from the File menu, and then save the file, which will save the PO file and create the MO file.)
- Upload the new main WordPress MO file to your web host, in the "languages" directory underneath "wp-includes" (or "wp-content" if you are using WordPress 2.2 or later). You will need to save it without the country code, i.e. a file name like "es.mo" rather than "es_ES.mo". Note: You do not need to upload the PO file(s), but save them in your local version.
- If you internationalized plugins or your theme, upload the MO file(s) to the appropriate location. For themes, MO files go into the theme's directory, along with index.php, style.css, and the other theme files; they must be named ll.mo, where ll is the language code. For plugins, you will need to figure out where to install the MO files based on the plugin author's instructions. If you created the internationalization file yourself, put the MO files in the main wp-content/plugins directory, and name them "domain-ll.mo" (without the quotes), where "domain" is the text domain for the plugin, and ll is the language code. Again, you will need to omit the country code from the MO file names.