README

Server-side automatic translation for PHP-rendered HTML. Walks markup, masks dynamic values (numbers, dates, names, URLs, 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

composer require gabepri/auto-html-i18n

Requires PHP 8.1+, the intl and mbstring extensions.

Quickstart

use AutoHtmlI18n\I18nTranslator;
use AutoHtmlI18n\TranslationItem;

$i18n = new I18nTranslator([
    'locale' => 'es',
    'onMissingTranslation' => function (array $items, string $locale): array {
        // $items: TranslationItem[] — one entry per unique missing key
        // Return: ['masked_key' => 'translation', ...]
        // Either look these up in your DB or hand them off to a translation service.
        return MyTranslationService::fetch($items, $locale);
    },
]);

$html = $i18n->translateHtml('<p>You have 5 apples</p>');
// → '<p>Tienes 5 manzanas</p>'

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:

Input	Cache key	Variables
`You have 5 apples`	`You have {{0}} apples`	`[{value: "5", type: "number"}]`
`Visit https://acme.com`	`Visit {{0}}`	`[{value: "https://acme.com", type: "url"}]`
`Click <a href="/x">here</a>`	`Click <a0>here</a0>`	`[]` (tag attrs preserved separately)
`HELLO WORLD`	`hello world`	(case is restored on output)

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.

API

`new I18nTranslator(array $config)`

Key	Type	Default	Notes
`locale`	`string`	—	Required. Initial active locale.
`onMissingTranslation`	`callable`	—	Required. `(TranslationItem[] $items, string $locale): array<string, string\|array>`
`allowedInlineTags`	`string[]`	`['a','b','i','u','strong','em','span','small','mark','del']`	Tags that may appear inside translatable text and round-trip through translation.
`translatableAttributes`	`string[]`	`['title','placeholder','alt','aria-label']`	Attributes to translate on every element.
`ignoreSelectors`	`string[]`	`['script','style','code']`	Skip subtrees matching these. Tag names or `[attr]` form.
`ignoreWords`	`array`	`[]`	Words preserved verbatim during masking. Plain strings or `['word' => 'X', 'meta' => [...]]`.
`initialCache`	`array<string,string\|array>`	`[]`	Pre-populated translations for the active locale.
`originalAttribute`	`string`	`'data-i18n-original'`	Reserved (currently unused server-side).
`keyAttribute`	`string`	`'data-i18n-key'`	When set on an element, overrides the masked key for that element's content.
`ignoreAttribute`	`string`	`'data-i18n-ignore'`	Setting this attribute on an element skips its subtree.
`scopeAttribute`	`string`	`'data-i18n-scope'`	Names a scope that scope-keyed translations resolve against.
`debug`	`bool`	`false`	When true, each `TranslationItem` includes a `debug` payload (DOM context).

Methods

// Walk an HTML fragment, translate everything translatable, return HTML.
$i18n->translateHtml(string $html): string

// Imperative: look up a pre-masked key and substitute positional variables.
// (No masking, no ICU — just {{N}} substitution.)
$i18n->translate(string $text, array $variables = [], ?string $scope = null): string

// Locale management
$i18n->getLocale(): string
$i18n->setLocale(string $locale): void

// Cache management
$i18n->setCache(string $locale, array $entries): void
$i18n->getCache(?string $locale = null): array
$i18n->clearCache(?string $locale = null): void
$i18n->getTranslation(string $key, ?string $locale = null): string|array|null

// IgnoreWords management
$i18n->getIgnoreWords(): array
$i18n->addIgnoreWords(array $words): void
$i18n->removeIgnoreWords(array $words): void
$i18n->setIgnoreWords(array $words): void

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.

// Backend response
[
    'greeting' => [
        'formal' => 'Bienvenido',
        'casual' => '¡Hola!',
    ],
]

// HTML
'<div data-i18n-scope="formal"><p data-i18n-key="greeting">Hello</p></div>'
// → '<div data-i18n-scope="formal"><p data-i18n-key="greeting">Bienvenido</p></div>'

ICU MessageFormat

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

// Backend returns
['You have {{0}} apples' => '{0, plural, one {Tienes # manzana} other {Tienes # manzanas}}']

// "You have 1 apples" → "Tienes 1 manzana"
// "You have 5 apples" → "Tienes 5 manzanas"

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 {...}}.

What's deliberately different from the JS package

	JS (browser)	PHP (server)
Walks	Live DOM via `MutationObserver`	One HTML string per call
`onMissingTranslation`	Async, possibly many calls (debounced/batched)	Sync, exactly one call per `translateHtml()`
Pending state	Yes — text is replaced when async callback resolves	No — translation always completes before serialization
Re-render on locale change	Re-walks the DOM in place	Caller re-runs `translateHtml()` on cached source
Output-side bookkeeping attributes	`data-i18n-original` / `data-i18n-pending` written to elements	Not used (single-pass output)

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

Development

composer install
vendor/bin/phpunit

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.

License

MIT

gabepri / auto-html-i18n

Maintainers

Package info

Statistics

Security