Download the PHP package gabepri/auto-html-i18n without Composer

auto-html-i18n (PHP)

Server-side automatic translation for PHP-rendered HTML. Walks markup, masks dynamic values (numbers, dates, names, URLs, emails, symbols, inline tags) into stable cache keys, looks them up in a translation cache, and falls back to a user-supplied backend for cache misses. Returns translated HTML in a single synchronous pass — no async bookkeeping, no client-side JS required.

This is the PHP sibling of packages/js. Both packages share the same masking algorithm and a corpus of cross-port test fixtures so behavior stays identical.

Install

Requires PHP 8.1+, the intl and mbstring extensions.

Quickstart

The onMissingTranslation callback is invoked once per translateHtml() call with the full deduplicated batch of unknown keys. Translations are cached in memory for the lifetime of the I18nTranslator instance — pass initialCache to seed it from your persistent store.

How masking works

Before lookup, each translatable string is normalized into a stable key with dynamic values replaced by {{N}} placeholders:

This means you only translate the abstract sentence shape once — You have {{0}} apples works for any number — and your translations don't have to know about specific values.

Recognized value types, matched in priority order, are ignoreWord, url, email, date, number, and symbol — identical to the JS port. URLs and emails are matched ahead of dates and numbers so they mask as a single unit rather than fragmenting. Strings containing no Unicode letter are skipped outright rather than masked. None of these ever reach your translation backend, so ignoreAttribute is unnecessary for them; reserve it for letter-bearing content the masker cannot recognize by shape, such as personal names or user-authored prose.

Tags outside allowedInlineTags (an <input>, <svg>, <div>, …) are captured as opaque markup variables instead of being left in the key — so their volatile attributes (random ids, gradient refs) never destabilize the cache key, and the original markup is restored verbatim on output. Nested same-name inline tags (<span><span>…</span></span>) are matched opener-to-closer by a stack, so their indices never cross.

An element's markup is aggregated into a single translatable unit only when its entire descendant subtree is inline-allowed and it has direct interleaved text of its own. A pure container of inline elements with no direct text — a nav menu, link list, or button group — is treated as structural, so each child is translated on its own and keeps its own cache key rather than collapsing the whole container into one key.

API

new I18nTranslator(array $config)

Methods

Half-rendered values

Markup rendered before its data arrived carries the stringified absence of the value — Level undefined, Read time about NaN minutes, No results found for ''. Those tokens are not numbers or dates, so masking bakes the broken value into the key as literal text ("Level undefined", not "Level {{0}}").

By default such text is rendered untranslated but never reported — onMissingTranslation never sees it, and nothing about the skip is cached, so the correct mask reports normally on the next render. A translation you have cached for such a key still applies; the gate is on reporting, not on lookup.

A mask counts as half-rendered when it contains undefined, null or NaN as a standalone word, or an empty quote pair ('', "", «», ‘’, “”). Word boundaries are respected, so Annulled contracts reports as usual.

Scoped translations

A translation entry can be either a plain string or a scope-keyed array. The walker resolves the active scope by walking up the DOM tree from the element containing the text and reading the data-i18n-scope attribute.

ICU MessageFormat

Translations may use ICU MessageFormat for plurals, gender, and conditional structure. PHP's built-in MessageFormatter (the intl extension) handles evaluation.

When an ignoreWord carries metadata (e.g. ['word' => 'Mary', 'meta' => ['gender' => 'female']]), that metadata is exposed to ICU as {N_key} arguments — letting translations branch on {0_gender, select, female {...} other {...}}.

If an ICU pattern fails to parse or evaluate — including when it references a variable index or metadata key that doesn't exist (PHP's MessageFormatter would otherwise render a literal {1} and report success) — the affected text falls back to its original untranslated source. Neither the raw pattern nor unfilled placeholders are ever rendered into the output HTML.

Validating translations

To catch bad patterns before they reach your cache or backend responses, dry-run them the same way translateHtml() consumes them. Both methods return an IcuValidationResult (->valid, ->format, ->error, ->output):

format reports how the string will be consumed — icu (single-brace {0}), simple (double-brace {{0}} substitution), or plain — check it matches your intent. Invalid results carry an engine-specific error (malformed pattern, unfilled arguments, out-of-range {{N}} index).

RTL support

Right-to-left locales (Hebrew, Arabic, Persian, Urdu, …) work out of the box.

