String Translation

String Translation lets you override gettext strings emitted by themes and plugins from inside WordPress - no editing .po/.mo files, no rebuilding, no lost changes after updates. PerfLocale scans PHP source for __(), _e(), _x(), _n(), and every other WordPress i18n function, stores what it finds, and serves your translations through the standard gettext filter.

What it handles

  • __(), _e(), esc_html__(), esc_attr__(), esc_html_e(), esc_attr_e() - simple strings
  • _x(), _ex(), esc_html_x(), esc_attr_x() - context-disambiguated strings
  • _n(), _nx(), _n_noop(), _nx_noop() - plural forms, including languages with three to six CLDR plural forms (e.g. Russian, Polish, Arabic), not just a two-form n == 1 / else split

Scanning

The scanner runs from PerfLocale → Strings → Scan for Strings (top-right button). It walks the parent theme, the child theme (if any), every active plugin directory and mu-plugins/ — PerfLocale’s own directory is deliberately skipped so its strings stay out of your catalogue — reads every PHP file, and inserts newly-found strings into the perflocale_strings table. Existing strings are preserved; only new ones are added. Files larger than 2 MB are skipped to avoid memory spikes, and vendor/, node_modules/, .git/, tests/, test/, cache/, build/ and dist/ are excluded by default (filter perflocale/strings/scanner/excluded_paths).

A full scan on a site with many active plugins can take a minute or two. PerfLocale dispatches the scan via its background-jobs system — you'll be redirected to PerfLocale → Jobs where progress and any errors are visible live. Smaller scans (targeted at a single plugin / theme directory) still run inline.

You can also run the scanner from the command line. The CLI scans one directory at a time and defaults to the active theme, so pass --dir to point it elsewhere:

# Active theme (default).
wp perflocale strings scan

# A specific plugin, restricted to one text domain.
wp perflocale strings scan --dir=wp-content/plugins/my-plugin --domain=my-plugin

Domains and contexts

Every string has a text domain (usually a theme or plugin slug) and an optional context. Filter the Strings page by domain (e.g. only translate woocommerce strings) and combine with context when the same word has different meanings (e.g. Post as a noun vs. a verb).

Translating a string

Click any row on the Strings page. The editor opens with the original on the left and one editable field per active language on the right. Plural strings appear as two rows — singular text and plural text — and for languages with more than two plural forms the plural row adds an extra field per grammatical form. Save - the translation takes effect immediately on frontend pages. Machine translation is available via the MT button if you’ve configured a provider.

Plural forms

WordPress plural calls — _n(), _nx(), and the _n_noop() / _nx_noop() variants — are served with each language’s full CLDR plural rules, not just a two-form n == 1 / else split. Each language picks its own form set at runtime through WordPress core’s \Plural_Forms: Japanese has 1 form, English and German 2, Russian and Polish 3, Arabic 6.

For languages with more than two forms, the plural row on the Strings screen shows one extra input per grammatical form, so a translator fills in each CLDR category (Polish few vs. many, for example) directly. Multi-form .po files import correctly — every msgstr[…] form is stored.

PO round-trip: forms beyond the standard two are imported from multi-form .po files, editable per-form in the Strings screen, and preserved across a PO export followed by a re-import. The flat .po export carries the standard two forms (singular + plural); those extra forms aren’t written into the exported file, and re-importing that file leaves them in place. For a fully lossless backup of three-or-more-form translations, use the JSON data export rather than the .po file.

Storage modes: database vs files

PerfLocale supports two storage backends for string translations, selectable at Settings → Performance:

  • Files (default) - generates .l10n.php translation files (the format WP 6.5+ prefers) in wp-content/uploads/perflocale/translations/. Same speed as a native language pack; zero DB reads for gettext lookups; regenerated automatically when you edit a string.
  • Database - translations live in perflocale_string_translations with a 3-layer cache in front. Simple; every edit is instantly live; portable across hosts via the Export feature.

