[This page will discuss some of the basics of working with WordPress core, including references back to the Core Contributor Handbook, and information on working with comments, placeholders, and other things that are specific to localizing WordPress.]
Using Localizations #
One of the first things you should know about working with WordPress core is how to actually use your own localized version.
To localize your installation of WordPress go to Settings > General > Site Language, select the desired language, and click the Save Changes button. The localization files will be downloaded into a directory named languages inside of wp-content and the localization will be available immediately.
To localize a Multi-Site installation or an older version of WordPress (v3.9.2 and below) follow the steps described on this Codex page.
Localization Technology #
WordPress’ developers chose to use the GNU gettext localization framework to provide localization infrastructure to WordPress. gettext is a mature, widely used framework for modular translation of software, and is the de facto standard for localization in the open source/free software realm.
Gettext uses message-level translation — that is, every “message” displayed to users is translated individually, whether it be a paragraph or a single word. In WordPress, such “messages” are generated, translated, and used by the WordPress PHP files via two PHP functions. __() is used when the message is passed as an argument to another function; _e() is used to write the message directly to the page. More detail on these two functions:
- Searches the localization module for the translation of 'message', and passes the translation to the PHP return statement. If no translation is found for 'message', it just returns 'message'.
- Searches the localization module for the translation of 'message', and passes the translation to the PHP echo statement. If no translation is found for 'message', it just echoes 'message'.
Note that if you are internationalizing a Theme or Plugin, you should use a “Text Domain”. See Writing a Plugin for more information on how to do this for a plugin; themes are similar. Example usage in a theme or plugin using “Text Domain”:
<?php $translated_text = __( 'text', 'domain' ); ?>
The gettext framework takes care of most of WordPress. However, there are a few places in the WordPress distribution where gettext cannot be used – see below where we list the files for direct translation for more information on how to translate these spots.
Gettext files #
There are three types of files used in the gettext translation framework. These files are used and/or generated by translation tools during the translation process, as follows:
- POT (Portable Object Template) files
- The first step in the localization process is that a program is used to search through the WordPress source code and pick out every message passed into a __() or _e() function. This list of English-language messages is put into a specially-formatted template file (POT file) that forms the basis of all translations. Generally, you can download a POT file for WordPress, so you shouldn’t have to generate your own. Separate POT files can also be made for themes and plugins, if the theme/plugin developer has enclosed all text in __() or _e() functions.
- PO (Portable Object) files
- The second step in the localization process is that the translator translates all the messages from the POT file into the target language, and saves both English and translated messages in a PO file.
- MO (Machine Object) files
- The final step in the localization process is that the PO file is run through a program that turns it into an optimized machine-readable binary file (MO file). Compiling the translations to machine code makes the localized program much faster in retrieving the translations while it is running.
Files for Direct Translation #
Although WordPress displays in U.S. English by default, the software has the built-in capability to be used in any language, or ‘localized’ (see WordPress in Your Language for more information). Most WordPress localization is performed using the Gnu gettext system (see above for more information). The gettext system runs text messages produced by WordPress PHP files through a look-up function, which finds and uses the non-English equivalent of a given word or phrase. This works well for most aspects of WordPress; however, there are a few components of the software that do not lend themselves to localization with gettext. This article explains why that is the case, and how to localize those components of WordPress.
Where Gettext doesn’t work #
There are some components of WordPress that cannot or should not be translated or localized with gettext:
- The main WordPress README file cannot be run through the gettext functions as it is a static HTML file, not a PHP file.
- A few error messages are generated very early in the WordPress loading cycle, before gettext is loaded.
Internationalizing Non-gettext Components #
To internationalize or localize components of WordPress that cannot use gettext, you will need to replace the English version of the files with a manually translated version. A list of the files you should translate is given below.
Note: Be careful of version conflicts if you plan to release your localized files for use by others. You will need to keep track of the version of WordPress that each file corresponds to, or release different versions of the files for different versions of WordPress. You can find a list of different WordPress versions in the Release Archive. Alternatively, you can check the Trac Browser, which allows you to browse the WordPress SVN source code repository and offers even greater detail on version numbers.
List of Files to Translate #
Below is the list of files that need to be translated manually.
- readme.html – This is a static HTML file, not a PHP file, and so cannot be run through gettext. The whole file must be translated.
- wp-admin/setup-config.php – This is a script that enables automatic generation of wp-config.php. It cannot be used with gettext as it runs independently of WordPress. The whole file must be translated.
- wp-config-sample.php – See below for instructions on how to translate this file manually.
Translate the instructions in the PHP comments (so that they can be used by non-English speakers), and set the WPLANG variable to the correct locale. For example, you would change define ('WPLANG', ''); to define ('WPLANG', 'bg_BG');if you were using the bg_BG locale.
Replace the text after each salt and key definition with a similar phrase in the desired language. For example, the Bulgarian file would look like this:
[...] define('AUTH_KEY', 'вашата супер-ултра-уникална фраза сложете тук'); define('SECURE_AUTH_KEY', 'вашата супер-ултра-уникална фраза сложете тук'); define('LOGGED_IN_KEY', 'вашата супер-ултра-уникална фраза сложете тук'); [...]
Do not translate #
- license.txt – This should be kept in place for legal reasons. A translated version can be added to the archive.