Translate WordPress Themes Using Poedit

Poedit is a good tool for a small, controlled translation job: you have a theme that already supports WordPress translations, and you want to change labels such as “Read more” or “Search results.” It is a poor fix for a theme whose strings were never made translatable. Before you spend an afternoon translating, check that distinction. It determines whether the job is editing a catalog or changing theme code.

Check whether the theme can be translated

Open the theme’s style.css file and look for its Text Domain header. The domain should match the theme slug. Then check the theme’s languages folder for a .pot template. A missing POT file does not prove the theme is impossible to translate, but it means you need to extract its strings before Poedit has a useful starting point. WordPress’s Theme Handbook explains the text domain and translation file locations.

The decisive test is in the code. A label written as esc_html__( 'Read more', 'my-theme' ) can be found by WordPress translation tools. Plain hard-coded text cannot. If the theme is full of hard-coded labels, ask the developer to internationalize it or choose a better-maintained theme. Translating a few visible strings with search-and-replace will break at the next update.

Create the translation in Poedit

1. Confirm the active locale. In WordPress, check Settings → General → Site Language. The file name must match the locale WordPress uses, such as de_DE for German (Germany). A language switcher may use separate locale settings, so check that plugin too if the site serves several languages.
2. Open the POT file in Poedit and create a new translation for the target language. If you maintain the theme yourself and no POT exists, the documented wp i18n make-pot command can generate one from the theme’s source.
3. Translate the entries in context. Do not change placeholders such as %s or %d, and check plural forms and strings with HTML. “Post” in a button may need a different translation from “post” in a sentence. Poedit can show source references when the POT contains them.
4. Save the PO file and compile the MO file. The PO file is the editable translation; the MO file is the compiled catalog WordPress loads for PHP strings. Keep both. WordPress’s localization documentation defines POT, PO, and MO files.
5. Put the files in the right place and test the site as a visitor. File naming differs by location, as shown below.

Where the files go

Those are two different naming schemes, not two spellings of the same path. WordPress documents both in the Theme Handbook. For a custom theme, make sure it loads its text domain from the intended directory. Themes distributed through the WordPress Theme Directory can use WordPress.org language packs without a manual load call.

Test the result before declaring it done

Change the site language, then check actual theme-owned labels on a normal post, an archive, search results, and a 404 page. Test a logged-out visit as well as the admin view. If one string remains in English, check its text domain in the theme code and whether the POT includes it. If every string remains in English, check the locale, file name, file location, and loading code first. Clear the page cache only after confirming the files themselves are correct.

Be careful with block themes and other themes that use JavaScript for interface text. PHP translations use the MO catalog; JavaScript translations use JSON files associated with a registered script. A PO/MO pair alone will not translate those strings. The Block Editor Handbook explains script translations.

Poedit, Loco Translate, or a multilingual plugin?

Use Poedit when you can work with theme files locally, review changes, and deploy them deliberately. Use a translation-management plugin if editors must change strings from the WordPress dashboard, but check where it stores custom files and how it handles updates. For a theme in the WordPress.org directory, contributing through its translation project may be more durable than maintaining a private copy.

Do not buy a full multilingual plugin just to rename a few theme labels. Conversely, do not mistake Poedit for a multilingual publishing system. It does not create translated posts, separate language URLs, translated SEO metadata, or hreflang relationships. If those are the requirements, choose the site’s multilingual workflow first and treat theme strings as one part of it.

My recommendation: keep Poedit for properly internationalized themes and small translation sets. If the theme fails the text-domain check, fix the theme before touching the catalog. That is less glamorous than installing another plugin, but it addresses the reason the strings do not translate.

Frequently asked questions