Plugins Plugin hub Backup SEO Caching Security Forms WooCommerce Images Best backup plugins
Hosting Hosting directory Shared hosting Managed WordPress Cloud hosting VPS hosting By reader location Hosting finder
Themes & builders Compare Rank Math vs Yoast
Tools All tools Hosting finder Plugin stack builder Cost calculator Salt generator Theme detector Who is hosting this? Speed test Headline analyzer robots.txt generator Redirect generator Uptime calculator Blog name generator
Blog Best backup plugins Deals
Guides All guides Speed up WordPress Choose hosting Back up WordPress
How we test

Developer · Guide

How to Make a WordPress Plugin Translatable

How to Make a WordPress Plugin Translatable

Short answer

To make a WordPress plugin translatable, wrap every user-facing string in a gettext function such as __() or _e(), using a text domain that matches the plugin slug. Use placeholders for variables, _n() for plurals, and _x() for words with more than one meaning. Then run wp i18n make-pot to build the template file for translators.

Key takeaways

  • Internationalization prepares strings for translation, while localization is the actual translation step.
  • The text domain must match the plugin slug, in lowercase with dashes and no spaces.
  • Use __() to get a translation and _e() to print it, always with the text domain.
  • Use %s placeholders with printf so translators can move values to the right place.
  • A language pack is generated once 90 percent of a plugin strings are translated and approved.

What does it mean to make a plugin translatable?

Making a plugin translatable means wrapping every user-facing string in a function that lets translators replace it with another language.

Internationalization, often shortened to i18n, is the first step: you prepare the code so strings can be translated later. Developer.WordPress.org states that localization, shortened to l10n, is the second step, where the text is actually translated and adapted to a language and culture (checked November 2026).

WordPress uses the gettext system for this work. Developer.WordPress.org states that you wrap each original string in a call to one of a set of special functions, known together as gettext (checked November 2026).

You do not translate the strings yourself. You mark them, and translators on translate.wordpress.org or in your own files provide the other languages.

StepWhat happensWho does it
Internationalization (i18n)Strings are wrapped in gettext functionsThe plugin author
Template file (POT)All marked strings are collected in one fileThe plugin author
Translation (PO)Translators write each string in their languageTranslators
Compiled file (MO)The PO file is compiled for WordPress to readThe build step

What is a text domain and why does it matter?

A text domain is a unique tag that tells WordPress which plugin a string belongs to, so translations from different plugins never clash.

Use a text domain to mark all text that belongs to your plugin. Developer.WordPress.org states that the text domain must match the slug of the plugin, using dashes and not underscores, in lowercase, with no spaces (checked November 2026).

If your plugin folder is called my-plugin, the text domain must be my-plugin. Developer.WordPress.org states that a plugin hosted on wordpress.org must use the slug part of its plugin URL (checked November 2026).

Add the text domain to the plugin header so WordPress can translate the plugin details even when the plugin is off:

/*
 * Plugin Name: My Plugin
 * Author: Plugin Author
 * Text Domain: my-plugin
 */

Since WordPress 4.6, the Text Domain header is optional because it must be the same as the plugin slug. Developer.WordPress.org states that there is no harm in adding it, but it is not required (checked November 2026).

The Domain Path header tells WordPress where the translation files live. Developer.WordPress.org states that a Domain Path of /languages points to a languages folder inside the plugin, and that the header can be left out for plugins in the official directory (checked November 2026).

A guide on how to create a WordPress plugin covers the header fields, including the Text Domain and Domain Path lines.

How do you wrap strings for translation?

Wrap each plain string in __() to get its translation, or in _e() to print it straight away.

For basic strings with no placeholders or plurals, use __(). Developer.WordPress.org states that __() returns the translation of its argument (checked November 2026).

__( 'Blog Options', 'my-plugin' );

To print the translation at once, use _e() instead of echoing __():

_e( 'WordPress is the best!', 'my-plugin' );

Add your text domain to every gettext call, or the translations will not work. Developer.WordPress.org states that a call such as __( 'Post' ) must become __( 'Post', 'my-plugin' ) (checked November 2026).

Never use a variable for the text domain. Developer.WordPress.org states that you should not pass a variable such as $text_domain as the domain, because the string extraction tools cannot read it (checked November 2026).

Even strings that WordPress core already uses, such as “Settings”, need your own text domain. Developer.WordPress.org states that they can become untranslated if the core string changes (checked November 2026).

