How to Translate a WordPress Theme (and Make It Multilingual)

Summarize this post with: 9 min read

ChatGPT Perplexity Grok Google AI

How you translate a WordPress theme depends on what you need. If your whole site will run in one language other than English, switch the Site Language under Settings → General and let WordPress download the theme’s language pack, or edit the theme’s .po/.mo translation files with a tool such as Loco Translate or Poedit. If you want visitors to choose between several languages, you need a multilingual plugin that translates the theme’s text and your content for each language, since theme translation files alone switch the whole site to one language.

Key takeaways

• Theme strings (buttons, labels, “Read more”, “Search results for…”) live in the theme’s code and are translated through a text domain and .po/.mo files.
• Themes from the WordPress.org directory get language packs automatically from translate.wordpress.org when you change the site language.
• Save custom translations where theme updates can’t overwrite them: wp-content/languages/themes/ or Loco Translate’s protected folder.
• Text that isn’t wrapped in translation functions can’t be translated by .po files. Fix it in a child theme, or use a tool that translates the rendered page.
• For a multilingual site, every language needs its own URL and hreflang. A .mo file doesn’t provide that.

First, which kind of “translate” do you need?

Most “how do I translate my theme” questions are really the third case, so the second half of this guide covers it. First, how theme translation works.

How WordPress theme translation works

A translation-ready theme wraps every visible string in a translation function with the theme’s text domain, a unique ID that matches the theme’s slug. The WordPress Theme Handbook’s example: a theme called Fabled Sunset uses the text domain fabled-sunset, declared in style.css as Text Domain: fabled-sunset (WordPress Developer Resources).

In the theme’s templates, strings look like this:

<?php esc_html_e( 'Read more', 'fabled-sunset' ); ?>
<?php echo esc_html( sprintf( __( 'Search results for: %s', 'fabled-sunset' ), get_search_query() ) ); ?>

Translations are stored in .po files (human-readable) and compiled to .mo files, which are the ones WordPress actually uses. The handbook lists two places WordPress looks for a theme’s translation, based on the site’s locale:

• wp-content/themes/your-theme/{domain-path}/{locale}.mo
• wp-content/languages/themes/{textdomain}-{locale}.mo

Since WordPress 6.5, translations can also be loaded from .l10n.php files, a faster PHP format that WordPress.org language packs now include. If only a .mo file exists, it still loads as before (Make WordPress Core).

Step 1: check whether your theme is translation-ready

1. Open the theme’s style.css and look for a Text Domain: line.
2. Look for a languages folder (or similar) containing a .pot template file.
3. Spot-check a template file: strings should be wrapped in functions such as __(), _e(), esc_html__() or esc_html_e(), each with the text domain.

If the theme has none of these, its strings are hard-coded and can’t be translated with translation files. Skip to “Fixing hard-coded strings” below, or to the multilingual section.

Step 2: try the language pack first

For themes hosted in the WordPress Theme Directory, the handbook notes you “do not need to load translations”: WordPress checks wp-content/languages and downloads translations from the Translating WordPress project.

1. Go to Settings → General and choose your Site Language.
2. Go to Dashboard → Updates and click Update Translations if prompted.
3. Visit the site. If the theme’s volunteers have translated it into your language, most strings will already be translated.

Premium themes bought elsewhere usually ship their own languages folder instead; check the theme’s documentation for included languages.

Step 3: edit or complete the translation

If strings are missing or you don’t like the wording, edit the translation files.

Option A: Loco Translate (inside WordPress)

Loco Translate “provides in-browser editing of WordPress translation files” and can save custom translations to a protected language directory, wp-content/languages/loco/themes, so theme updates don’t overwrite them (WordPress.org plugin directory).

1. Install and activate Loco Translate.
2. Go to Loco Translate → Themes and choose your theme.
3. Click New language, pick the language, and choose the Custom (protected) location.
4. Search for the string, type the translation and click Save. Loco compiles the .mo file for you.

Option B: Poedit (on your computer)

1. Download the theme’s .pot file (or the existing .po for your language).
2. Open it in Poedit, create a new translation for your locale, and translate the strings.
3. Save. Poedit writes both the .po and the compiled .mo.
4. Rename the files to {textdomain}-{locale}, for example fabled-sunset-de_DE.po and .mo, and upload them to wp-content/languages/themes/.

