Language Switcher WordPress Plugin

Note: A German translation of this page is now available -- thanks, Angi!

Introduction

The Language Switcher WordPress plugin allows you to create a bilingual or multi-lingual blog, using WordPress. The way it works is that you write the content for your blog in multiple languages, using special tags to tell the plugin which text goes with which language. You'll also install "gettext" language files to translate the text generated by your theme, other plugins, and WordPress itself into your target languages. The Language Switcher plugin will then let your blog viewers choose a language for viewing your blog, and put all the text on the screen into the right language.

To see the Language Switcher in action, visit HodgBlog, the plugin author's personal, bilingual blog. In the side bar, or just under a post title, click the Spanish language link, and you should see most of the text on the screen change to Spanish.

Unfortunately, setting up a multi-lingual blog does take some work. You will need to follow all the steps below carefully to get your blog functioning properly. Also, unfortunately many WordPress themes and plugins that other people have written are not set up properly for internationalization and multi-lingual blogs with the Language Switcher. Instructions are given below on how to fix them, but it will require some PHP programming (or at least PHP editing) to fix some plugins and themes. So, be prepared! The good news is that the core of WordPress has a lot of functionality, and the Language Switcher works well with the core WordPress functionality.

Note: Language Switcher does not do any translations! It just allows you to display text that you have provided, in the language preferred by your blog's visitors. There are other plugins that can be used to create multilingual blogs, which have different approaches, including automatic machine translations. To find other plugins, see the Plugins article at wordpress.org.

Since setting up a bilingual or multi-lingual blog is rather complex, this web site is basically a tutorial on how to get your blog set up, from start to finish. Contents:

Terminology note for Windows and Mac users: the word "directory" in this article is the same as "folder" -- a location containing files on a computer.

Installing or Upgrading Blog Software

WordPress Install or Upgrade

The first step in creating a bilingual or multi-lingual blog with the Language Switcher is to install or upgrade WordPress. The Language Switcher is mostly compatible with WordPress 2.1.2 and later versions. However, the released versions of WordPress have some little bugs or features that make them not quite compatible with the Language Switcher plugin, so please follow these instructions to install WordPress, or to upgrade to a new version. Important: later on, after using the Language Switcher, please return to this page and follow the instructions below in order to upgrade your bilingual or multi-lingual blog to a new version of WordPress.

  1. Read the instructions in the WordPress Installation Guide or (WordPress Upgrade Guide if you are updating from a previous version). But -- don't follow them exactly yet! Instead, follow these slightly modified steps.
  2. Download the latest version of WordPress zip file from the WordPress download page. Important: Do not download from any other site! Especially, do not get a version that has been modified for a foreign language. To make a multi-lingual version work, you will need to start with the English-language, standard version of WordPress. If you start with a different version, you will probably encounter problems, because some foreign-language WordPress versions have modified files that are not compatible with multi-lingual operation.
  3. Unzip the file onto your personal computer.
  4. If you are installing for the first time, set up your MySQL server as described in the Installation Guide. If you are upgrading, back up your previous MySQL database as described in the Upgrading guide.
  5. Modify the configuration file (as described in the Installation guide -- if you are upgrading, you can download your previous configuration file from your site).
  6. If your configuration file (wp-config.php) has this line in it, remove this line -- it seems to be incompatible with the Language Switcher in some circumstances:
    define('ENABLE_CACHE', true);
    Also, if you are using a language that uses a non-western character set (such as Chinese or Hebrew), you may need to remove these two lines from your configuration file, in order to display those characters:
    define('DB_CHARSET', 'utf8');
    define('DB_COLLATE', '');
    See this page on the WordPress support forum for more information. David, a Chinese/English Language Switcher user also wrote and said that for him, removing those lines didn't work. What worked was changing those lines to match what his database was currently using, which you can find in PHPMyAdmin. The Character Set setting is displayed on the PHPMyAdmin home page (it's usually utf8, I think), and the Collate setting is displayed when you choose a database or database table. If you have a working database table that is able to display your language's characters in PHPMyAdmin, then you should be able to choose that DB_COLLATE setting in the wp-config.php file. For David, the DB_COLLATE setting that worked for Chinese/English was 'utf8_unicode-ci'.
  7. Download the zip file of WordPress fixes (if any) corresponding to your WordPress version from the downloads section below, and install the files into the correct locations (as specified in the README.txt file contained in the fixes zip file).
  8. If you are using WordPress version 2.3 or higher, also follow the 2.3 database fix instructions below.
  9. If you are upgrading, delete the obsolete files from your installation, as specified in the Upgrade guide.
  10. Upload the entire set of WordPress files to your server (see the Installation Guide for a description of where to put them).
  11. Run the install.php or upgrade.php file to complete the installation (as described in the installation/upgrade guide).

Manual Database Field Change