Regenerate Translation Files

If you ever see Tools → Site Health reporting “Some translations need to be re-linked” or “Compiled translation files are missing”, the fix is a single click: Settings → Performance → Regenerate Translation Files. That button does three things in one pass:

  1. Self-heal. Any saved translation that has lost its connection to the file-generation pipeline (orphaned string_translations row, string with no group, or a missing translation_links row) is reconnected automatically before generation starts. The completion notice reports how many translations were reconnected on this run.
  2. Clean. Stale .l10n.php files are removed.
  3. Generate. Fresh files are written, one per (domain × locale) pair.

In normal operation files regenerate automatically on every translation save via the perflocale/strings/regenerate_files hook, so you rarely need to click the button. The manual path exists for two cases: (a) recovering from a partial import or a re-scan that renumbered strings, and (b) after editing translations directly in the database (e.g. via a migration script that bypassed the normal save flow).

Import / export

Export your string translations as standard .po files straight from PerfLocale → Strings — the Export PO and Import PO buttons sit beside the page heading, one language at a time — or from the command line with wp perflocale po-export / po-import. The full JSON export at Settings → Export & Import carries the same data under its String Translations section. See Export & Import.

Plural forms are preserved across a PO export and re-import — the forms beyond the standard two are never lost — and multi-form PO files import every form. For a fully lossless backup of three-or-more-form languages, use the JSON data export.

Imports by accounts without unfiltered_html

A PO file uploaded on PerfLocale → Strings is stored at the trust level of the account that uploads it. For an account without WordPress’s unfiltered_html capability, each translation goes through the same HTML filter the Strings screen applies when you save a translation there (WordPress’s wp_kses_post()), which keeps the markup WordPress allows in post content.

Only values that can contain markup are touched: a translation with no < in it is stored exactly as the file has it. A translation that does contain markup can come back reformatted, as it would after a save on the Strings screen — single-quoted attributes become double-quoted, <br/> becomes <br />, a bare & becomes &amp; — and a <…> the filter does not read as an allowed tag is removed, including a printf placeholder that stands where an attribute would (the %2$s in <a href="%1$s" %2$s>). Entries with no translation (msgid only) and fuzzy entries are skipped as they always are, and are not filtered.

When the filter leaves nothing of a translation, a message says which one:

  • A whole entry emptied — Not imported: removing HTML that is not allowed left the translation of "…" empty. The entry is skipped, so in Merge mode whatever was already stored for that string stays as it was.
  • One plural form emptied — a Partly imported: … message names the entry and the msgstr[…] index. An emptied msgstr[0] or msgstr[1] is not written; for msgstr[1] that includes the extra plural forms that come after it. In Merge mode the message for an emptied msgstr[0] or msgstr[1] ends Any translation already stored for it was kept. An emptied msgstr[2] or later is different: it is stored as an empty form in its own slot, so the forms after it keep their places, and it replaces whatever that form held before, in Merge mode too.
  • Every importable translation in the file emptied — Nothing was imported: removing HTML that is not allowed left every importable translation in the PO file empty. The import stops before it writes anything, so in Replace mode the language’s existing translations are not deleted.

The notice after the import counts both cases — … imported entries were changed by the HTML filter for accounts without the unfiltered_html capability … for entries that were imported after filtering, and … entries were not imported because nothing was left after removing HTML that is not allowed — and lists the first three messages under the counts.

Accounts that hold unfiltered_html — on a single site that includes administrators, unless DISALLOW_UNFILTERED_HTML is set — store each translation exactly as the file has it. wp perflocale po-import always does, whichever user it runs as.

The JSON import on Settings → Export & Import applies the same filter to its String Translations section, with two differences. A JSON translation the filter empties is still stored, empty, and the site treats it as untranslated; the JSON import does not stop when that happens to every translation, so a Replace import goes ahead. And the JSON import reports only how many rows were changed, not a message per entry. See Export & Import.

← Back to Docs