How do you handle variables inside strings?

Keep variables out of the translated string and use placeholders with printf, so translators can move the value to the right place in their language.

A string with a variable in it, such as “Your city is $city.”, breaks translation. Developer.WordPress.org states that translators would see the phrase with the variable still in it, and the lookup would fail at run time (checked November 2026).

Use a %s placeholder and pass the value to printf:

printf(
    /* translators: %s: Name of a city */
    __( 'Your city is %s.', 'my-plugin' ),
    $city
);

The translators comment tells the translator what the placeholder holds. Developer.WordPress.org states that the comment must start with the words translators: and sit as the last PHP comment before the gettext call (checked November 2026).

With two or more placeholders, use numbered slots such as %1$s and %2$s. Developer.WordPress.org states that numbered slots let a translation swap the order, which some languages need (checked November 2026).

printf(
    /* translators: 1: Name of a city 2: ZIP code */
    __( 'Your city is %1$s, and your zip code is %2$s.', 'my-plugin' ),
    $city,
    $zipcode
);

Never split one sentence into small translated pieces. Developer.WordPress.org states that you should translate phrases and not words, and use format strings instead of joining pieces together (checked November 2026).

How do you handle plurals?

Use _n() with a singular form, a plural form, and the count, because many languages have more than two plural forms.

A string that changes with the number of items needs the _n() function. Developer.WordPress.org states that _n() takes four arguments: singular, plural, count, and text domain (checked November 2026).

printf(
    _n(
        '%s comment',
        '%s comments',
        get_comments_number(),
        'my-plugin'
    ),
    number_format_i18n( get_comments_number() )
);

Some languages use the singular form for numbers other than one, such as 21 or 31. Developer.WordPress.org states that the count passed to _n() picks the right form for each language (checked November 2026).

Use %s for the count inside the string, and write the singular as '%s item' rather than 'One item'. Developer.WordPress.org states that 'One item' fails in languages where the singular covers other numbers too (checked November 2026).

For numbers and dates, use the WordPress helpers. Developer.WordPress.org lists number_format_i18n() and date_i18n() among the functions that format values for the site language (checked November 2026).

How do you handle words with more than one meaning?

Use _x() with a context note when one English word needs different translations in different places.

The word “Post” can be a noun, as in “Edit this post”, or a verb, as in “Click here to post your comment”. Developer.WordPress.org states that _x() adds a context argument so translators see two separate strings (checked November 2026).

_x( 'Post', 'noun', 'my-plugin' );
_x( 'Post', 'verb', 'my-plugin' );

_x() works like __() but takes the extra context argument. Developer.WordPress.org states that _ex() is the echo version of _x(), just as _e() is the echo version of __() (checked November 2026).

Add a context note whenever a short string could mean two things. A single word such as “Default” or “Archive” is hard to translate without knowing where it appears.

FunctionWhat it doesWhen to use it
__()Returns the translationPlain strings
_e()Prints the translationPlain strings shown at once
_n()Picks singular or plural by countStrings with a number
_x()Returns the translation with contextWords with more than one meaning
_ex()Prints the translation with contextSame as _x(), shown at once
esc_html__()Returns a translation safe for HTMLStrings printed inside page markup
esc_attr__()Returns a translation safe for attributesStrings printed inside tag attributes

How do you escape translated strings?

Escape every translated string before you print it, because a translator could add markup that breaks your page or runs code.

Developer.WordPress.org states that it is good to escape all of your strings, so translators cannot run malicious code (checked November 2026).

Use the combined functions that translate and escape in one step. Developer.WordPress.org lists esc_html__(), esc_html_e(), esc_attr__(), and esc_attr_e() among the escape functions that work with translations (checked November 2026).

Strings that go into HTML attributes need esc_attr__(). Strings that go into page text need esc_html__(). Pick the one that matches where the string will appear.

Never leave a URL inside a translated string unless the URL itself has a version in another language. Developer.WordPress.org states that URLs should not be left for translation in normal cases (checked November 2026).

A guide on how to check a plugin for vulnerabilities covers the wider escaping and cleaning checks that keep plugin output safe.

How do you generate the translation template file?

Run wp i18n make-pot on your plugin folder to collect every marked string into a POT template file.

The POT file is the template you hand to translators. Developer.WordPress.org states that a POT file holds all the original strings, a PO file holds the translation for one language, and an MO file is the compiled form WordPress actually reads (checked November 2026).