If you did not install the fixes zip file, or if you are adding the Language Switcher to an existing site, you will find that you probably need a larger field for entering categories (and tags, if you are using WordPress 2.3 or higher), than WordPress provides by default. The fixes zip files make it 200 characters instead of 55 characters. But if you did not install the fixes, or ran the upgrade/install scripts before you installed the fixes, you may need to follow these directions to fix your database so that it has more space for categories.

Also, if you are upgrading from a previous version of WordPress, already had an existing Language Switcher installation, and did not install the fixes for your new version before running upgrade.php, you may find that your categories from before will get truncated back to the WordPress default of 55 characters, and very likely your entire blog will fail to display correctly until you go back, follow the directions below to fix the field width manually, and then edit all the categories (which you may need to do in the database manually too).

To fix your category name field manually, start by logging into your web host's PHPMyAdmin page (see the Installing WordPress page for reference). In PHPMyAdmin, you will need to:

  1. Navigate to the WordPress database you set up during WordPress installation (it may be selected by default).
  2. Navigate to the "Structure" tab of the "categories" table, which may have a prefix on its name (like "wp_categories"). If you are using WordPress 2.3 or a later version, the table is called "terms" instead of "categories".
  3. Click on the "change" icon or link in the "cat_name" field row (the icon is a pencil in the version of PHPMyAdmin my web host uses). In WordPress 2.3 and later, the field is called "name".
  4. Increase the Length property; I suggest using 200 characters.
  5. Save your change.
  6. If this is an upgrade from a previous multi-lingual blog installation, you may also need to edit your categories in the database. Just click on the Browse tab in your categories (or terms) table, find a row that needs editing, click on the "change" icon (the pencil), and edit the category (or term) name field back to what it should be.

Installing and Setting Up the Language Switcher Plugin

The next step in creating your multi-lingual blog is to install the Language Switcher plugin. After downloading the zip file from the downloads section below, follow these steps to install, activate, and set it up:

  1. Upload langswitch.php (the main plugin file) into wp_content/plugins, in your WordPress installation.
  2. Upload the flag icon files (*.png) into sub-directory "langswitch_flags" of wp-content/plugins, in your WordPress installation. You can add other flags, or substitute other image files, by putting them in this directory.
  3. If you want to localize Language Switcher so that the administration menus are displayed in a language besides English, and the title of the language list widget (if you are using Widgets), you can use the langswitch.pot file and your favorite localization software to translate Language Switcher. See the general instructions on plugin and theme translation, below; your localization file(s) will need to be named "langswitch-ll.mo", where "ll" is the ISO code of the language you want to use, and they will need to go into sub-directory "langswitch_flags". Several localization files have been provided in the zip file, but they may not be complete or accurate (they came from other plugin users).
  4. Activate the plugin from your WordPress administration panel (log in, click on "Plugins" in the top menu bar, and activate the "Language Switcher" plugin by clicking on the link that says "Activate" to the right of the plugin name). If you need more detailed information on how to manage WordPress plugins, please visit the Managing Plugins page on the WordPress site.
  5. Enter information about the languages you want to use in your blog on the Language Switcher options page.
    • To get to the page in the administration panel, click on "Options", and then "Language Switcher"; if you are using WordPress 2.5 or later, click on "Settings" and then "Language Switcher".
    • Type in the two-letter ISO code for your default language (the one someone will see when first visiting the page) at the top; a table of ISO codes is available at this Wikipedia site (be sure to use the two-letter codes from the first column). Note: If you cannot find an ISO code for your language, you can make one up. The Language Switcher does not care, as long as you use consistent 2-letter codes on the Options screen, when entering multilingual text (see below), and for the MO file names (see below).
    • In the table below, enter information about all the languages you will use in your blog, one language per line (including the default language). Fields:
      • ISO Code: The two-letter ISO code for the language; for example, "en" for English, and "es" for Spanish (do not type the quotes).
      • Language: The name of the language, in that language. For example, for English, type in "English", and for Spanish, type in "español" (without the quotes).
      • Flag File: The image file name for the flag you want to use for the language (from the langswitch_flags directory in the plugin distribution). For instance, for English, you could use "en.png" for the English flag, "us.png" for the American flag, etc. Enter the file name without the quotes and without the directory name.
      • Time Format: The format you would like to use for time of day for that language, using standard PHP time/date formatting codes found on this PHP documentation page. For instance, to display times in a format like "3:15 PM", you would type in "g:i A", and to use a 24-hour clock, you would use "G:i" (in both cases without the quotes).
      • Date Format: The format you would like to use for dates for that language, using standard PHP time/date formatting codes (see above). For instance, to display dates in a format like "25 Dec. 2008", you would type in "j M. Y"; to get something like "12/25/2008", you could use "m/d/Y"; and to have the day before the month, "d/m/Y" (in all cases without the quotes).
      • Text Missing Message: The message to display on the screen if an article has no translation for the requested language.
    • Click "Update Options" when you have entered all your language information.
    • If you want to change some information, enter the new information in the line with the ISO code you want to change, and click "Update Options".
    • If you want to delete a language, check the "Delete" box in that row and click "Update Options".
    • If you want to add additional languages, type in the information, starting at the first blank line, and click "Update Options".
    • If you want to enter more new languages than there are space for, enter as many as you can, click "Update Options", and then more blank lines will appear on the screen. Repeat until all your languages are entered.

