Skip to main content
WordPress uses three different types of files for managing translations:
  • .pot files contain a list of all translatable strings in the code. This file is a template only. It’s only purpose is to keep track of all translatable strings in the code.
  • .po files contain a list of translations for a particular language. They are generated from the .pot files.
  • .mo files are machine-readable versions of .po files. They are used by the software to output translations.

​
Languages and Locales

WordPress distinguishes between languages, like Portuguese, and locales, like Portuguese for Brazil. The distinction is done via the naming. Language files only contain the language code, in this case pt.po. Locale files contain the language and the locale code, so pt_BR.po. Correct naming is required for WordPress to find the correct translations. WordPress will look for the language file first, and then for the locale second.

​
Creating Translations

​
Create the .pot file

Generated themes will have a script in the package.json file to serve this purpose. All that script does is call a wp-cli command to create the .pot files for you. You can run npm run pot in your terminal.

​
Create the .po file

  • Start Poedit and click on “Create new” from the welcome menu.
  • Navigate to the generated .pot file and select it.
  • Poedit will ask you for the language of the translation. Select the language and locale you want to translate to.
  • Translate the strings
  • Save your .po file in the same folder as your .pot file. Usually this folder is called languages/. A .mo file should be generated automatically.

​
Translating JavaScript

In the past we would localize some strings in PHP so that they could be passed to the JavaScript files. Since WP 5.0 we can use the same translating functions like __() in JavaScript by using the i18n package from WordPress. Please follow these instructions to set it up. To make this easier for us, there’s another package.json script that will generate the .json files for us. This will look at all .po files and extract all strings that are in JavaScript files into .json files. The command is npm run pot:json.

​
Updating translations

  • Run the command to generate the .pot file again. This will update the file with new strings.
  • Open the desired .po file in Poedit.
  • Select File > Update from POT file. This will ensure your .po file gets the updates from the .pot file.
  • Translate strings
  • Save
If any changes were done to JavaScript strings, re-run the npm run pot:json command to update the json files.

​
Common issues

​
My translations not working

Check your textdomain. It is common to either forget to add a textdomain to your strings or to use the wrong textdomain. You should also check if your site(or your user profile) is using a different language then the translated language or locale.

​
All other translations work fine, except for mine

In Poedit, check if the string you are translating is not marked as “Needs Review”. Poedit will sometimes mark some strings as needing review so that an editor can confirm if the translation is correct. Strings that are under review are not used by WordPress.

​
My JavaScript translations are not working

Check if your .json file is following the correct naming convention. You can learn more about it here.