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

Scanning

The scanner runs from PerfLocale → Strings → Scan for Strings (top-right button). It walks wp-content/, 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; vendor/, node_modules/, .git/, and test directories are excluded by default (filter perflocale/strings/scanner/excluded_paths).

A full wp-content/ 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:

wp perflocale strings scan

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. Save - the translation takes effect immediately on frontend pages. Machine translation is available via the MT button if you’ve configured a provider.

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 or .mo files (or the XLIFF industry format) from Settings → Export & Import. See Export & Import.

← Back to Docs