Working with WordPress Core

[This page will discuss some of the basics of working with WordPress coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress., 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 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 localizationLocalization Localization (sometimes shortened to "l10n") is the process of adapting a product or service to a particular language, culture, and desired local "look-and-feel." 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.

Top ↑

Localization Technology 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 sourceOpen Source Open Source denotes software for which the original source code is made freely available and may be redistributed and modified. Open Source **must be** delivered via a licensing model, see GPL./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 PHPPHP PHP (recursive acronym for PHP: Hypertext Preprocessor) is a widely-used open source general-purpose scripting language that is especially suited for web development and can be embedded into HTML. 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 PluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the Plugin Directory or can be cost-based plugin from a third-party, 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 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 filePOT file POT files are the template files for PO files. They will have all the translation strings left empty. A POT file is essentially an empty PO file without the translations, with just the original strings.) 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.

Top ↑

Files for Direct Translation 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.

Top ↑

Where Gettext doesn’t work 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 HTMLHTML HTML is an acronym for Hyper Text Markup Language. It is a markup language that is used in the development of web pages and websites. file, not a PHP file.
  • A few error messages are generated very early in the WordPress loading cycle, before gettext is loaded.

Top ↑

Internationalizing Non-gettext Components 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 releaseRelease A release is the distribution of the final version of an application. A software release may be either public or private and generally constitutes the initial or new generation of a new or upgraded application. A release is preceded by the distribution of alpha and then beta versions of the software. 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 SVNSVN Apache Subversion (often abbreviated SVN, after its command name svn) is a software versioning and revision control system. Software developers use Subversion to maintain current and historical versions of files such as source code, web pages, and documentation. Its goal is to be a mostly compatible successor to the widely used Concurrent Versions System (CVS). WordPress core and the released code are all centrally managed through SVN. source code repositoryWordPress Localization Repository The WordPress Localization Repository at is a Subversion repository where official WordPress translations are maintained. See Working with the Translation Repository for details. and offers even greater detail on version numbers.

Top ↑

List of Files to Translate List of Files to Translate

Below is the list of files that need to be translated manually.

Translate: Translate:

  • 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-config-sample.php – See below for instructions on how to translate this file manually.

Top ↑

wp-config-sample.php wp-config-sample.php

Translate the instructions in the PHP comments (so that they can be used by non-English speakers)

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',    'вашата супер-ултра-уникална фраза сложете тук');
define('NONCE_KEY',        'вашата супер-ултра-уникална фраза сложете тук');
define('AUTH_SALT',        'вашата супер-ултра-уникална фраза сложете тук');
define('SECURE_AUTH_SALT', 'вашата супер-ултра-уникална фраза сложете тук');
define('LOGGED_IN_SALT',   'вашата супер-ултра-уникална фраза сложете тук');
define('NONCE_SALT',       'вашата супер-ултра-уникална фраза сложете тук');

Top ↑

Do not translate Do not translate

  • license.txt – This should be kept in place for legal reasons. A translated version can be added to the archive.