How to translate a WordPress child theme with Loco Translate

We're often asked if Loco Translate can be used to translate child themes. The answer is "Yes", but if you're creating the child theme yourself there are plenty of places to go wrong and some common misconceptions about how child themes should be translated.

A common assumption is that child theme translations work like PHP templates. You may expect that by copying translation files from your parent theme that they will be used by your child theme instead. Unfortunately, this is not how WordPress localization works.

Overriding parent theme translations

If you need to override some existing strings in the parent theme, then you should translate the parent, and leave the child theme alone.

Within Loco Translate, navigate to the parent theme and create your own custom language file. If there's already a language file installed, you can create a custom file containing only your overridden translations. See notes on loading order.

If your parent theme isn't loading translations at all, then your child theme is probably not the problem. See the most commonly asked questions.

Overriding English source text

To change the default English text, follow the steps above and create a translation file in the en-US locale. If your parent theme is set up correctly this will load and replace the English text with your versions. You don't have to modify the whole file, just edit the strings you want to be different.

Important: Do not edit the translation template to change English strings. This will not do what you expect. Treat custom English text as "translations".

Adding your own translatable strings

If the above sections don't cover your use case then perhaps you need to add your own translatable strings, i.e. words and phrases that do not exist in the parent theme. This is much more advanced and will require coding.

Child themes aren't automatically internationalized just because your parent theme is. The process is much the same as creating a theme from scratch. If you want to add new translatable strings to your own child theme, follow these recommended steps:

1. Understand child theme PHP templates

You will only be adding PHP code into child theme files, so ensure you know how to add template files. Never edit files in your parent theme.

Important: PHP templates are not to be confused with POT templates.

2. Understand WordPress internationalization

Introduce yourself to the basics of internationalizing a theme. (basically, preparing your PHP code to be translatable). Your parent theme isn't going to do much to alleviate the need for this knowledge. Any new strings you add have to be declared in the code.

By this point you should know what a text domain is, and how to print a translation from a PHP template.

3. Use a separate text domain for the child theme

Child themes should declare and use a separate text domain from the parent theme. The name of the text domain should match the name of its folder. If it doesn't match the folder you can declare it in style.css but it must be different from the parent theme's text domain.

Although it's physically possible for your parent and child to share the same text domain, this is against WordPress standards and you'd have to configure Loco Translate specially to work this way. We won't cover that here. Just ensure your parent and child are using their own unique text domains according to their respective folders.

4. Add additional strings into your source code

It's perfectly fine for child themes to use strings that exist the parent theme, but any additional strings must be in the child theme's own text domain. The following is perfectly valid in a child theme PHP template:

echo __("Comments are closed.","twentyseventeen"); // <- parent's text domain
echo __("Sorry old chap","twentyseventeen-child"); // <- child's text domain

You can see from this example that although translations are namespaced uniquely, any bit of code can reference any text domain it likes. There's no inheritance or sandboxing, they're just groups of strings loaded into WordPress.

5. Create translation files for the child theme

Once you've added your own strings to the source code you can use Loco Translate to extract them into a POT file. You can then add your own language files and translate as needed. If you're new to that part, see the beginner's guide.

There are several places you can choose to save your files. If you're the author of the child theme, then saving them inside the child theme's folder is probably fine. Otherwise we recommend you use Loco Translate's "safe" folder. See choosing a location.

6. Ensure your text domain is loaded at startup

Since version 4.6, WordPress will attempt to automatically load your translation files. However, for reasons we won't go into here we recommended you perform the loading yourself.

Loading the files is another thing your parent theme isn't going to do for you. In your child theme's functions.php file add some initialization code like this:

function twentyseventeen_child_setup() {
    $path = get_stylesheet_directory().'/languages';
    load_child_theme_textdomain( 'twentyseventeen-child', $path );
}
add_action( 'after_setup_theme', 'twentyseventeen_child_setup' );

The $path parameter refers to a "languages" folder within your theme where you might have saved your translation files. If you leave this parameter out WordPress will look in your theme root. However, don't set this path to anything outside your theme folder. WordPress will always look in the global languages directory for translations and will only use this path if it doesn't find any.