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/twentytwenty-xx_XX.mo
2. System e.g. wp-content/languages/themes/twentytwenty-xx_XX.mo
3. Author e.g. wp-content/themes/twentytwenty/languages/xx_XX.mo

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 default template.

• Copy target translations
  A POT file will contain only source strings, but a PO file will also have translations. This option will copy those translations into your new file along with the source strings. 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.

• Merge strings from related JSON files
  Enabling this causes Loco Translate to look for additional strings in JSON files used by wp_set_script_translations. This is only required if you know that script translations have been purged from the PO file. See our notes on JSON translation files.

• Use this file as template when running Sync
  Select this to ensure the new PO file "remembers" these settings. Otherwise future Sync operations will use the default method and sync to the bundle's configured POT file instead.