Translate your WordPress theme with the Loco Translate plugin

This guide will walk you through adding your own translations to a theme that has already been set up for translation.

Be aware that Loco Translate cannot control how themes are set up. The following steps are a best case example using a theme that is set up in the correct way. There is no guarantee that these steps are the right ones for your exact situation, but covering all possibilities would be too technical for a beginner's guide.

1. Get the theme

In this example we're going to add some translations to the open source theme Omega. We've chosen Omega because it's set up for translation properly and we know it will work. Omega is also the last letter in the Greek alphabet, which seems appropriate!

So download and install the Omega theme the way you normally do. We won't cover that part, we assume you already know how to install WordPress themes. You don't need to activate the theme yet. Just have it installed into "wp-content/themes" and we can move on.

2. Check you can switch language

Loco Translate isn't responsible for setting your WordPress language, but we'll cover this step because it's important. If you already know how to configure your WordPress language, you can skip on.

Head to the Settings > General admin screen and scroll to the bottom. You should see a dropdown list with the label "Site Language". Changing this will set a new default language for all site visitors. Try it and you should see something like this:

Continuing the theme of our example, we're going to set the language to Greek, listed under "Available > Ελληνικά" in the list. Once WordPress has downloaded the core language packs for Greek this entry will move to the "Installed" section.

If you don't see your language in the dropdown list you may have to install the core language packs manually.

You can set your site back to English now if you like. We'll be switching to Greek later on to check our custom translations are working, but the language setting isn't required while we add them.

3. Set up the folders

Before you do any translating, make sure the following folder exists on your site, and is writeable by the web server:

wp-content/languages/loco/themes

If you have automatic updates enabled then the "wp-content/languages" folder probably exists already. The "loco" subfolder is there to protect your custom translations from automatic translation updates. This is critical if you want to avoid your files being deleted behind your back.

Loco Translate also lets you save translations inside the theme's own folder, but this is provided for theme developers only. Files inside the theme folder will get deleted by WordPress updates, so don't save anything in there unless you know what you're doing. For more detail, see our guide to language folders.

If you're not familiar with changing file permissions see our guide to filesystem access, and ask your hosting provider or system administrator if you have any doubts.

4. Check the theme contains a POT file

Looking inside the Omega theme folder we can see a "languages" sub-folder containing a file called "omega.pot". This is a translation template provided by the theme author. It contains all the translatable phrases (or strings) that the theme defines.

If your theme has no template file, Loco Translate will warn you. In this case we know it exists, but just to be sure check it's at the following location:

wp-content/themes/omega/languages/omega.pot

Just knowing this exists is good enough for us right now. It doesn't need to be writeable unless you're the developer of the theme. For more detail, see our guide to working with templates.

5. Find the theme in the translation dashboard

If you haven't installed and enabled the Loco Translate plugin yet, do that now. This guide assumes you already know how to install and enable WordPress plugins.

Click the admin menu item that says "Loco Translate" and select the "Themes" sub section. This will take you to a list of all available themes in your WordPress. You should see "Omega" in the list regardless of whether it's your active theme. Click it and you should see the following screen:

If you have automatic updates enabled, you may see that WordPress has already installed language files for Omega in your language. Any such files will be community translations (indicated by the word "System" in the image above) but we'll ignore this for now because our example is all about doing your own translation.

Community translations will live quite happily along side your own custom files. In fact Loco Translate will allow your own translations to override, but fall back on them as needed.

6. Add a new language

Above the language list (which may be empty) you should see a button that says "New language" with an :add icon:. To start translating the theme into another language click this button and you'll be taken to a new screen where you can choose the language you want.

Select a language from the dropdown list of common languages. In this example we'll select 'Greek'. You could achieve the same result by entering "el" into the text field instead, but we won't talk about language codes right now.

If you've set up your folders correctly you should see a location marked as "Custom". You should select this so your new translations are safe from automatic updates. For more detail on folder locations, see our guide to adding new languages.

With the language and folder location selected, click the "Start translating" button and you'll be taken to the editor screen for translating the theme.

7. Translate some strings

Once on the editor screen you'll see all the strings the theme has defined in its template file. Untranslated strings are shown in bold blue. To start with they will all be untranslated.

The basics of the editor should be fairly intuitive. Select the English string at the top and enter your translation in the pane at the bottom. You can ignore most of the editor buttons for now. We're just going to enter a translation and save it.

For our example we've picked out the phrase "Leave a comment". Using the text filter at the top of the editor we can find this phrase quickly and select it in the list. Then we enter the text "Σχολιάστε" into the bottom pane as our translation.

The string at the top now shows a :star icon: to indicate that our changes are not yet saved.

Continue to translate as much as you like and when you're ready click the :Save icon: in the editor toolbar. Congratulations, you've saved your first WordPress translation.

8. Check the files exist

If everything has gone well, you now have Greek translation files on your server for the Omega theme. Take a look in the folder you set up earlier and you should see two new files:

wp-content/languages/loco/themes/omega-el.po
wp-content/languages/loco/themes/omega-el.mo

Checking they exist is good for our sanity and helps you see how it all works. The PO file is a human-readable source file. The MO file is the binary file that the Omega theme will ask WordPress to load.

Loco Translate has now completed its job. It has compiled a MO file and saved it to disk with the correct name. This is all it does. What happens next is down to WordPress and the theme.

9. Viewing the translated theme

Our new MO file will be loaded by the Omega theme (and only by the Omega theme) when the Greek language setting is active. So, let's check it works..

• If you didn't set your language earlier, do it now.
• If you didn't activate the theme earlier, do it now.

Head to a blog post on your site and check the sample phrase we translated earlier. We know where "Leave a comment" will appear - below the title of every post.

Great, it works.

That's the end of this beginner's example guide. There's a lot more to know about WordPress localization and more that Loco Translate can do to help. See the technical overview for more advanced workflow features and the manual for help with specific admin screens.

Troubleshooting

The Omega theme is known to work with Loco Translate, so if any of these example steps failed the problem could be due to some other part of your setup. We will try to help in the support forum if you provide enough information, but please read the FAQs before posting.