Document direction. The server owns the markup, so set dir/lang yourself using getDirection(). Direction is resolved from the locale tag: the language subtag decides (he, ar, fa, ur, …) and an explicit script subtag overrides it (az-Arab → rtl, ar-Latn → ltr). TextDirection::forLocale() is also available statically.

Bidi isolation of variables. When the target locale is RTL, values re-injected into {{N}} placeholders — numbers, dates, URLs, emails, and ignoreWords (typically Latin brand names) — are wrapped in Unicode first-strong isolate characters (U+2068…U+2069). Without this, the bidi algorithm can visually scramble LTR fragments inside an RTL sentence (e.g. a date like 12/31/2024 rendering reversed). The isolates are invisible, carried into the output HTML, and stripped again during masking, so cache keys stay stable.

Isolation applies to simple {{N}} substitution (and validateIcu/validateTranslation output). ICU patterns are rendered by the ICU engine as-is — add directional marks inside the pattern if a specific argument needs them.

What's deliberately different from the JS package

Both ports honor the same data-i18n-* input attributes (-key, -scope, -ignore).

Development

composer test:coverage sets XDEBUG_MODE=coverage for you. Running vendor/bin/phpunit --coverage-text directly reports nothing under Xdebug 3, which defaults to develop mode.

Tests include a fixture-driven suite (tests/FixtureTest.php) that runs the same Masker assertions as the JS package against the shared corpus in fixtures/masker/. Adding a fixture there exercises both ports immediately.

Static analysis level

phpstan.neon.dist pins level 9 — the highest level that passes with zero errors and zero suppressions. There is deliberately no baseline: a baseline would let a higher number hide the same findings.

Four things make level 9 reachable:

• treatPhpDocTypesAsCertain: false. Several guards in src/ defend against values that a vendor's PHPDoc claims are impossible but that the runtime can still produce — Masterminds\HTML5::loadHTMLFragment() returning a non-fragment (HtmlWalker, I18nTranslator) and MessageFormatter::create() returning null (Masker). An annotation is not a runtime guarantee, so the guards stay and PHPStan is told not to trust the annotation.
• Removing guards that were dead by this code's own logic — the DOMElement loop condition and trailing return null in HtmlWalker::findAggregationTarget(), the ownerDocument === null check in HtmlWalker::replaceTextNode() (mutually exclusive with the parentNode === null check above it), and the empty-capture-group skip in Masker::parseAttributes() (group 1 of that regex always matches ≥1 char).

• A declared shape for the constructor config. I18nTranslator used to take array<string,mixed>, so every value read out of it was mixed and level 9 rejected all ten downstream constructor calls. The keys are now spelled out as a PHPStan array shape — which is worth more than the level number: consumers who run PHPStan on their own code get key-name typo detection and per-key value types at the call site. Two aliases are exported and importable with @phpstan-import-type I18nTranslatorConfig from \AutoHtmlI18n\I18nTranslator:

  Alias	Meaning
  I18nTranslatorConfig	What the constructor takes: locale and onMissingTranslation required, everything else optional.
  I18nTranslatorOptions	The same keys with all of them optional — for a partial config you merge into a base one.

  onMissingTranslation is deliberately typed as a bare callable rather than with its full signature. It is the one config value whose return crosses back from consumer code, and annotating that return would let the analyser treat it as proven and delete the runtime guards that exist precisely because an annotation is not a runtime guarantee. The signature it is called with is documented in the class docblock and in the config table above.

• A typed decoder in tests/FixtureTest.php. json_decode() returns mixed, which accounted for 34 of the 44 level-9 findings. The shared JSON now crosses into typed territory in exactly one place (decodeCases()), behind a handful of small accessors (str(), map(), objectList(), …) rather than scattered casts — a malformed fixture fails loudly at the decode site instead of surfacing as a confusing type error deep inside a test.

Level 10 (checkImplicitMixed) is not enabled. It reports 53 findings, all but one of them the same thing: the array $items parameter of the ~25 onMissingTranslation test closures has an implicit mixed element type, so every $item->masked in the tests is an error. Because the config shape types the callback as a bare callable (see above), PHPStan cannot infer the element type and each closure would need its own @param list<TranslationItem> docblock. The remaining finding is a genuine variance nit in TranslationItem::toArray(). Nothing in src/ blocks it structurally.

Code style

.php-cs-fixer.dist.php applies @PSR12 plus declare_strict_types (every file in src/ and tests/ already declares it). The codebase satisfies it — composer lint reports 0 of 27 files — and CI enforces it. Run composer lint:fix to normalize anything new.

License

MIT