Don’t put custom files inside the theme folder: a theme update replaces that folder and your translations with it.

Fixing hard-coded strings

When a theme prints text directly (<a>Read more</a>), no translation file can reach it. Your options, from cleanest to quickest:

1. Ask the theme author to make the strings translatable. It helps every user of the theme.
2. Override the template in a child theme. Copy the template file into your child theme and wrap the string: esc_html_e( 'Read more', 'my-child-theme' );. Load your child theme’s translations with load_child_theme_textdomain() on the after_setup_theme hook, as the handbook shows.
3. Use a tool that translates the rendered page rather than the code, which picks up hard-coded text along with everything else.

A note for developers: since WordPress 6.7, WordPress warns when a theme or plugin loads translations too early, before after_setup_theme or init (Make WordPress Core). If you see a _load_textdomain_just_in_time notice after an update, the fix belongs in the code that loads the text domain.

Also remember what isn’t part of the theme: page and post content, menus you created, widget text, block patterns you edited, Customizer text and page-builder layouts are all stored in the database. Theme translation files don’t touch them.

Translating a theme for a multilingual website

A .mo file switches the language of the theme’s strings for the whole site. It can’t show German to one visitor and French to another, and it doesn’t translate your content. For a site in several languages you need three more things:

1. Every piece of text translated, including theme strings, menus, widgets, content and plugin output such as WooCommerce buttons and checkout.
2. A separate URL for each language, such as /de/ and /fr/. Google recommends different URLs for each language version rather than cookies or browser settings (Google Search Central).
3. Hreflang annotations linking the versions so search engines show the right one. See how to add hreflang tags.

How ConveyThis handles it

The ConveyThis plugin for WordPress (1,000+ active installs on WordPress.org, rated 4.4/5 from 145 ratings) translates the page WordPress renders, so the theme’s strings, hard-coded text, menus, widgets, content and plugin output are all translated together, with no .po files to maintain. It is useful when a theme isn’t translation-ready or when you’d rather not manage translation files per language.

In practice:

• Automatic first draft, then edits. Pages are machine-translated, and you refine any string in the visual editor, which shows it in place on the page, so you can see whether a translated button label still fits.
• Consistent terms. A glossary keeps brand and product names untranslated or translated the same way everywhere.
• SEO-ready URLs. Each language is served from its own subfolder or subdomain with translated meta titles and descriptions and automatic hreflang. You can also customize translated URLs.
• Exclusions. Keep specific pages or elements in the original language with exclusion rules.
• 210 languages, including right-to-left languages like Arabic and Hebrew.

The WordPress integration page covers installation, and the step-by-step help guide walks through setup. If performance is a concern on a larger site, see our guide to multilingual WordPress performance.

Troubleshooting: why a theme string won’t translate

• Wrong text domain. The domain in the function call must match the one in style.css and in the file name.
• Wrong file name or locale. de_DE is not de; the file must match the Site Language exactly.
• File in the wrong folder, or overwritten by a theme update.
• String not wrapped in a translation function (hard-coded).
• String comes from a plugin or the database, not the theme. Search the plugin’s translations, or edit the content itself.
• Caching. Clear page and object caches after changing translation files.

Frequently asked questions

How do I translate my WordPress theme into another language?

Set the Site Language under Settings, General, then update translations. If the theme has no language pack or you want different wording, create or edit its translation with Loco Translate or Poedit and save it in wp-content/languages/themes or Loco’s protected folder.

Where are WordPress theme translation files stored?

WordPress looks in the theme’s own language folder and in wp-content/languages/themes, using files named with the text domain and locale, such as fabled-sunset-de_DE.mo. Custom translations are safest outside the theme folder.

Will a theme update delete my translations?

Yes, if you saved them inside the theme’s folder. Store them in wp-content/languages/themes or Loco Translate’s protected directory instead.

Can I translate a theme that isn’t translation-ready?

Not with translation files. Either wrap the strings in translation functions in a child theme, or use a tool that translates the rendered page, such as ConveyThis.

Do .po and .mo files make my site multilingual?

No. They change the language of the theme’s strings for the whole site. A multilingual site needs content translation, a URL per language and hreflang, which is what a multilingual plugin provides.

Translate the whole site, not just the theme

If your goal is a site visitors can read in several languages, you can create a ConveyThis account, install the WordPress plugin and translate your theme and content together.