> ## Documentation Index
> Fetch the complete documentation index at: https://engineering.trewknowledge.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Translations

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](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-i18n/).

Please follow these [instructions](https://make.wordpress.org/core/2018/11/09/new-javascript-i18n-support-in-wordpress/) 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](https://make.wordpress.org/core/2018/11/09/new-javascript-i18n-support-in-wordpress/).