{"id":20863,"date":"2026-10-18T09:03:00","date_gmt":"2026-10-18T07:03:00","guid":{"rendered":"https:\/\/www.lukaswojcik.com\/blog\/?p=20863"},"modified":"2026-10-09T22:29:15","modified_gmt":"2026-10-09T20:29:15","slug":"plugin-internationalization","status":"publish","type":"post","link":"https:\/\/www.lukaswojcik.com\/blog\/en\/wordpress-plugins-tricks\/tutorials-en-wordpress-plugins-tricks\/plugin-internationalization\/","title":{"rendered":"Plugin i18n: text domain, language packs and JavaScript"},"content":{"rendered":"

A plugin written only in English shows English buttons on a German or Polish site, even when WordPress itself speaks the visitor\u2019s language. This blog runs in English, German and Polish, so every plugin string used here has to exist three times, including texts that JavaScript writes into the page later. WordPress handles this on three levels: gettext calls in PHP, separate JSON files for scripts, and language packs built by translate.wordpress.org. Many older tutorials still call load_plugin_textdomain()<\/code> early in plugins_loaded<\/code>, although since WordPress 6.7 that call only records the path; the notice added in 6.7 comes from translation calls before after_setup_theme<\/code>.<\/p>\n

This article builds a small plugin, \u201cLW Reading Time\u201d, with one PHP file and one script that imports @wordpress\/i18n<\/code>. It covers the translation functions, the plural rules of German and Polish, what WordPress 7.1.2 (the current release on 29.09.2026) loads by itself, how a string travels through GlotPress into a language pack, and how translation files are built locally with WP-CLI. Plugin Check<\/a> and the fields of readme.txt<\/code><\/a> each have a separate article in this series and appear here only where translations touch them.<\/p>\n

The text domain: one identifier, identical to the slug<\/h2>\n

Every gettext call carries the text domain as its last argument. It tells WordPress which translation file a string belongs to. For plugins in the directory the rule is strict: the text domain has to match the plugin slug, so a plugin with the slug akismet<\/code> uses the text domain akismet<\/code>, and a plugin may use only one text domain. The Meta handbook states that plugins breaking this rule cannot be imported properly into translate.wordpress.org and do not get language packs. The format is lowercase with hyphens, no underscores and no spaces.<\/p>\n

The text domain must also be a literal string. Tools such as wp i18n make-pot<\/code> and the importer on WordPress.org read the source code without running it, so a constant or variable in place of 'lw-reading-time'<\/code> is invisible to them; the plugin handbook explicitly advises against this shortcut. Strings that core already translates, such as \u201cSettings\u201d, still get the plugin\u2019s own text domain, otherwise they lose their translation once core changes its wording.<\/p>\n

According to the handbook, the Text Domain<\/code> header has been optional since WordPress 4.6, and directory plugins may omit Domain Path<\/code>. Both are still worth setting: make-pot<\/code> reads the text domain from the header, and since WordPress 6.8 this pair lets plugins outside the directory load translations automatically. Plugin Check 2.1.0 (released on 16.08.2026) reports an invalid text domain format as an error, a header that differs from the slug as a warning, and a Domain Path<\/code> that lacks a leading slash or points to a missing folder as a warning as well. The example plugin therefore ships an existing languages\/<\/code> folder containing the POT file.<\/p>\n

The gettext functions in PHP<\/h2>\n

The main file of the example plugin shows the reading time above single posts and adds a button that the script later relabels. All visible strings pass through a translation function:<\/p>\n

<?php\n\/**\n * Plugin Name:       LW Reading Time\n * Description:       Shows the estimated reading time above single posts.\n * Version:           1.0.0\n * Requires at least: 6.8\n * Requires PHP:      7.4\n * Author:            Lukas Wojcik\n * License:           GPL-2.0-or-later\n * License URI:       https:\/\/www.gnu.org\/licenses\/gpl-2.0.html\n * Text Domain:       lw-reading-time\n * Domain Path:       \/languages\n *\n * @package LW_Reading_Time\n *\/\n\ndefined( 'ABSPATH' ) || exit;\n\nconst LW_READING_TIME_WORDS_PER_MINUTE = 200;\n\n\/**\n * Returns the estimated reading time of a post in whole minutes.\n *\n * @param WP_Post $post Post object.\n * @return int Minutes, at least 1.\n *\/\nfunction lw_reading_time_minutes( WP_Post $post ) {\n\t$text  = wp_strip_all_tags( strip_shortcodes( $post->post_content ) );\n\t$words = preg_split( '\/\\s+\/u', trim( $text ), -1, PREG_SPLIT_NO_EMPTY );\n\n\treturn max( 1, (int) ceil( count( $words ) \/ LW_READING_TIME_WORDS_PER_MINUTE ) );\n}\n\n\/**\n * Prepends the reading time and a \"mark as read\" button to single posts.\n *\n * @param string $content Post content.\n * @return string\n *\/\nfunction lw_reading_time_prepend( $content ) {\n\tif ( ! is_singular( 'post' ) || ! in_the_loop() || ! is_main_query() ) {\n\t\treturn $content;\n\t}\n\n\t$post    = get_post();\n\t$minutes = lw_reading_time_minutes( $post );\n\n\t$label = sprintf(\n\t\t\/* translators: %s: estimated reading time in minutes. *\/\n\t\t_n( 'Reading time: %s minute', 'Reading time: %s minutes', $minutes, 'lw-reading-time' ),\n\t\tnumber_format_i18n( $minutes )\n\t);\n\n\t$button = sprintf(\n\t\t'<button type=\"button\" class=\"lw-reading-time__mark\" data-post=\"%1$d\">%2$s<\/button>',\n\t\t(int) $post->ID,\n\t\tesc_html__( 'Mark as read', 'lw-reading-time' )\n\t);\n\n\treturn '<p class=\"lw-reading-time\">' . esc_html( $label ) . ' ' . $button . '<\/p>' . $content;\n}\nadd_filter( 'the_content', 'lw_reading_time_prepend' );\n\n\/**\n * Enqueues the front-end script and connects it to its translation files.\n *\/\nfunction lw_reading_time_enqueue_script() {\n\tif ( ! is_singular( 'post' ) ) {\n\t\treturn;\n\t}\n\n\t$asset_file = plugin_dir_path( __FILE__ ) . 'build\/index.asset.php';\n\tif ( ! file_exists( $asset_file ) ) {\n\t\treturn;\n\t}\n\t$asset = require $asset_file;\n\n\twp_enqueue_script(\n\t\t'lw-reading-time',\n\t\tplugins_url( 'build\/index.js', __FILE__ ),\n\t\t$asset['dependencies'],\n\t\t$asset['version'],\n\t\tarray( 'in_footer' => true )\n\t);\n\n\t\/\/ Looks for lw-reading-time-{locale}-{md5 of \"build\/index.js\"}.json in wp-content\/languages\/plugins, without a language pack there in languages\/ (Domain Path).\n\twp_set_script_translations( 'lw-reading-time', 'lw-reading-time' );\n}\nadd_action( 'wp_enqueue_scripts', 'lw_reading_time_enqueue_script' );<\/code><\/pre>\n
__()<\/code> returns the translation, _e()<\/code> prints it. Printing without escaping is exactly what the WordPress Coding Standards flag: the EscapeOutput<\/code> sniff lists _e()<\/code> and _ex()<\/code> as unsafe printing functions and suggests esc_html_e()<\/code> or esc_attr_e()<\/code> instead. The combined functions esc_html__()<\/code>, esc_html_e()<\/code>, esc_attr__()<\/code>, esc_attr_e()<\/code>, esc_html_x()<\/code> and esc_attr_x()<\/code> translate and escape in one step. A translated string is still text from outside the code and is escaped like any other output. In the example, esc_html()<\/code> wraps the result of sprintf()<\/code>, because escaping only the pattern would leave the inserted number unescaped.<\/p>\n
Placeholders and translator comments<\/h3>\n
Variables never belong inside the translated string. A call like _e( \"Your city is $city.\" )<\/code> fails because the extractor sees the literal $city<\/code>, while at runtime WordPress looks up a string with the actual city name, which no translation file contains. The correct form is a placeholder plus printf()<\/code> or sprintf()<\/code>. With several placeholders the handbook recommends numbered arguments such as %1$s<\/code> and %2$s<\/code> in single quotes, so a translation can reorder the values.<\/p>\n
A comment starting with translators:<\/code> tells the translator what a placeholder stands for. It has to be the last PHP comment before the gettext call; make-pot<\/code> copies it into the POT file as a #.<\/code> line, and GlotPress displays it next to the string. The number itself goes through number_format_i18n()<\/code>, because German and Polish use different thousands separators than English.<\/p>\n
_x()<\/code> adds a context for words with several meanings; GlotPress treats context plus text as a separate entry. The script below uses _x( 'Read', \u2026 )<\/code> for the state after the click: without context, \u201cRead\u201d might become the verb \u201cLesen\u201d or \u201cCzytaj\u201d, while the button needs \u201cGelesen\u201d or \u201cPrzeczytany\u201d.<\/p>\n
Plural forms: two in English and German, three in Polish<\/h3>\n
_n()<\/code> receives a singular, a plural, the count and the text domain. English and German get by with two forms, Polish needs three. The rule lives in the Plural-Forms<\/code> header of each locale. GlotPress, the software behind translate.wordpress.org, defines Polish with nplurals=3<\/code> and the expression (n == 1) ? 0 : ((n % 10 >= 2 && n % 10 <= 4 && (n % 100 < 12 || n % 100 > 14)) ? 1 : 2)<\/code>; a Polish export from translate.wordpress.org carries the same header. For the reading time this results in:<\/p>\n\n\n\n\n\n\n\n\n\n\n
Minutes<\/th>\nEnglish<\/th>\nGerman<\/th>\nPolish (form)<\/th>\n<\/tr>\n<\/thead>\n
1<\/td>\nReading time: 1 minute<\/td>\nLesezeit: 1 Minute<\/td>\nCzas czytania: 1 minuta (0)<\/td>\n<\/tr>\n
2<\/td>\nReading time: 2 minutes<\/td>\nLesezeit: 2 Minuten<\/td>\nCzas czytania: 2 minuty (1)<\/td>\n<\/tr>\n
5<\/td>\nReading time: 5 minutes<\/td>\nLesezeit: 5 Minuten<\/td>\nCzas czytania: 5 minut (2)<\/td>\n<\/tr>\n
12<\/td>\nReading time: 12 minutes<\/td>\nLesezeit: 12 Minuten<\/td>\nCzas czytania: 12 minut (2)<\/td>\n<\/tr>\n
21<\/td>\nReading time: 21 minutes<\/td>\nLesezeit: 21 Minuten<\/td>\nCzas czytania: 21 minut (2)<\/td>\n<\/tr>\n
22<\/td>\nReading time: 22 minutes<\/td>\nLesezeit: 22 Minuten<\/td>\nCzas czytania: 22 minuty (1)<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
This explains a rule from the handbook: the singular has to contain the placeholder as well, so '%s minute'<\/code> and not 'One minute'<\/code>, because in some languages the \u201csingular\u201d slot also covers numbers other than one. The code only passes the number; which of the three Polish sentences appears is decided by the translation file. For plural strings whose count is not known yet at definition time, _n_noop()<\/code> and translate_nooped_plural()<\/code> exist.<\/p>\n
Who loads the translations: just-in-time instead of load_plugin_textdomain<\/h2>\n
With WordPress 4.6, the way translations are loaded changed fundamentally. The dev note from July 2016 introduced just-in-time loading: when WordPress meets a text domain for the first time, _load_textdomain_just_in_time()<\/code> looks in wp-content\/languages<\/code> and loads the matching file. Since then, plugins from the directory no longer need load_plugin_textdomain()<\/code>. The same release reversed the search order, so language packs in wp-content\/languages<\/code> are checked before files inside the plugin folder.<\/p>\n
WordPress 6.5 replaced the translation engine. Language packs now also contain a .l10n.php<\/code> file next to .po<\/code> and .mo<\/code>; when present, WordPress loads it instead of the .mo<\/code> file, which is faster, uses less memory and benefits from OPcache. The filter translation_file_format<\/code> switches back to mo<\/code>.<\/p>\n
WordPress 6.7 changed load_plugin_textdomain()<\/code> so that it only records the path; the just-in-time mechanism loads the translations. The same release added a _doing_it_wrong()<\/code> notice. If translations for a domain are requested before after_setup_theme<\/code>, WordPress reports that loading \u201cwas triggered too early\u201d and says to load translations at init<\/code> or later. According to the dev note, early loading forces WordPress to determine the current user prematurely and prevents other plugins from filtering the locale or file location.<\/p>\n
For testing, a detail in core\u2019s l10n.php<\/code> matters: the notice appears as soon as core knows a language directory for the domain, even if no translation file exists. Since 6.8, core registers the Domain Path<\/code> folder for every active plugin, or the plugin folder if the header is absent. On WordPress 7.1.2, the snippet below therefore also triggers the notice on an English site without any translation file.<\/p>\n
<?php\n\/\/ Too early: runs while WordPress loads the plugin file, before after_setup_theme and init.\n\/\/ WordPress 6.7+ reports (since 6.8 also without a translation file, even on en_US)\n\/\/ _load_textdomain_just_in_time() via _doing_it_wrong().\ndefine( 'LW_READING_TIME_TITLE', __( 'Reading time', 'lw-reading-time' ) );\n\n\/\/ Better: translate at the moment the text is needed (init or later).\nfunction lw_reading_time_title() {\n\treturn __( 'Reading time', 'lw-reading-time' );\n}\n\n\/\/ Plugin metadata without translating it: third parameter $translate = false.\nfunction lw_reading_time_version() {\n\tif ( ! function_exists( 'get_plugin_data' ) ) {\n\t\trequire_once ABSPATH . 'wp-admin\/includes\/plugin.php';\n\t}\n\t$data = get_plugin_data( __FILE__, false, false );\n\n\treturn $data['Version'];\n}<\/code><\/pre>\n
The dev note names two typical causes: get_plugin_data()<\/code> without $translate = false<\/code>, and classes instantiated in the main file whose constructor calls __()<\/code>. To locate the trigger, it suggests a callback on doing_it_wrong_run<\/code> that prints a backtrace for _load_textdomain_just_in_time<\/code>, or Query Monitor.<\/p>\n
WordPress 6.8 extended just-in-time loading to plugins outside the directory, based on the Text Domain<\/code> and Domain Path<\/code> headers. The dev note sums it up in two cases:<\/p>\n