Run the documented translator adapters, and rewrite the prose round them

[jakejackson1]

Follow-up to #35. Nothing ran the translator adapters the README told a caller to write. Wiring one up against the real library found a bug, so this adds the checks, the per-library pages, and a prose pass over what was left.

A bug, found by running the documented code

Symfony's PoFileLoader reads a .po into one catalogue entry per msgid — including entries still carrying an empty msgstr. trans() then answers '' for anything not yet translated:

before:  untranslated msgid rendered as ""      ← blank message, on the failure path
after:   untranslated msgid rendered as "Unknown error"

Gettext defines an empty msgstr as untranslated. Symfony's loader does not apply that rule, so Translation::translate() now does — for every loader, not just that one.

Anyone with a partly-translated catalogue would have shown blank error messages to whoever submitted the file.

The checks

tools/translator-readme/, built the way tools/psr7-readme/ already is: its own pinned manifest so the library still depends on nothing, and a verify.php that reads each snippet out of the documentation at run time rather than copying it. Reword an adapter and the extraction fails by name.

The libraries are Composer dependencies installed in CI on PHP 7.3 and 8.5 — one pinned set resolves on both; illuminate/translation 8.x is the newest that still installs on 7.3.

Each adapter is checked for three things: a translated msgid comes back translated, an untranslated one falls back to English rather than an empty string, and a value still interpolates.

The catalogue is built by running the documented commands — msginit, msgfmt --check, msgmerge, msgattrib — not approximated in PHP, so the pipeline a reader follows is the one under test. Symfony and php-gettext consume a real GNU message catalog.

WordPress

wp i18n make-pot runs before WordPress loads, so the extraction half needs wp-cli but no WordPress and no database. wordpress.sh builds a plugin tree from git archive — what it holds is what a consumer's vendor/ holds — runs the documented make-pot --merge, checks the library's msgids and the plugin's own survived, then compiles and reads the result back.

It also asserts the negative the WordPress page turns on: that a catalogue left inside vendor/ is still invisible to make-pot. That claim would otherwise rot silently.

The runtime half that actually goes wrong is pinned in PHP instead. marker-import.php imports this library's __() marker and calls both __() and \__() — the situation the docs warn about, where a missing backslash makes the translator a silent no-op.

Mutation-tested, not just green

mutation	result
empty-string fallback removed	Symfony: an untranslated msgid rendered as ""
Symfony snippet reworded	The Symfony adapter is no longer in the documentation
expected msgid absent	the library's msgids are missing from the merged catalogue

One mutation I ran was invalid: emptying i18n/upload.pot in the working tree does not fail wordpress.sh, because it builds from git archive HEAD. That is the script working as designed, but it means working-tree edits cannot mutation-test it.

I also confirmed msgfmt --check earns the place the docs give it — a translation dropping a %1$s gives a format specification for argument 1 doesn't exist in 'msgstr', because xgettext marks those entries #, php-format.

Documentation

One page per library under docs/translation/, each with its adapter, the commands to build its catalogue, and its gotchas — Symfony's empty-msgstr behaviour, Laravel's printf placeholders not being :name, php-gettext's two-package split, and the whole wordpress.org limitation including why --include proves nothing.

The README links rather than repeats. That matters for the check as much as for length: with a snippet in two places, verify.php would only exercise whichever copy it found first, so a stale one could pass.

docs is added to package.yml's expected top level, so the pages ship.

Prose

The docblocks and docs added in #35 were written at length rather than for clarity — the same fact twice in different words, asides longer than their clause, sentences narrating why a design is good rather than what it does. i18n.php carried twenty lines of docblock over a function whose body is return $text;. UPGRADE.md described six reworded messages in a paragraph where a before/after table is what somebody upgrading wants.

Verification

551 tests, PHPStan level 9, PSR-12, parallel-lint, the PSR-7 bridge, the translator adapters and the WordPress pipeline all pass locally. No message id moves and i18n/upload.pot regenerates byte for byte.

The wp-cli download and apt-get gettext steps have only run on my machine — this PR's own CI run is the first real test of the new workflow.

🤖 Generated with Claude Code