Installing Plugins and Themes

Installing a Theme

The next step in creating your multi-lingual blog, unless you happen to like the default WordPress theme, is to find a theme, and install it. Themes can be found in the WordPress Theme Repository and other web sites. Important: Get an internationalized theme, if possible. If you cannot find an internationalized theme that you like, than get an English-language theme. Internationalizing a non-English theme is much more complex than internationalizing an English-language theme, and you will need to have an internationalized theme in order for its text to switch between languages using the Language Switcher. To install a theme:

  1. Download the theme from the repository, or anywhere you found it. It should come in a zip file.
  2. Unzip and upload the theme's distribution files into the WordPress "themes" directory on your site, which is under "wp-content".
  3. Visit the WordPress administration page, click on "Presentation", and activate your new theme by clicking on it.

Installing Other Plugins

The next step is to find and install other plugins; you can look for plugins in the WordPress Plugins List. Besides Language Switcher, which you should have already installed, you should install any other plugins you plan to use at this point. To install a plugin:

  1. Download the plugin from the plugin's home page (linked from the repository). It should either come in a zip file, or as a bare PHP script.
  2. Unzip and upload the plugin's distribution files into the WordPress "plugins" directory on your site, which is under "wp-content". Follow the plugin's instructions -- some plugins go into sub-directories of the plugins directory, and some go directly into the plugins directory.
  3. Visit the WordPress administration page, click on "Plugins", and activate your new plugin by clicking on the "Activate" link in the list.

If you are using WordPress 2.3, and wish to put multi-lingual tags on your posts using the built-in WordPress tagging functionality, I recommend that you get the Advanced Tag Entry plugin. The built-in tag entry field in WordPress 2.3 is inadequate for multi-lingual tags, because you cannot define tag "slugs" (which are used in tag URLs). However, in WordPress 2.5, there is a Tag Management screen you can use to define tags with slugs.

Adding Language Switcher Features to your Theme

The next step in creating your multi-lingual blog is to modify your theme, so that it can display language choices to your blog viewers. There are two additions that you can make to your theme.

List of All Available Languages

To add a clickable list of all available languages to the sidebar of your blog, use the "langswitch_list_langs" function. For instance, if you want to list the languages by name, put the following into the sidebar.php file of your Theme:

<li><h2><?php _e('Language');?></h2>
<ul>
<?php if(function_exists('langswitch_list_langs')){
langswitch_list_langs(false, true, 'li');
}?>
</ul>
</li>

The inputs to the function are:

So, if you want to use flags and not text, use (true, false), and if you want to use both, use (true, true). NOTE: If you are migrating from the Polyglot plugin to Language Switcher, you can just add the lines above to your template. Because of the part in what is above that checks to see if the function exists, as long as you have only Polyglot or Language Switcher (but not both) enabled, only one of them will be listing its languages.

Alternatively, if you are using WordPress 2.2 or later, and are using the built-in Widgets with your theme, the sidebar languages list is available as a Widget. The settings for the Widget (available after you drag the box to your sidebar) allow you to choose between flags, language names, or both by clicking checkboxes. In this case, 'li' is always used for the HTML tag, but of course you can style the list using your theme's style file.

Also note that this list of languages (or flags) can go into the header, footer, or anywhere else in your Theme that you want. Just put the function text where you want the list to appear.

One more note: Even if you use <li> tags, you can fix the style of the list of languages in your theme's style.css file. Also, most theme sidebars to expect you to put bullet lists on the sidebar -- it is a WordPress standard.

List of Other Languages For A Post/Page

To add a clickable list of all the languages available for a blog post or page (excluding the language currently being displayed), use the "langswitch_post_other_langs" function. This will usually go between the title and content of your post/page. You will need to add this to any Theme files that display posts/pages, if you want the language links to display (e.g. index.php, single.php, etc. -- see this article on the template file hierarchy to learn more about which Theme files are used to display your blog). For instance, to make a UL list of the languages, using language names and not flags to indicate the languages, you would add the following:

<?php if(function_exists('langswitch_post_other_langs')){ langswitch_post_other_langs(false, true, ' ','<ul>', '</ul>', '<li>', '</li>'); }?>

The inputs to the function are:

So, if you want to use flags instead of language names, then you need to switch the true/false in the above lines, and you will probably want to replace the UL and LI tags with spaces, because you probably will not want a bullet list of flags. You can also use both language names and flags by setting both of the first two inputs to true.

