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

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

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. http://php.net/manual/en/intro-whatis.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:

__('message') 
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'.
_e('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 WordPress.org Plugin Directory https://wordpress.org/plugins/ 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.

Top ↑

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 ↑

JSON files

Starting from WordPress 5.0, JavascriptJavaScript JavaScript or JS is an object-oriented computer programming language commonly used to create interactive effects within web browsers. WordPress makes extensive use of JS for a better user experience. While PHP is executed on the server, JS executes within a user’s browser. https://www.javascript.com/. components are translated using jsonJSON JSON, or JavaScript Object Notation, is a minimal, readable format for structuring data. It is used primarily to transmit data between a server and web application, as an alternative to XML. files. Inside the Javascript code, similar translation functions as in PHP code. These stringsString A string is a translatable part of the software. A translation consists of a multitude of localized strings. are automatically extracted and made available for translation on the translate.wordpress.orgtranslate.wordpress.org The platform for contributing to the translation of WordPress core, themes and plugins. site. When a language pack or a localized installation package is created, the translations for Javascript functions are included as json files.

Top ↑

Localization parameters

The translation projects for each localeLocale Locale = language version, often a combination of a language code and a region code, for instance es_MX denotes Spanish as it’s used in Mexico. A list of all locales supported by WordPress in https://make.wordpress.org/polyglots/teams/ contain a few parameters that should never be “translated,” but rather adjusted to the specifics of the target language. The most important ones are marked as “high prio” and are located in the main core translation and in the “admin” part and can be found by sorting the translation strings in descending priority order.

sorting screenshot
In main core translation and core/admin translation you can find the localization parameters by clicking “sort ↑”, selecting “Priority”, “Descending” and then hitting the button “Sort”

Top ↑

How to “translate” various parameters

screenshot
Localization parameters in the “Admin” subproject

In the Admin area, you’ll currently (November 2019) find the following parameters:

  • 0 default GMT offset or timezone stringString A string is a translatable part of the software. A translation consists of a multitude of localized strings. – Pick a suitable “TZ database name” from https://www.php.net/manual/en/timezones.php, for instance “Asia/Seoul” if you’re translating to Korean.
  • 1 start of week – If the target locale uses Sunday as first day of week, then this parameter should be translated as ”0”. ”1” denotes Monday, and ”6” – Saturday.
  • Continue – This is not a parameter, but must be normally translated . During installation of WordPress or when a user changes the language of their installation, it is used on the button to confirm the language chosen.
screenshot
Screenshot of localization parameters in main translation project

In the main translation project, you’ll encounter the following parameters:

  • Noto Serif:400,400i,700,700i Google Font Name and Variants – Use this to specify the proper Google Font name and variants to load that is supported by your language. Check in https://fonts.google.com/specimen/Noto+Serif if Noto Serif will work well in your target language. In that case you can just copy the source string. Set to “off” to disable loading.
  • Comment number declension: on or off off – This should only be “translated” to on or off where “on” means that declension should be used for the number of comments.
  • html_lang_attribute – Translate this to the correct language tag for your locale, see https://www.w3.org/International/articles/language-tags/ for reference. Do not translate into your own language.
  • off decline months names: on or off – If months in your language require a genitive case, translate this to “on”. Do not translate into your own language.
  • on Open Sans font: on or off – If there are characters in your language that are not supported by Open Sans, translate this to “off”. Do not translate into your own language. See https://fonts.google.com/specimen/Open+Sans
  • ltr text direction – Must be “translated” as either “rtl” or “ltr”. This sets the text direction for WordPress.
  • Unicode points 8216, 8217, 8220, 8221 – WordPress includes functions that allows localization of quotation marks. If your target locale as standard uses other quotation marks than en_US, then you can indicate here what to use.
  • number_format_thousands_sep – See https://www.php.net/number_format. If your language, like en_US, uses a comma as thousands separator, then you should translate this as “,”. Then the numeric value 1234 would be formatted as 1,234. If your target language uses a different separator (for example a non-breaking space), then you’d enter that here.
  • number_format_decimal_point – See previous paragraph for reference. This is the decimal separator for your target language. In en_US a decimal point “.” is used to separate the decimal part of a value.

Top ↑

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. Below is explained why that is the case, and how to localize those components of WordPress.

Top ↑

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 others’ use. 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 wordpress.org released code are all centrally managed through SVN. https://subversion.apache.org/. source code repositoryWordPress Localization Repository The WordPress Localization Repository at https://i18n.svn.wordpress.org/ 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 that may need direct translation

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

Top ↑

Translate:

  • readme.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. – 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.
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:

dist/wp-config-sample.php:

[...]
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

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

Last updated: