Internationalization

Variable parts go in placeholders filled by sprintf() or printf(), never by concatenation: 'Published on ' . $date gives translators two fragments, and many languages need the date elsewhere in the sentence. A string with more than one placeholder uses numbered ones (%1$s, %2$s) so a translation can reorder them. A comment starting with translators: on the line directly above the call (or inside it, above the string) explains each placeholder; it is copied into the POT file and shown to translators next to the string. HTML stays out of strings where possible; when a link sits inside a sentence, the translation keeps the tag and the URL is inserted through a placeholder.

_n() is not an if ( 1 === $n ). Each language defines its own plural rule in the Plural-Forms header of its translation file: Spanish has two forms (n != 1), Japanese one, Arabic six. The singular string still carries the placeholder, because some languages use the "singular" form for 21, 31 and so on. When the number is unknown at the point where the strings are declared (a post status label, a list registered on init), _n_noop() stores the pair and translate_nooped_plural( $noop, $count, 'lumen-catalog' ) picks the form later.

_x() adds a context to identical English strings that translate differently: the catalogue has a sort "Order" and an "Order" button, Orden and Pedir in Spanish, each a separate catalogue entry. Context also carries hints such as post type general name, used by core’s own labels.

A translation is third-party input: a translator, or a compromised language pack, can put markup or script into it. Translated text is therefore escaped like any other output, late and for its context, with the combined functions (esc_html__(), esc_attr__(), esc_html_x()) or with esc_html( __() ); the catalogue’s search form prints its label with esc_html_e( 'Search the catalogue', 'lumen-catalog' ) and its placeholder attribute with esc_attr__( 'Title, author or ISBN', 'lumen-catalog' ). When a translation must contain HTML, wp_kses() keeps only the expected tags and the URL is escaped separately with esc_url() (see Security for Developers).

src/Text.php of lumen-catalog holds the user-facing strings of the catalogue and shows each case: a plural with a formatted number, reorderable placeholders, two contexts, a translated date and a sentence with a link. The class is loaded by the plugin’s Composer autoloader (see Plugin Fundamentals):

Source: Plugin Handbook: How to Internationalize Your Plugin

Post type labels are translated the same way, inside the init callback that registers lp_book (_x( 'Books', 'post type general name', 'lumen-catalog' ) for name, __( 'Add New Book', 'lumen-catalog' ) for add_new_item; the full registration is in Custom Post Types and Taxonomies). The rewrite slug stays books in every language: a translated slug changes the URLs whenever the site language changes, and the rewrite rules are only flushed on activation.

Five common mistakes, in a throwaway file Bad.php outside the plugin:

Source: WordPress Coding Standards: Customizable sniff properties

The WordPress.WP.I18n sniff of WPCS 3.4.1, run as vendor/bin/phpcs --standard=WordPress --sniffs=WordPress.WP.I18n --runtime-set text_domain lumen-catalog Bad.php, reported seven errors on five lines: MissingTranslatorsComment (lines 3, 5 and 7), NonSingularStringLiteralText ("The $text parameter must be a single text string literal. Found: $title", line 4), UnorderedPlaceholdersText (line 5, fixable automatically), TextDomainMismatch ("Expected 'lumen-catalog' but got 'lumen'", line 6) and MissingSingularPlaceholder (line 7).

__( $title ) can never work: the extractor cannot know the value, so no translator ever sees it. The real Text.php and Plugin.php passed the same sniff plus WordPress.Security.EscapeOutput with no reports. The text_domain property belongs in the plugin’s phpcs.xml.dist, next to the prefixes shown in Plugin Fundamentals.

Translations loaded before the current user and locale are known come out in the wrong language (the site locale instead of the user’s profile language) and bypass any plugin that filters the locale or the file paths. Since 6.7, WordPress reports it. To reproduce it, a test copy of lumen-catalog.php gets one extra line at the end of the main file, which runs while WordPress is still including plugins:

Source: Make WordPress Core: I18N Improvements in 6.7

With WP_DEBUG enabled, any request (here wp eval 'echo LUMEN_CATALOG_LABEL, "\n";') prints:

The string was still translated, in the site locale, so the notice is easy to dismiss. On WordPress 7.1.3 it appeared even with the site in English, because since 6.8 every active plugin with a Text Domain header has a registered path, and the check runs before looking for a file. The usual causes are:

The fix is to move the code into a callback on init (or later), or to translate at the point of output.

wp i18n make-pot scans PHP, JavaScript, Blade, block.json and theme.json files and the plugin header. It defaults the domain to the slug and silently skips strings of other domains. Run from the plugin folder (in the cli container of the stack in Database Schema, with the plugin folder mounted):

Source: WP-CLI Commands: wp i18n make-pot

node_modules, vendor and .git are excluded by default. --exclude=src/admin leaves out the JavaScript sources, so that the JavaScript strings are referenced from the built file that WordPress actually loads (see JavaScript translations). The entry for the script’s plural, with its translator comment and format flag:

The audit built into make-pot warns about placeholders without a translator comment and unordered placeholders (--skip-audit turns it off); with Bad.php copied into the plugin for a run, it printed Warning: The string "%s and %s" contains placeholders but has no "translators:" comment to clarify their meaning. followed by Warning: Multiple placeholders should be ordered. It does not see __( $title ) or the wrong domain, which is why WPCS runs as well.

The PO file starts as a copy of the POT with the language headers filled in; the Plural-Forms line must match the language. Translators then fill msgstr:

Source: Plugin Handbook: Localization

When the code changes, wp i18n update-po languages/lumen-catalog.pot languages/ merges new strings into existing PO files. The three compiled formats come from the PO:

Source: WP-CLI Commands: wp i18n make-php

Each command printed Success: Created 1 file., leaving:

make-json removes the JavaScript strings from the PO by default; --no-purge keeps the PO complete, so it can be compiled again. The .l10n.php file is a plain return [ ... ] of the headers and messages, with context and string joined by an invisible \x04 byte and plural forms by \0. With the MO file removed, the strings were still translated from the PHP file alone; a site that needs MO files only returns mo from translation_file_format.

A WordPress.org plugin is translated by the community on translate.wordpress.org, and WordPress downloads each language pack into wp-content/languages/plugins/ with the other updates (translations update automatically by default; wp language plugin install <slug> <locale> installs one by hand). lumen-catalog is private, so it ships its own languages/ folder; a language pack for the same domain would take precedence.

Code that writes to one user (e-mails, notifications) uses that user’s locale with switch_to_user_locale() (6.2), which also makes determine_locale() and get_user_locale() follow. Core already does this for its own e-mails, and since 6.7 also for messages to the admin_email address when it belongs to a user. With the site in Spanish and maria.editor set to English in her profile (wp user meta update maria.editor locale en_US):

Source: Code Reference: switch_to_user_locale()