What is localization? #

Localization describes the subsequent process of translating an internationalized plugin. Localization is abbreviated as l10n (because there are 10 letters between the l and the n.)

Top ↑

Localization files #

POT (Portable Object Template) files #

This file contains the original strings (in English) in your plugin. Here is an example POT file entry:

#: plugin-name.php:123
msgid "Page Title"
msgstr ""

Top ↑

PO (Portable Object) files #

Every translator takes the POT file and translates the msgstr sections in their own language. The result is a PO file with the same format as a POT, but with translations and some specific headers. There is one po file per language.

Top ↑

MO (Machine Object) files #

From every translated PO file a MO file is built. These are machine-readable, binary files that the gettext functions actually use (they don’t care about .POT or .PO files), and are a “compiled” version of the PO file. The conversion is done using the msgfmt tool. In general, an application may use more than one large logical translatable module and a different MO file accordingly. A text domain is a handle of each module, which has a different MO file.

Top ↑

Generating POT file #

The POT file is the one you need to hand to translators, so that they can do their work. There are a couple of ways to generate a POT file for your plugin:

Top ↑

Plugin Repository Admin Tools #

If your plugin is registered in the official plugin repository, go to your “Admin” page there and then click on ‘Continue’ by the “Generate POT file” section.

Plugin Admin Area

Plugin Admin Area

Then simply click on Get POT to download the POT file.

Plugin Generate POT

Generate POT

Top ↑

WordPress i18n tools #

If your plugin is not in the repository, you can checkout the WordPress Trunk directory from SVN (see Using Subversion to learn about SVN). You need to checkout the whole trunk because the wordpress-i18n tools uses code from WordPress core to generate the POT. You need the gettext (GNU Internationalization utilities) package and PHP to be installed on your server/computer before you can run the below command.

Open command line and change the directory to the language folder.

cd theme-name/languages

You can run the makepot.php script in command line like this:

php path/to/makepot.php wp-plugin path/to/your-plugin-directory

After it’s finished you should see the POT file in the current directory.

Top ↑

Poedit #

There are a few other tools that can be used for generating a pot file. You can use locally Poedit. After generating the po file you can rename the file to POT. If a mo was generated then you can delete that file as it is not needed. The pro version allows you to create the po file with one click.
Poedit-Pro
If you don’t have the pro version you can easily get the Blank POT and use that as the base of your POT file. Once you have placed the blank POT in the languages folder you can click “Update” in Poeditor to update the POT file with your strings.

Top ↑

Grunt Tasks #

There are even some grunt tasks that you can use to create the POTs. grunt-wp-i18n & grunt-pot
To set it up you need to install node.js. It is a simple installation. Then you need to install grunt in the directory that you would like to use grunt in. This is done via command line. An example Grunt.js and package.json that you can place in the root of your plugin. You can the grunt tasks with a simple command in the command line.

Top ↑

WordPress Plugins #

You can use Codestyling Localization on your WordPress installation.

The POT and PO files can easily be interchangeably renamed to change file types without issues.

It is a good idea to offer the POT file along with your plugin, so that translators won’t have to ask you specifically about it.

Top ↑

Translate PO file #

There are multiple ways to translate a PO file.

You can use a text editor to enter the translation. In a text editor it will look like this.

#: plugin-name.php:123
msgid "Page Title"
msgstr ""

You enter the translation between the quotation marks. For the German translation it would look like this.

#: plugin-name.php:123
msgid "Page Title"
msgstr "Seitentitel"

You can also use Poedit when translating.

A third option is to use a online translation service. The general idea is that you upload the POT file and then you can give permission to users or translators to translate your plugin. This allows you to track the changes, always have the latest translation and reduce the translation being done twice.

François-Xavier Bénard is running WP-Translations, a community “where translators meet developers.” It is run on Transifex, you can submit projects for translation as a developer, or translate existing plugins and themes for your language. This is great as there are existing translators there.

Here are a few tools that can be used to translate PO files online:

You can even use WordPress plugins to do the translation.

The translated file is to be saved as my-plugin-{locale}.mo. The locale is the language code and/or country code you defined in the constant WPLANG in the file wp-config.php. For example, the locale for German is de_DE. From the code example above the text domain is ‘my-plugin’ therefore the German MO and PO files should be named my-plugin-de_DE.mo and my-plugin-de_DE.po. For more information about language and country codes, see Installing WordPress in Your Language.

Top ↑

Generate MO file #

Top ↑

Command line #

A program msgfmt is used to create the MO file. msgfmt is part of Gettext package. Otherwise command line can be used. A typical msgfmt command looks like this:

Unix Operating Systems

msgfmt -o filename.mo filename.po

Windows Operating Systems

msgfmt -o filename.mo filename.po

If you have a lot of PO files to convert at once, you can run it as a batch. For example, using a bash command:

Unix Operating Systems

# Find PO files, process each with msgfmt and rename the result to MO
for file in `find . -name "*.po"` ; do msgfmt -o ${file/.po/.mo} $file ; done

Windows Operating Systems
For Windows you need to install Cygwin first.

Create a potomo.sh

#! /bin/sh
# Find PO files, process each with msgfmt and rename the result to MO
for file in `/usr/bin/find . -name '*.po'` ; do /usr/bin/msgfmt -o ${file/.po/.mo} $file ; done

You can run this command in the command line.

cd C:/path/to/language/folder/my-plugin/languages & C:/cygwin/bin/bash -c /cygdrive/c/path/to/script/directory/potomo.sh

Top ↑

Poedit #

msgfmt is also integrated in Poedit allowing you to use it to generate the MO file. There is a setting in the preferences where you can enable or disable it.

Poedit Prefences MO

Top ↑

Grunt task #

There is grunt-po2mo that will convert all of the files.

Top ↑

Tips for Good Translations #

Top ↑

Don’t translate literally, translate organically #

Being bi- or multi-lingual, you undoubtedly know that the languages you speak have different structures, rhythms, tones, and inflections. Translated messages don’t need to be structured the same way as the English ones: take the ideas that are presented and come up with a message that expresses the same thing in a natural way for the target language. It’s the difference between creating an equal message and an equivalent message: don’t replicate, replace. Even with more structural items in messages, you have creative license to adapt and change if you feel it will be more logical for, or better adapted to, your target audience.

Top ↑

Try to keep the same level of formality (or informality) #

Each message has a different level of formality or informality. Exactly what level of formality or informality to use for each message in your target language is something you’ll have to figure out on your own (or with your team), but WordPress messages (informational messages in particular) tend to have a politely informal tone in English. Try to accomplish the equivalent in the target language, within your cultural context.

Top ↑

Don’t use slang or audience-specific terms #

Some amount of terminology is to be expected in a blog, but refrain from using colloquialisms that only the “in” crowd will get. If the uninitiated blogger were to install WordPress in your language, would they know what the term means? Words like pingback, trackback, and feed are exceptions to this rule; they’re terminology that are typically difficult to translate, and many translators choose to leave in English.

Top ↑

Read other software’s localizations in your language #

If you get stuck or need direction, try reading through the translations of other popular software tools to get a feel for what terms are commonly used, how formality is addressed, etc. Of course, WordPress has its own tone and feel, so keep that in mind when you’re reading other localizations, but feel free to dig up UI terms and the like to maintain consistency with other software in your language.

Top ↑

Using Localizations #

Place the localization files in the language folder, either in the plugin languages folder or as of WordPress 3.7 in the plugin languages folder normally under wp-content. The full path would be wp-content/languages/plugins/my-plugin-fr_FR.mo.

Set WPLANG inside of wp-config.php to your chosen language. For example, if you wanted to use french, you would have:

define ('WPLANG', 'fr_FR');

Top ↑

Resources #