Generate the POT file with WP-CLI:

wp i18n make-pot path/to/your-plugin

Developer.WordPress.org states that you can install WP-CLI and use the wp i18n make-pot command to build the file (checked November 2026).

Each translator takes the POT file and fills in the msgstr lines in their own language, which produces a PO file. Developer.WordPress.org states that one PO file exists per language, and that the MO file is built from it with the msgfmt tool (checked November 2026).

Ship the POT file with your plugin so translators do not have to ask you for it. Developer.WordPress.org states that it is a good idea to offer the POT file along with the plugin or theme (checked November 2026).

How do translations reach users on WordPress.org?

Upload the plugin to WordPress.org and the directory parses your files, sends the strings to translate.wordpress.org, and ships language packs to users.

When you upload software to WordPress.org, all JavaScript and PHP files are parsed by machine. Developer.WordPress.org states that any strings found are added to translate.wordpress.org so the community can translate them (checked November 2026).

The plugin developer pages on WordPress.org explain how a plugin joins the directory in the first place, including the account you need and the review that follows.

For a plugin to be imported well, its text domain must match its slug, and it must not use more than one text domain. Make WordPress states that a plugin with the akismet slug must use akismet as its text domain (checked November 2026).

Once a translation reaches 90 percent of the strings translated and approved on translate.wordpress.org, a language pack is generated for that plugin and language. Make WordPress states that the 90 percent mark is the trigger for a pack (checked November 2026).

After the packs exist, the plugin can drop its own language files, because WordPress downloads the pack for each site language. Make WordPress states that plugins can remove the language files from their package once the packs are generated (checked November 2026).

WordPress 5.0 added the same process for JavaScript. Developer.WordPress.org states that the wp-i18n package gives JavaScript the __, _n, and _x functions, and that wp_set_script_translations() tells WordPress the script has translations (checked November 2026).

A guide on how to translate WordPress with AI covers machine translation options for sites, while this guide covers making the plugin code itself translatable.

What mistakes should you avoid?

Avoid missing text domains, split sentences, and strings that translators cannot understand without context.

A missing text domain is the most common fault. Developer.WordPress.org states that you must add your text domain to every __(), _e(), and _n() call, or the translations will not work (checked November 2026).

Split sentences break translation because word order changes between languages. Developer.WordPress.org states that you should use full sentences and split at paragraphs, never putting a whole page in one string (checked November 2026).

Translated strings can double in length, so leave room in buttons and menus. Developer.WordPress.org states that you should assume strings can double in length when translated (checked November 2026).

Do not leave leading or trailing spaces in a translated phrase, and do not put odd markup or control characters in the string. Developer.WordPress.org states that both habits make the string harder to translate (checked November 2026).

A guide on theme vs plugin in WordPress explains the split between theme and plugin strings, which matters because each side needs its own text domain.

Frequently asked questions

Does wrapping strings translate my plugin by itself?

No. Wrapping the strings only prepares the plugin for translation. Translators still need to write each string in their language, either on translate.wordpress.org or in PO files you ship with the plugin.

What text domain should I use for my plugin?

Use the plugin slug in lowercase with dashes, such as my-plugin. The text domain must match the slug, and a plugin on WordPress.org must use the slug part of its plugin URL.

How do I translate a string that holds a variable?

Use placeholders such as %s with printf, and add a translators comment that explains what the value is. Never put the variable inside the quoted string, because the lookup will fail at run time.

How do I handle plurals in different languages?

Use _n() with a singular form, a plural form, and the count. Many languages have more than two plural forms, so the count picks the right form for each language.

Can JavaScript strings in my plugin be translated too?

Yes, since WordPress 5.0. Use the wp-i18n JavaScript package with its __, _n, and _x functions, then call wp_set_script_translations() so WordPress knows the script has translations.

Sources

  1. How to Internationalize Your Plugin WordPress Developer Resources
  2. Localization WordPress Developer Resources
  3. Internationalization for the Block Editor WordPress Developer Resources
  4. Translations Make WordPress
  5. Developer Information WordPress.org
  6. Translate WordPress WordPress.org

Is your product missing, or something out of date?

Tell us what to add or correct. We read every note and reply when we need a source. A message does not buy a ranking.

About the editors

Written and checked byWPLegible Editorial Team Independent WordPress reviews and guides

Researched from the primary sources listed above and checked against our editorial rules before publishing.