WordPress Development

Internationalising WordPress Plugins and Themes

Internationalising WordPress Plugins and Themes

When I first published plugins, I wrote every message, label and button text directly in English. It seemed fine until users started asking whether they could translate the interface, and multilingual site owners couldn’t use my plugin on their non-English pages. Going back and internationalising everything took far longer than doing it properly from the start would have.

Internationalisation, often shortened to i18n, means preparing your code so its text can be translated into other languages. Localisation, or l10n, is the actual translation. As a developer, your job is internationalisation: wrapping strings in the right functions, so translators and translation systems can do the rest.

WordPress has excellent internationalisation tools. Here’s how to use them correctly in plugins and themes.

Why it matters

  • WordPress is used worldwide, and a large share of sites run in languages other than English.
  • Multilingual sites need every visible string to be translatable.
  • Translation communities translate popular plugins and themes into many languages, for free, through WordPress.org, but only if strings are internationalised.
  • It’s expected. Plugins and themes in the WordPress.org directories are expected to be translation-ready.

The text domain

Every translatable string is associated with a text domain, a unique identifier for your plugin or theme. It should match your plugin or theme slug, the folder name.

Declare it in your plugin header or theme’s style.css:

Use exactly the same text domain in every translation function call, as a plain string, not a variable or constant. Translation tools scan your code for these strings, and they can’t read variables.

The core translation functions

Returning and echoing translated strings

Translating with escaping

Most output should be escaped. Use the combined functions:

Using escaped variants protects against translations that contain unexpected HTML, whether by accident or malice.

Context

The same English word can mean different things. “Post” can be a noun or a verb. “Order” can mean a purchase or a sorting direction. Translators need to know which. Use _x to provide context:

Plurals

Languages handle plurals differently. Some have one plural form, others several. Never build plurals yourself with simple conditions. Use _n:

WordPress chooses the correct form for the language, including languages with multiple plural forms.

For plurals with context, use _nx.

Placeholders and translator comments

Never build sentences by concatenating translated fragments:

Instead, use placeholders with sprintf or printf, so translators can move variables to the right position:

For multiple placeholders, use numbered placeholders, so translators can reorder them:

The translators comment, placed directly above the function call, appears in translation tools and explains what each placeholder represents. Always add one when using placeholders.

Strings with HTML

Avoid putting HTML inside translatable strings where possible. When you must, such as for a link inside a sentence, keep markup minimal and escape carefully:

Allowing only specific tags with wp_kses prevents translations from introducing unexpected markup.

What not to translate

  • Variables and dynamic content: only literal strings can be translated.
  • Technical identifiers, like option names, CSS classes and hook names.
  • User-generated content, like post content, which multilingual plugins handle separately.
  • Strings in log messages meant only for developers, unless you want them translated.

JavaScript translations

Modern plugins and blocks include JavaScript with user-facing text. WordPress provides translation functions for JavaScript through the @wordpress/i18n package:

To load translations for a script, tell WordPress the script uses translations:

For blocks registered through block.json, WordPress handles script translations when the textdomain is set in block.json.

JavaScript translations use JSON files generated from your translation files.

Generating translation files

Translation files come in several formats:

  • POT: a template containing all translatable strings, generated from your code.
  • PO: a translation for a specific language, editable by translators.
  • MO: a compiled binary version of a PO file that WordPress loads.
  • JSON: translations for JavaScript strings.
  • PHP translation files: since WordPress 6.5, translations can also be stored in PHP files, which load faster.

WP-CLI generates them:

Run make-pot whenever you add or change strings, and include the POT file in your plugin or theme for translators.

Loading translations

For plugins and themes hosted on WordPress.org, WordPress loads translations from translate.wordpress.org automatically, and since WordPress 4.6, you generally don’t need to call load_plugin_textdomain for that.

For plugins and themes distributed elsewhere, or with bundled translations, load the text domain yourself, at the appropriate time:

For themes, use load_theme_textdomain in after_setup_theme.

Recent WordPress versions warn when translations are loaded too early, before the init action. Avoid calling translation functions at the top level of plugin files, before WordPress is ready.

Translating through WordPress.org

If your plugin or theme is on WordPress.org, volunteers can translate it on translate.wordpress.org. Language packs are delivered automatically to users. Make sure your strings are clear, consistent and well commented, and translators will thank you.

Right-to-left languages

Languages like Arabic and Hebrew are written right to left. Make your CSS work in both directions:

  • Use logical CSS properties, like margin-inline-start instead of margin-left, where possible.
  • Provide RTL stylesheets if needed; WordPress can load them automatically for RTL languages.
  • Test your layouts with an RTL language.

Common mistakes

  • Using a variable or constant as the text domain.
  • Concatenating translated fragments instead of using placeholders.
  • Missing translator comments for placeholders.
  • Building plurals manually.
  • Translating strings too early, before init.
  • Forgetting to escape translated output.
  • Different text domains in different files.

Retrofitting an existing plugin

If you have an existing plugin full of hard-coded English strings, internationalising it is tedious but straightforward. Work file by file. Search for strings in echo statements, labels, button text, admin notices and error messages. Wrap each in the appropriate function, adding escaping and translator comments as you go. Replace concatenated sentences with placeholders. Then generate a POT file and review it: every user-facing string should appear, and none should appear twice with slightly different wording.

A useful check is to install a pseudo-translation, which replaces every translated string with modified text. Browse your plugin’s screens, and any strings that still appear in normal English were missed.

Consistency helps translators

Use consistent terminology across your plugin. If one screen says “booking” and another says “reservation” for the same thing, translators must guess whether they mean different concepts. A short glossary of key terms, shared with translators, makes translations more accurate and consistent.

Avoid ambiguity

Short, isolated strings like “Open”, “Post” or “Free” are difficult to translate without context. Add context with _x, or rewrite the string to be clearer. Translators work through long lists of strings without seeing your interface, so every hint helps.

Dates, numbers and currencies

Translation isn’t only about words. Use WordPress functions like date_i18n or wp_date and number_format_i18n to format dates and numbers according to the site’s locale, rather than hard-coding formats. Different countries write dates and decimal separators differently, and getting these right is part of making a plugin feel native.

Test with a real language

After internationalising, install a translation, even a partial one, and browse your plugin’s screens in that language. Longer translated strings often break layouts designed only for English, and seeing your interface in another language quickly reveals missed strings, awkward concatenations and buttons that overflow. Fixing these early saves your translators and users frustration.

Encourage contributions

If your plugin is on WordPress.org, mention in your readme that translations are welcome and link to its translation page. Thank translators in changelogs. A small, friendly community of translators can bring your plugin to many more users than you could reach alone.

Make it part of your workflow

Add POT generation to your build or release process, so the template always matches the current code. Translators then work from accurate strings with every release, and nothing new slips through untranslatable.

Consistent habits make internationalisation effortless over time.

Translators will notice the care you take.

Frequently asked questions

Do I need to internationalise if my site is only in English?

For custom site-specific code, it’s optional, though good practice. For plugins and themes distributed to others, it’s expected.

What’s the difference between internationalisation and localisation?

Internationalisation prepares code for translation. Localisation is translating it into a specific language.

Why aren’t my JavaScript strings translated?

Make sure you call wp_set_script_translations, or set the textdomain in block.json, and generate JSON translation files.

Can I use a variable for the text domain?

No. Translation tools scan for literal strings. Always write the text domain as a plain string.

Final thoughts

Internationalising your code is a small habit with big benefits. Use a consistent text domain matching your slug, wrap every user-facing string in the right function, escape output, provide context and translator comments, use placeholders instead of concatenation, handle plurals with _n and support JavaScript translations. Generate a POT file and load translations correctly. Your plugins and themes will be ready for users and translators around the world.