Note: If you are migrating from Polyglot, you can just add the lines above to your template. Because of the part in what is above that checks to see if the function exists, as long as you have only Polyglot or Language Switcher (but not both) enabled, only one of them will be listing its languages.

Fixing Plugins and Themes to Work with Language Switcher

Unfortunately, not all plugins and themes work well with the Language Switcher. This section explains some common things you might have to do to fix them so they will work better in a multi-lingual blog.

Internationalizing Plugins and Themes with Gettext

In order to have your plugins and theme work correctly in a multi-lingual blog, they will need to be internationalized. Many plugins and some themes are already internationalized (including the Language Switcher and any other plugins you might download from this web site). However, not all plugins and themes come internationalized, and this section explains how to internationalize them. It's possible that your plugins and theme might already be internationalized, and if that is the case, you can skip this section. If you're not sure, you can try skipping this section, and then come back and do it if you find things are not working properly. See the Translating WordPress Page for more information on internationalization with "gettext", which is the internationalization method WordPress uses. You may also want to read the Internationalization section of the Writing a Plugin article; Themes work the same way.

What you are aiming for is to have all of the text and terms that your theme and plugins print on the screen appear in the language that your blog viewer has chosen. In order for that to happen (assuming that you have installed language files and translated the terms; see the translating section below), you need to enclose all text printed on the screen by your themes and plugins in one of the two WordPress "gettext" functions: "_e" and "__" (two underscores). Note: You can do this even if you are not a PHP programmer! It is really just a simple replacement of text that is already in your plugin and theme files. But make a backup copy of your files before you start, just in case. Also note that the text inide the "_e" and "__" functions must be in English.

The "_e" function is used for text that was not previously inside a PHP function. For example, to fix the "Categories" header in your sidebar, you need to change something that looks like this in your sidebar.php file:

<h2>Categories</h2>

to this:

<h2><?php _e("Categories", "text_domain"); ?></h2>

Note that to use the "_e" function, you have to first "escape" into PHP, which is what the <?php and ?> tags do, and within that function, all text must be in English, and has to be enclosed in either single or double quotes. Technically speaking, the "_e" function prints its text (after translating it) to the browser output.

