Language Switcher WordPress Plugin
Theme and Plugin Modifications
This is the second 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.
Adding Language Switcher Features to your Theme
The next step in creating your multi-lingual site is to modify your theme, so that it can display language choices to your site 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 site, you have two choices:
- Modify your theme, using 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>
The inputs to the function are:
<ul>
<?php if(function_exists('langswitch_list_langs')){
langswitch_list_langs(false, true, 'li');
}?>
</ul>
</li>
- Use Flags: true or false (true means to use flags to indicate languages)
- Use Text: true or false (true means to use text language names)
- HTML Tag: (Language Switcher 1.10 and later versions only) HTML tag to enclose each flag/language name in -- enclose in single-quotes. The default is 'li' to use <li> (list item) tags. Alternatives would be 'p' to use paragraph tags, 'h3' to use 3rd-level header tags, etc. If you don't really want them in HTML tags at all, try 'span', because that's a fairly neutral tag. Note that the <ul> list starting tag is not included, in any case!
- 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, if you use the Modify your Theme option (Widgets only work with sidebars). 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 site). 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:
- Use Flags: true or false (true means to use flags to indicate languages)
- Use Text: true or false (true means to use text language names)
- "None" Text: text to print out if there are no languages to list (put inside single or double quotes)
- Pre-List Text: text to print out before the list of languages (put inside single or double quotes)
- Post-List Text: text to print out after the list of languages (put inside single or double quotes)
- Pre-Item Text: text to print out before each language (put inside single or double quotes)
- Post-Item Text: text to print out after each language (put inside single or double quotes)
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 site.
Language Meta Tags for Themes
One thing you might want to do is to put language "meta" tags in the HTML header section of your theme. To make the language tags to reflect the current language setting of the site viewer, use the following lines (possibly replacing whatever language tags your theme previously included):
<meta name="language" content="<?php echo(get_locale()); ?>" />
<meta http-equiv="content-language" content="<?php echo(get_locale()); ?>" />
Internationalizing Plugins and Themes with Gettext
In order to have your plugins and theme work correctly in a multi-lingual site, 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 site viewer has chosen. In order for that to happen (assuming that you have installed language files and translated the terms; see the translating section of this site), you need to enclose all text directly 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 inside 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
'Read 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 of this site 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 translating database-stored text for more information). 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:
- 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_url . '">' . $external->post_title . '</a></li>';
- 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( 'widget_title', $title ) . $after_title;
and:echo '<li><a href="' . $external->post_url . '">' . apply_filters( 'the_title', $external->post_title ) . '</a></li>';
- 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!
Note that the names of months and days of the week in WordPress are translated in the main WordPress translation file. So if you are using a format that displays month/day names, you will need to follow the instructions in the Translating section to install the main WordPress .mo file(s) for the languages you are using on your site, in order to get dates to display correctly in al languages.
If you are still having trouble with dates and times when using the Language Switcher, please update to the latest version of Language Switcher, make sure you have followed the instructions above, and then if you are still having trouble, contact the plugin author and describe the problem.
Making Other Sections of your Theme Switch Languages
Some themes will have sections of their header, footer, or sidebar that need to change based on language, but that aren't coming from the database. For instance, you might have a banner image, a navigation section, or other HTML, and you want to have a different version for each language. Here is an example of how to make this work -- you can adapt it for as many languages as you need:
<?php
global $langswitch_lang_pref;
if( $langswitch_lang_pref == 'en' ) {
?>
(put the HTML for English here)
<?php
} else if( $langswitch_lang_pref == 'es' ) {
?>
(put the HTML for Spanish here)
<?php
} else if( $langswitch_lang_pref == 'it' ) {
?>
(put the HTML for Italian here)
<?php
}
?>