Custom translations

How to customize existing translations with Loco Translate

Many people install Loco Translate to change existing translations to something they like better. To avoid disappointment observe this very important rule:

DO NOT edit translation files that have already been installed by WordPress.

Files installed by WordPress can be modified or deleted by WordPress. If you make changes to system translations you may find that your hard work disappears overnight. There are ways to protect these files, but we recommend you use the following method instead.

Override translations in your own custom files

In this example we'll make some changes to the installed translations of the Twenty Seventeen theme. You can navigate to this theme by following the side bar and selecting it from the list: Loco Translate > Themes > Twenty Seventeen. You'll see something like this if you have at least one language installed:

A couple of things to notice here:

Our existing file shows "System" under the "Folder" column. That means it lives in a location that is managed by WordPress updates.
There's a link that says "Create template". This tells us that Twenty Seventeen doesn't have a POT file. We can get around this.

Advanced users might want to create a template, but there's a quicker way that will work well in this situation. Because we already have a valid set of translations we can just click "Copy". Hover over the language icon and the file menu will appear as shown above.

You can copy any language as long as your files are valid. They should all contain the same English source strings.

Choosing where to save the custom file

Clicking "Copy" brings us to the screen for adding a new language, except we will select the same language even though a file already exists. It's OK to have two copies of the same language. You'll see why in a moment.

Here are the important options to choose on this screen:

Select the "Custom" file location
A file already exists under "System" and we don't want to save our file inside the theme because we're not the "Author". The "Custom" folder under languages/loco is safe from WordPress updates. (Note all paths are relative to wp-content)
Just copy English source strings
It's not necessary to duplicate all the translations into your file. Any original text you don't override will still be used as a fallback.
Use this file as template when running Sync
This tells Loco Translate to use the original file to detect any changes in the theme's available strings. Effectively the system translations file will fill the role of the missing POT file.

With these options selected you can click "Start translating" and make any custom translations you wish in the Loco Translate editor. These will be safely held in your own custom file which WordPress should not touch during system updates. Your list of translations will now show the new file as follows:

You'll notice that your file is listed as "Custom" under the "Folder" column, and in addition to the "System" version. Both files will be loaded, but your custom strings will override. See our note about loading order for more on that topic.

Our example shows only 1% translated because that's all we customized. If you'd selected "copy target translations" in the options this would show 100%. You'd also have larger file with a lot of duplicated strings, so we recommend you don't copy all the translations unless you have good reason.

Theme updates

When WordPress updates the theme in future you may find your translations no longer correspond to the English text in the theme. Loco Translate won't automatically fix this for you, so when you know the theme has been updated you'll have to update your custom translations manually.

WordPress should automatically update the original System translations whenever it updates the theme, but check that's working before proceeding with the next step. You can download them yourself if you need to.

Now open your custom translations in the editor and click the "Sync" button. If any of the source strings have changed you'll see a summary like "2 new strings added. 1 obsolete string removed". Nothing will be saved yet, but the editor will be updated with the new changes. Make any changes you need to and click "Save".

A note about the custom folder

Loco Translate's "Custom" folder is located at wp-content/languages/loco. It works for this example because Twenty Seventeen is set up correctly and loads translation files using the proper WordPress functions. We can't say the same for every theme and plugin out there. If your files don't load from this location, please see this FAQ.

A note about commercial products

If you're translating a commercial product you'll probably find that installed translations show up as "Author" (meaning that they're shipped by the vendor). These can be copied in the same way as the System files described above, but please note that we can't offer any help troubleshooting commercial products if the above steps don't work. The most likely cause is that the product isn't internationalized to WordPress standards.