Main menu

Creating new WordPress translations in Loco Translate

Adding a language means asking Loco Translate to create a new set of Gettext files on disk.

1. Choose a language

The simplest way to choose a language is to select it from the list of languages WordPress knows about. If your language is not in the list (or if you just prefer) you can enter the locale code in the text field instead.

Note that if your language is not in the dropdown list under "Installed languages" you may not be able to switch WordPress to use this language. Switching language is beyond the scope of what Loco does, but see our short guide here if you need a starting point.

2. Choose a location

You'll be offered a choice of file locations in which to save your new files. This can be confusing if you're not familiar with WordPress localization, but the location you choose is important. The exact choices will depend on what you're translating, but they will always include one or more of the following four types:

  • Author (developer only)
    This location will be inside the folder where the theme or plugin is installed. Automatic updates will overwrite files in this location, so only save files here if you are the author or have a good reason for adding files directly to a bundle.

  • System (possibly unsafe)
    This location is under the global language installation directory (WP_LANG_DIR). Files saved here can be overwritten by WordPress's own language installer, so don't save files here unless you've disabled automatic translation updates.

  • Custom (recommended)
    This is Loco's protected folder under "wp-content/languages/loco/" which is safe from automatic updates and provides priority over the above locations. If this folder doesn't exist you may need to create it and ensure it has the correct permissions.

  • Other
    Some bundles may offer their own locations for custom translations, but we can't advise on how they are used. Please ask the bundle author how to work with any alternative locations you see here.

IMPORTANT: Avoid saving files in locations managed by WordPress updates. Your files may be overwritten or deleted. See FAQ.

A note about loading order

The location you choose is not only important in protecting your files from updates, but your choice also affects your file's priority over other translations you don't want.

This is a complicated topic, but briefly - when a plugin or theme asks WordPress to load a language file, it will always try to load the installed "system" translations first. Only when it doesn't find anything will it look in the language folder that the author defined.

Loco Translate forces its own safe location before these two standard attempts and always takes priority as long as the plugin is enabled. Thus WordPress would try to load translations in following order for the twentytwenty (theme) text domain.

  1. Custom e.g. wp-content/languages/loco/themes/
  2. System e.g. wp-content/languages/themes/
  3. Author e.g. wp-content/themes/twentytwenty/languages/

Loco Translate also deliberately allows WordPress to continue loading the "system" or "author" files. If it manages to load one of these, the translations will be merged into your custom strings. This means your strings take priority, but any missing ones will fall back to the file that would normally have been loaded. It's a feature, not a bug.

3. Template options

This section will only appear if you've chosen to copy an existing PO file rather than create a new one from the bundle's template.

  • Copy target translations
    Whereas a POT file will only contain source strings, a PO file will also have translations. This option will copy them into your new file. Avoid this option unless you're creating a file for the same (or very similar) language.

  • Just copy English source strings
    Choose this option to treat the PO file as if it was a regular template containing only source strings. This is the default option and should be used whenever the new file will contain a different language.

  • Use this file as template when running Sync
    This option ensures your new file "remembers" its template instead of updating from the bundle's official template in future. If your bundle is set up properly with a valid template you should leave this option OFF.

Warning: Use the copy features with care as they provide great scope for confusing yourself. Copying is useful for quickly duplicating languages, but not as a substitute for a proper translations template. If the bundle you're translating has a missing or invalid template, ask the author to fix the problem in their next release.