You are here: start » plugin_tutorial_i18n

Plugin Tutorial: Internationalization

To make the plugin useful for languages other than English, you should consider to add internationalization (i18n). Therefore create a folder languages/ in the plugin's folder, and create a file en.php with the following content and save it as UTF-8 without BOM.

$plugin_tx['visitors_online']['text']="Visitors online";

All plugins share a two-dimensional array $plugin_tx, which first index is the name of the plugin. You're free to choose any index you like as second one (as long as it contains printable ASCII characters only), but note that underscores will be replaced by spaces when displayed in the back-end. The first part of this second index will be used for grouping the language strings in categories; you should use this to provide the user with a better overview.

The language file will be automatically include()d by the pluginloader, so you can use the $plugin_tx without further preparation in the plugin. So change line 8 of index.php to

define('VISITORS_TEXT', $plugin_tx['visitors_online']['text']);


Now localization (l10n) is very easy. Just make a copy of en.php and rename it to de.php (use the ISO-639-1 language code in lower case instead of de for other languages than German). Then edit the file and translate the language variables. Of course you don't have to provide all translations for yourself. It's enough, if you provide one language (preferably english), so others could translate it for themselves.


Sometimes you need output which combines internationalized and fixed parts, the latter often dynamically retrieved from the context. Consider, that a file couldn't be written as expected and you want to report this to the user: “The file $FILENAME could not be saved!” Often you can work around this by rewording: “The following file could not be saved: $FILENAME”, but this is clumsy at best. Using two language strings (“The file” and “could not be saved!”) is no option, as other languages may use another syntax, so the localization will be even more clumsy.

Recommended solution: use a placeholder in the language string. You can use sprintf() to make constructing the final string easy:

sprintf('The file %s could not be saved!', $FILENAME)

If you want to make it clear to translators what the placeholder stands for, you may use str_replace():

str_replace('{{FILENAME}}', $FILENAME, 'The file {{FILENAME}} could not be saved!')


Sometimes you need language strings for varying numbers, e.g. “3 files have been uploaded.” When there was only one file uploaded it should read “1 file has been uploaded.” You can use a workaround like “Number of files uploaded: $x” or “$x file(s) has/have been uploaded”, but both are somewhat clumsy.

Recommended solution: use two language strings, one for the singular and another for the plural. But note, that there are languages with a third number, the paucal 1), which is used in Czech and Slovak for example. This number is used for two to four occurrences. I'm not sure, if there are other languages which have even other numbers, but for CMSimple_XH the following convention seems to suffice: use actually three language strings. One for singular (1), another one for the paucal (2-4) and yet another one for plural (5+ and 0).

« Introduction | Configuration »

I'm not sure if the name is correct
You are here: start » plugin_tutorial_i18n
Except where otherwise noted, content on this wiki is licensed under the following license: GNU Free Documentation License 1.3
Valid XHTML 1.0 Valid CSS Driven by DokuWiki