Also note that after the text you are trying to internationalize, you need to supply a "text domain" name. You will need to choose a name, and then make sure that the text domain is loaded properly by WordPress. For instance, if you chose the Theme's text domain name to be "mytheme", you would need to put the following lines at the beginning of the theme's functions.php file (you might have to create a new functions.php file if it doesn't exist):

<?php load_theme_textdomain('mytheme'); ?>

Note: The line above should go at the very top of your functions.php file, before any other <?php tags that are likely at the top of functions.php, if the file already existed! Or you can add it at the very end of the file, after the closing ?> that is probably at the end of the file.

For a plugin, you will need to add the following lines somewhere in the main plugin PHP file, assuming that the plugin functions all start with the prefix "abc_plugin" and the text domain name you want to use is "abc_text_domain":

add_action('init', 'abc_plugin_init' );
function abc_plugin_init() {
load_plugin_textdomain( 'abc_text_domain' );
}

The "__" function is used for text that was already within a PHP function (technically, this function just returns the text to the outer function, instead of printing it). For example, to fix the "more" text that is printed on the screen in the link to read the rest of your blog article, if you are only printing excerpts on your main page, change this in your index.php file:

<h2><?php the_content('Read more...'); ?></h2>

to:

<h2><?php the_content(__('Read more...', "text_domain")); ?></h2>

So, you are basically replacing

'(more...)'

(which was going to put the words "Read more" and three dots somewhere on your screen, from inside that PHP function) with

__( 'Read more...', "text_domain" )

(which will translate it before it gets put on the screen).

So, in summary, you will need to put the "__( )" function around all text (in English) in single or double quotes that eventually goes on the screen, and which is inside PHP functions. And you will need to escape into PHP and put the "_e( )" function and quotes around text (in English) that was not previously in a PHP function. See the testing section below for some suggestions on how to identify what text you actually need to fix.

Filtering Output of Plugins and Themes

Sometimes you will find that a Theme or Plugin you want to use is putting information on the screen, such as post titles or category names, that you have added language tags to (or that you want to add language tags to) -- but the theme or plugin is not "filtering" the information (see the section on translations below). So, you are getting multiple language versions and the language tags are showing. If that is the case, you can fix it by modifying the PHP code in the Theme or plugin. Here are the steps:

  1. Figure out where in the plugin/theme the information is being put on the screen. For instance, in a widget you might see a line like this where it puts the widget's title on the screen:
    echo $before_title . $title . $after_title;
    Another possibility would be something like this, where a post title is being displayed:
    echo '<li><a href="' . $external->post_content . '">' . $external->post_title . '</a></li>';
  2. Now that you have found the information, you need to put a "filter" function around the text. In these two examples, you would replace what was in your plugin/theme with the following:
    echo $before_title . apply_filters( 'the_title', $title ) . $after_title;
    and:
    echo '<li><a href="' . $external->post_content . '">' . apply_filters( 'the_title', $external->post_title ) . '</a></li>';
  3. The replacements above are both "title" type of information. The Language Switcher plugin actually does the same exact filters for post titles, categories, post content, blogroll entries, etc. So the modifications above will work with any information. However, if you are using other plugins, it is possible that they might also apply special filters to post title information. So, you can also use other filters besides 'the_title', such as 'the_content' (post content), 'comment_text' (comments), 'the_category' (category names), 'link_title' (names of blogroll links), and 'link_description' (descriptions of blogroll links). The Language Switcher doesn't care, but if you are having trouble with other plugins interfering, you might try one of the other filters.

Times and Dates in Themes

The Language Switcher overrides the WordPress Theme functions the_time() and the_date(), to use the time/date formats you entered in the Options page. Because of this override, to print out custom dates/times in your Theme (such as just the month/year or just the year), you will need to find out where in your Theme the custom dates/times are being printed, and then replace the_time( something ) or the_date( something ) with

echo get_the_time( something )

Be sure not to change the "something" that was inside the parentheses of the function!

If you are still having trouble with dates and times when using the Language Switcher, please (a) update to version 1.10, and then if you are still having trouble, contact the plugin author and describe the problem.

Translating WordPress, Plugins, Themes, and Content

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 blog 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 blog'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 blog 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]
[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.
A few notes:

Translating Static Text

As mentioned above in the Fixing Plugins and Themes section, 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 blog 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 blog viewer choose which language to translate the static text of your blog into. So, once you have internationalized your themes and plugins, you will need to translate them into the languages you are using for your blog (aside from English, which is the default). Here are the steps to follow to translate your themes, plugins, content, and WordPress:

  1. Find the language codes you entered for the languages in your blog in the Language Switcher's Options page.
  2. To translate the core of WordPress, 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.
    • Put the core WordPress language files into the "languages" directory underneath "wp-includes" (or "wp-content", if you are using WordPress 2.2 or later) in your local copy of WordPress. You may have to create the languages directory.
  3. 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.)
  4. 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.
  5. 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.

Testing and Troubleshooting

Once you have followed the steps above, you will need to do some testing before your blog is ready for public release. Here is the process I would suggest:

  1. Delete the dummy articles, categories, comments, and blogroll links that come with your original installation of WordPress.
  2. Make some tagged, multilingual content, as described in the translation section above. Write one short multilingual article, using the special language tags (including the title). Also, make one multilingual category name for your post and another for links, and add a multilingual link to your blogroll.
  3. Visit your blog's home page. Verify that everything on the screen appears in your default language.
  4. Click on a language link or flag to change to a different language, and verify that everything on the screen appears in that language. Also verify that if you click on links, the language is maintained (you will need to have cookies enabled to ensure that the language is maintained when you close your browser window).
  5. Repeat the previous two steps for a category archive page, a date archive page, a search results page, and a single article page.
  6. Repeat the previous three steps for any additional languages you are using.
  7. You might also want to verify that after selecting a language, the WordPress adminstration panels appear in that language.
  8. If you find any text that is not appearing in the right language, here are some things you can do to try to make it right:
    • If the text that is not working correctly came from the content you entered (article text, titles, blogroll, categories, etc.), check to see that you are using the language tags correctly in your content.
    • If none of the static text seems to be changing for you, your MO files are probably either missing, have the wrong names, or are in the wrong places. Or, it could be this bug in WordPress's "gettext" functionality, which has to do with whether your web site is running on a computer with a 64-bit processor, or a 32-bit processor. (The link shows how to fix this problem.)
    • If some of the text is changing but some isn't, you probably need to internationalize or filter more of your plugins, or translate more terms. See Fixing Plugins and Themes or Translating above for more information.
    • If you find that some things seem to be "sticky" in one of your languages (meaning that when you change languages, they still have links that lead to articles back in the previous language), you could have a "cache" problem, where WordPress is keeping some of its output around and re-using it, rather than changing it when you change languages. Check to see if you have this line in your wp-config.php file, and if so, remove it:
      define('ENABLE_CACHE', true);
    • If the text that is not appearing in the right language is part of the WordPress administrative panels, then you probably need to add translations to the main WordPress language files.
    • If none fo the WordPress administration panel text is changing to your non-English language, then probably your language file for WordPress is missing or has the wrong name. It must be named ll.mo, where ll is your two-letter language code, and it must be in directory wp-content/languages in your WordPress installation (wp-includes/languages may also work).

Frequently Asked Questions (and answers)

  1. How can I use different flag images?
    Put the image files you want to use into the sub-directory "langswitch_flags" of wp-content/plugins, in your WordPress installation. Then change your Language Switcher Options to associate languages with the desired flag image files.
  2. I am thinking about converting an existing blog to being multilingual. Can I prepare my translations of old posts off-line before activating the plugin?
    My recommendation would be that you go ahead and install/activate the Language Switcher, and then fill in the translations for past articles as you have time. Language Switcher works just fine with posts that have no language tags -- it just allows them to be viewed like they were before you installed and activated the Language Switcher. The other alternative would be to translate the articles into text documents off-line, and then when you are ready to turn the switch, turn on Language Switcher and put in all the translations. But that would mean a delay, and an inability to write new posts with translations while you are working on the old posts. Another thing you could do is to prepare a section something like this, in all of your blog's languages:
    [lang_en]I'm working on translating my past posts. For now, this post is only available in English.[/lang_en] [lang_es]Estoy traduciendo blah blah blah [/lang_es] [lang_it]...[/lang_it]
    If you copy/paste something like this at the top of all of your past articles, blog viewers will see a description of what is going on, in their chosen language, followed by the untranslated text of the post. The thing to avoid is to have Language Switcher turned off, but have posts with language tags in them. They will not look good on the screen!
  3. I installed and activated the plugin, but some of the text on my screen is not being translated. Why?
    See the Testing and Troubleshooting section above.
  4. I am using the built-in WordPress Widgets for my sidebar, but the widget titles are not being translated. What can I do?
    You can put Language Switcher language tags into the titles you enter on the Widget option screens, and then modify the Widget PHP files so that the title text is "filtered". See the Fixing Themes and Plugins section above to learn how to add filters to PHP files.
  5. What happens with comments on a post?
    Basically, comments are run through the Language Switcher just the same as the text in your posts. So, assuming the commenter doesn't put language tags into their comment, it will be as if they put [lang_all] tags around it, and it will appear in all languages.
  6. Another plugin I am using has some special URLs, and it stops working when I activate the Language Switcher. How can I fix this?
    The Language Switcher adds suffixes to your blog's URLs to indicate languages. If you have permalinks turned on in your blog, the suffixes look something like "/langswitch_lang/de" to switch to German (code "de"). If you don't have permalinks, the suffixes look like this instead: "?langswitch_lang=de".

    Unfortunately, while the core of WordPress doesn't care, and properly-written plugins also should not care, some plugins use special URL detection that cannot deal with the first type of URL suffix. If this is happening in your blog, you can modify the Language Switcher so that it only uses the second type of URL suffix (you will need to make this modification again if you ever upgrade to a new version of the Language Switcher).

    To do this, edit the langswitch.php file in a plain-text editor. Find these lines (they may be slightly different in different versions of Language Switcher) and delete them: 
      if( $permalink != '' ) {
    // we have a permalink structure, add a new param

    return langswitch_trailingslashit( $urlstr ) . $langSwitchPermalink . "/" .
      $lang;
  }
    Save the file, upload to your site, and your other plugin's URLs should start working again.
  7. When I turn on Language Switcher, something strange happens with the times and dates on my posts. How can I fix it?
    See the Fixing Plugins and Themes section above.
  8. I don't think the default language setting is working. Why?
    The Language Switcher goes through the following steps to see what language to use when displaying your blog to a visitor:
    1. Checks the language setting of the visitor's web browser.
    2. Checks for a cookie - this cookie is set by the Language Switcher after the first time through these steps, and if the cookie exists, it overrides the browser setting.
    3. Checks for a language in the URL, and if there is one, overrides cookies and browser settings (i.e. if the person has clicked on a link that changes the language).
    4. If none of the above gives a valid language (i.e. a language that you have entered in the Language Switcher settings page as one of the languages used in your blog ), Language Switcher uses your blog's default language from the settings page.
    So, the default language setting is only used if there is no other information giving a language. The WPLANG variable is not used in this process, by the way. And once a language is chosen via the above steps, Language Switcher stores a cookie that will make it continue to display everything (including the admin panel) in that language until you choose another language.
  9. What if there is no official 2-letter code for my language, or if I want to use two different locales whose languages have the same 2-letter code?
    The Language Switcher actually doesn't care whether you use "official" 2-letter language codes or not. So, just make up a 2-letter code for your language, and use it consistently in the Language Switcher options and when creating posts, categories, etc., and it should work just fine. The only thing that will not work with this method is that the automatic browser-detection of language will not work -- a user will have to click on a link to switch to your invented language code's language.
  10. I am using a static page as my home page, and when I do an empty (no search term) search (which gives me the home page) and then switch to a non-default language, a list of posts is displayed instead. What can I do?
    Some themes, when they are putting the search form on the screen, give the search button's HTML tag a "name" attribute. You need to remove this name, or replace it with an "id" attribute (you may also need to update your theme's style.css file). So, for instance, if your theme's search button line looks like this:
    <input type="submit" name="sbutton" value="<?php _e('Search'); ?>" />
    you need to replace it with this:
    <input type="submit" id="sbutton" value="<?php _e('Search'); ?>" />
    This should fix the problem, although you may still see a problem that if a blog viewer switches to a non-default language, does a search, and doesn't accept a cookie that stores their language preference, they may get switched back to the default language. They would just have to click on their language in the sidebar again, if that is the case.

    If you are interested, here is a bit of background. When you do a search for a term, the suffix "?s=term" is added to the URL (without the quotes), and WordPress knows to search for posts containing the term. If you don't enter a term, "?s=" is added to the URL, but since there is no search term, WordPress ignores it and goes to the home page. However, if you then add a language link to the URL, the extra URL suffix for the language would confuse WordPress and it would give you a list of posts, which is fine if that is normally what is on your home page, but not so good if you are using a static home page. So, Language Switcher cleans out empty "?s=" URL suffixes when making language links, so your viewers will still see the home page. Now, if your button also has a name, you'll see "?s=&sbutton=Search" on the URL, which again confuses WordPress, and since Language Switcher doesn't know the name of your particular search button, it doesn't know it should clean out the empty search suffix. Taking the name out of the search button fixes the problem.
  11. I can program a little in PHP, and I want to know if there is a way I can do something in PHP that detects what language the blog viewer has chosen in the Language Switcher.
    Yes, you can. There is a global variable in the Language Switcher called $langswitch_lang_pref, which gets set to the 2-letter language code currently in effect. So you can do something like this: 
    if( $langswitch_lang_pref == 'ru' ) {
   // do something if the language is Russian
} else {
   // do something different if the language is not Russian
}
    Note that if this is inside of a PHP function, you will need to add this line, inside your PHP function, just before the lines above: 
    global $langswitch_lang_pref;
  12. Is there an easier way to insert the language tags when editing a post?
    If you want to, you can add editing toolbar buttons to the editing screen. To do this, you will need to find the file "quicktags.js" in the wp-includes/js directory of your WordPress installation. Edit this file using a text editor, find the area where the buttons are defined, and add new buttons similar to this: 
    edButtons[edButtons.length] =
   new edButton( 'ed_en', 'lang_en', '[lang_en]', '[/lang_en]', 'e' );
    Thanks to user Christina for that suggestion!
  13. What versions of WordPress is this plugin compatible with?
    Language Switcher works with version 2.1.2 and above of WordPress, if you have the WordPress fixes installed (as detailed in the Installing WordPress section. The latest version of WordPress that has been tested with this plugin is 2.5.
  14. What has changed from version to version of Language Switcher?
    • Version 1.15 - Fix for WordPress 2.5 widget filtering (needs 2.5 updates installed from download below)
    • Version 1.14 - Fix for WordPress 2.5 tag filtering
    • Version 1.13 - Add trailing / to generated URLs, for fewer redirects.
    • Version 1.12 - Fix bug in URLs generated for page 2, page 3, etc.
    • Version 1.11 - Fix bug in comment dates in comment RSS feed. Update for compatibility to upcoming version 2.5 of WordPress.
    • Version 1.10 - New argument for HTML tag added to language list sidebar function. Updates for WordPress 2.3.1. Update to date/time behavior. Another bug fix on next page links. When outputting 'no text in this language' message, only do so if the original post had some text in it.
    • Version 1.09 - Updates so Language Switcher will work with WordPress 2.3 (still works with earlier versions). Another bug fix on nextpage links. Better logic on finding the user's preferred language (considers browser preferences and only accepts languages that exist in the settings). Fix bug that caused endless backslashes in options entry screen.
    • Version 1.08 - Another bug fix on nextpage tags and permalinks.
    • Version 1.07 - Numerous bug fixes, including printing message when title has no text in user's preferred language, setting language correctly in RSS feeds, better permalink behavior, and getting the nextpage tag to work in articles. Also made the language list sidebar function into a Widget, for WordPress 2.2 and above (note that you will need an updated widgets.php file from the fixes zip file to get the Recent Comments Widget to work correctly).
    • Version 1.06 - Internal release only
    • Version 1.05 - Bug fixes for static home page links, and for the situation where the post has no information in the user's preferred language.
    • Version 1.04 - Bug fix for trackback/feed links.
    • Version 1.03 - Bug fix for language permalink on home page for some users.
    • Version 1.02 - Bug fix for comment dates/times.
    • Version 1.01 - Slight changes to syntax of the language listing functions. Added permalink support.
    • Version 1.0 - Limited initial release.
  15. How can I find out if there is a new version of the plugin?
    Subscribe to the RSS feed on the sidebar of this page, or check back on this page regularly to see if there is a new version. Note: The mechanism in WordPress 2.3 for automatic checking of version updates does NOT work with this plugin! It only works for plugins that are hosted on a particular WordPress plugin site, and this plugin is not hosted there. Sorry!

Downloads

Language Switcher Plugin

Click here to download the plugin package (zip file). The file size is 194 KB (199,443 bytes). The current version of Language Switcher is 1.15.

WordPress Fixes

WordPress 2.1.2 and later versions are, by default, almost compatible with the Language Switcher. However, there are a few incompatibilities, so if you want your multi-lingual or bilingual blog to work entirely, including posts, categories, links, link categories, RSS feeds, etc., and if you want the WordPress admin pages to display correctly, you will need to modify a few files in your WordPress installation (see the installation instructions above). So, here are some zip files of modifications -- each is specific to a particular version of WordPress. You can find out what version of WordPress you are using by looking at the bottom of your admin panel, if you already have it installed. If you don't have it installed yet, the file name of the WordPress zip download you got from the WordPress site should have the version number in it. The "README" file in each zip file below explains where to put the enclosed files.

WordPress 2.3.x: All of the incompatibilities are fixed! All you need to do is edit one file to fix the database field that holds category and tag names to have more space.

WordPress 2.5: There is again a zip file, to fix a problem with adding tags to posts on the post editing screen, and make it so widget titles can be filtered. You also need to do the database schema change to fix the database field that holds category and tag names to have more space.

Click here to download the Version 2.5 zip file. The file size is 45.0 KB (46,084 bytes). Note that this file is only compatible with WordPress version 2.5.

Click here to download the Version 2.2.2 zip file. The file size is 16.7 KB (17,174 bytes). Note that this file is only compatible with WordPress version 2.2.2 and 2.2.3.

Click here to download the Version 2.2.1 zip file. The file size is 16.7 KB (17,175 bytes). Note that this file is only compatible with WordPress version 2.2.1.

Click here to download the Version 2.2 zip file. The file size is 23.9 KB (24,531 bytes). Note that this file is only compatible with WordPress version 2.2.

Click here to download the Version 2.1.3 zip file. The file size is 156 KB (159,797 bytes). Note that this file is only compatible with WordPress version 2.1.3.

Click here to download the Version 2.1.2 zip file. The file size is 156 KB (159,855 bytes). Note that this file is only compatible with WordPress version 2.1.2.

WordPress 2.3 Fix for Database Schema File

WordPress 2.3 versions no longer require a special file download. The only change you will probably want to make is to make the database field that holds category and tag names wider, so that it has room for multi-lingual categories and tags. It is best do make this edit before running the install or upgrade script in your new/upgraded WordPress installation. Otherwise, you will need to follow the instructions above for manually fixing your database. Here are the steps for pre-script:

  1. Find a file called "schema.php" in the "includes" sub-directory of the "wp-admin" directory of your WordPress installation.
  2. Open this file in a plain-text editor (such as Notepad on Windows).
  3. Down about 10 lines, find a line that creates the "terms" table. It should look something like this:
    $wp_queries="CREATE TABLE $wpdb->terms (
  4. A few rows below that, find the line that creates the "name" field in this table. It should look something like this:
    name varchar(55) NOT NULL default '',
  5. Change the 55 to 200 (or even a larger number if you are using lots of different languages in your blog, and find you are running out of space for storing category and tag names).
  6. Save the file, and if you have already uploaded your WordPress files, upload this file to your server.

Questions, Comments, and Bugs

Jennifer Hodgdon, the owner of Poplar ProductivityWare and the author of the Language Switcher, would like to thank everyone who has sent in bug reports and suggestions about the Language Switcher. It would not work so well without your help! Language Switcher is based on Polyglot, by Martin Chlupac (the flags came from the Polyglot distribution), which was in turn based on Language Picker (which no longer exists).

The Language Switcher plugin is provided free, with no warrantee and no guarantee of service or support. However, Poplar ProductivityWare welcomes your comments. So if you have questions about how to install or use the plugin, suggestions for how to make it better, or wish to report a bug in the plugin, please contact Poplar ProductivityWare. Jennifer would really appreciate it if you would carefully re-read the documentation above before contacting her. Thanks!

Poplar ProductivityWare: your Seattle-area source for web databases, web programming, Palm OS applications, and analytical/modeling software

Home | Web Programming | Custom Software | Articles | Downloads | Testimonials | Values | Contact Us

Poplar ProductivityWare® is a trademark registered in the U.S. Patent and Trademark Office

Copyright (C) 2003-2008 Poplar ProductivityWare LLC

On This Site:

Home: See an overview of the company

Web Programming: Find out how we can improve your web site

Custom Software: Learn about our custom Palm OS and analytical software services

Articles: Get free information on a variety of topics

Downloads: Download free software

Testimonials: See what other clients have said

Values: Learn about the values that govern our business, and read our privacy policy

Contact Us: Locate our phone, email, and mailing addresses

RSSRSS Feed: Keep track of our new articles and downloads by subscribing (learn about RSS here)

Search the Poplar ProductivityWare site using Google: