Localization

What is localization? What is localization?

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

Top ↑

Localization files Localization files

POT (Portable Object Template) files POT (Portable Object Template) files

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

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

The first line is a comment which normally is the file and line number of the string. The msgid line is the original string and msgstr section is where the translation comes in.

Top ↑

PO (Portable Object) files 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 language specific headers. There is one po file per language for a theme.

Top ↑

MO (Machine Object) files 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. There are a few different ways to convert po to mo files.

Top ↑

Generating POT file Generating POT file

The POT file is the one you need to hand to translators, so that they can do their work. 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 theme, so that translators won’t have to ask you specifically for it. There are a couple of ways of generating a POT file for the theme:

Top ↑

WordPress i18n tools WordPress i18n tools

You need to 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-theme path/to/your-theme-directory

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

Top ↑

Poedit Poedit

You can also use Poedit locally when translating. This is an open source tool for all major OS. The free Poedit default version supports manual scanning of all source code with Gettext functions. A pro version of it also features one-click scanning for WordPress themes. 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. 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 Poedit to update the POT file with your strings.

Poedit-Pro

Top ↑

Grunt Tasks 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 theme. You can the grunt tasks with a simple command in the command line.

Top ↑

WordPress Plugins WordPress Plugins

You can use Loco Translate on your WordPress installation. Note: this plugin may not be compatible with all themes. Your mileage will vary.

Top ↑

Translate PO file 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.

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

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

#: theme-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 theme. 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 {locale}.mo in the theme language folder. 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-theme’ therefore the German MO and PO files should be named de_DE.mo and de_DE.po. For more information about language and country codes, see Installing WordPress in Your Language.

Top ↑

Generate MO file Generate MO file

Top ↑

Command line 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-theme/languages & C:/cygwin/bin/bash -c /cygdrive/c/path/to/script/directory/potomo.sh

Top ↑

Poedit 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 Grunt task

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

Top ↑

Tips for Good Translations Tips for Good Translations

Top ↑

Don’t translate literally, translate organically 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) 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 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 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 Using Localizations

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

As of WordPress 4.0 you can change the language in the “General Settings”. If you do not see any option or the language that you want to switch to then do the following steps:

  • Define 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');
    
  • Go to wp-admin/options-general.php or “Settings” -> “General”
  • Select your language in “Site Language” dropdown
  • Go to wp-admin/update-core.php
  • Click “Update translations”, when available
  • Core translations files are downloaded, when available

Top ↑

Resources Resources