Check out the video above for a visual explanation of this system. The information is mostly the same as the article below.
Loco Translate is a WordPress plugin that lets you edit the software translations inside WordPress. It has no effect on the content of the site, like pages, posts, and widgets, but is instead used to translate the interface added by plugins. For example, we can use it to translate the tools added to the post editor by the Global Voices plugin.
We use Loco Translate when the language of the site, including the backend wp-admin isn't in English, to ensure that all the tools in the site use the same language.
Most of the time we shouldn't need to use Loco Translate on Global Voices WordPress sites, but when we do, we should follow the guidelines below to avoid ever losing our work!
The Loco Translate plugin being used to translate the Global Voices plugin.
Contents
“GV Theme Translator” v. Loco Translate
A special thing about the Global Voices websites, compared to most WordPress sites, is that we have have another tool, the Theme Translator, that is used in a similar way.
The GV Theme Translator is intended to control all “public-facing” aspects of the site, and has the benefit of working even when the site's main language is set to English, as is the case with many Lingua translation sites, where the backend is in English but the frontend isn't. One effect of this is that elements translated by the GV Theme Translator don't honor the language set in your WP user profile settings, just like they don't honor the site's language set in the WordPress General settings.
In contrast, Loco Translate controls the “default” translation system used in WordPress, so any translations made with it will only apply to the “active language”, which defaults to the site's admin language, but can also be controlled by users in their personal profiles.
Because the two tools use different translation “systems”, any given string can only be translated using one or the other. When in doubt, try the GV Theme Translator (Appearance > Theme Translator) first, then if the string isn't there, investigate if using Loco Translate can solve your problem.
Note that some strings, whether in the GV Plugin/Theme or in third-party themes, just aren't set up to be translated, in which neither of these tools will work.
In the long run, GV should switch entirely to using the “default” system controlled by Loco Translate, rather than our “custom” Theme Translator, but for the time being there's no plan to make that migration.
Takeaway: The GV Theme Translator is set up to control most publicly-visible parts of the site and is disconnected from the “language” setting of the site or user. Loco Translate controls the translation across the entire site, and honors the language setting of the site and users.
Using Loco Translate to customize strings without translating
Another use of Loco Translate is to customize the translation of a plugin or theme, even if the string already exists in the correct language. This can be useful when we want a plugin to describe something a different way, but it doesn't offer a setting to control that piece of text.
If the text is correctly set up for translation, we can use Loco Translate to create a “custom translation” of the plugin that just updates the text to be what we want.
The process to use Loco Translate to “customize” rather than “translate” text is straightforward: Follow the same instructions below as if you were translating, just make sure the language you select to “translate into” is the same as the one the site is running. Your “custom translation” will act as an override of the default version of the text.
Recommended Loco Translate Workflows
Enabling Loco Translate
Activating the plugin can require up to two steps:
⚠️ If the Loco Translate menu item doesn't show at the bottom of the main wp-admin sidebar menu then the plugin is probably not enabled. An adminstrator-level user can enable the plugin on the Plugins screen.
⚠️ If you see the following error while creating a new translation, contact the GV Tech Lead (i.e. Jer), who needs to update the filesystem on the server for that site: Write protected: Creating this file requires permission.
Adding a new “Loco” translation
- Log in to
wp-adminand click on Loco Translate at the bottom of the dark sidebar. - Click the theme or plugin you want to translate, e.g. “GV Plugin”
- Click on New Language
- For “Choose a language”, select one of the default “WordPress Languages” if possible.
- For “Choose a location”, leave it on the default under
languages/loco/, for examplelanguages/loco/plugins/gv-plugin-{locale}.po - Click Start Translating
- Add translations of the strings you want to change.
- Click Save near the top to save your changes.
Following these steps, especially with regard to the location of the saved files, will ensure your changes aren't lost if the plugin or theme is updated.
Updating an existing “Loco” translation
- Log in to
wp-adminand click on Loco Translate at the bottom of the dark sidebar. - Click the theme or plugin you want to translate, e.g. “GV Plugin”
- Existing translations show near the top, and you can click the language names to edit them.
Making a “Loco” translation permanent
- Once a translation is complete it will be active on the site where it was created, but not necessarily on all other GV sites.
- To make a plugin's translation apply to all sites automatically, contact the GV Tech Lead (i.e. Jer) with a request. The process involves direct server management.
Tips when translating in Loco Translate
- If you are adding a translation of the plugin into a new language, try to translate all of the strings. Some of them may show only rarely to visitors, but strings like errors are very important when they do come up.
- When you encounter strings with parts that look like
%1$sor%2$s, be careful to leave them in place! These are “replacements” where custom data or HTML will be inserted. - There is often a special note for translators just above the Source text, that starts with
ℹ️Translators:. Read these messages carefully to understand how the string will be used, and especially what replacements like%1$swill end up containing.
