Download the PHP package celema/verba without Composer

Celema Verba

Gettext-style internationalization for PHP without the gettext extension.

Verba keeps the workflow you know from gettext — mark strings in code, extract them, translate, ship — but drops the parts that make the extension awkward to operate:

• No server restarts. Catalogs are plain PHP array files served from opcache; editing one takes effect on the next request.
• No system locales. Plural rules ship with Verba; nothing to install with dpkg-reconfigure locales.
• Works in CLI and CI. Extraction and status checks are pure PHP.

The interchange format is plain PHP arrays, not .po/.mo, and there is no fuzzy matching: a changed message id is simply a new entry.

Verba translates messages; it does not format numbers, dates, or currency. That is localization, and PHP already has the ICU-backed tool for it — ext-intl (NumberFormatter, IntlDateFormatter, MessageFormatter), the PHP counterpart to Babel. Verba deliberately stays out of it: formatting needs CLDR data and the intl extension, which would undo its "no extension, no system locales" premise. Pair the two when you need both.

Marking strings

Eight global functions are always available:

Arguments interpolate in one of two styles. A single array argument fills named :placeholder tokens; anything else is passed to sprintf:

In __n/__np/__dn/__dnp, :count is bound to the count automatically, so __n(':count file', ':count files', $n) needs no extra argument.

A context distinguishes uses of the same message id without becoming part of the output. For example, German may translate __p('menu', 'Open') as Öffnen but __p('state', 'Open') as Offen. Context is an exact lookup axis: a miss never falls back to an uncontextual translation or another context.

With no translator active the functions return the message id itself (after interpolation), so calls are safe in tests, CLI, and early boot.

Escaping

Verba does not escape anything — it cannot, since the same catalog feeds HTML, attributes, JSON, and the terminal, and only the boundary that emits a string knows the right encoding. Two rules follow:

• Translations are trusted, author-controlled content. A msgstr may contain markup (<strong>, links) on purpose; Verba passes it through untouched. Your template decides whether the result is rendered as raw HTML.
• Placeholder values are inserted verbatim. A :name value goes in as-is, so escape untrusted input for its output context at the call site: __('Hi :name', ['name' => htmlspecialchars($user->name)]) for HTML, and no escaping for CLI.

Runtime

A Translator is bound to one locale and an ordered cascade of domains, each mapping to the directory that holds its catalog files. The first domain with a translation wins; a miss falls back to the message id.

__d('cosray', …) and the other __d* helpers pin the cosray domain; bare helpers search the cascade. A domain selects a catalog, while a context selects a translation variant inside each catalog.

A third argument names fallback locales, tried in order whenever the primary locale lacks a string. Resolution is per id and stays within a domain before the cascade continues, so the domain cascade outranks the locale fallback:

Locale ids may contain ASCII letters, digits, hyphens, and underscores, for example zh-Hant or pt_BR. They become catalog filename segments.

This keeps a partially translated locale usable — untranslated ids surface in en instead of as raw message ids. Translator::exportMany() ships locale-specific payload entries in resolution order, each with its own plural rule; entries with no reachable messages are omitted. The JavaScript runtime therefore resolves the same chain. Fallback is a runtime concern only: extraction and i18n:status stay per catalog file, so an empty es catalog still reports as untranslated.

Catalog files

One file per domain and locale, named <domain>.<locale>.php. See the catalog format reference for the complete schema and its design rationale.

• A string is a translation, a list holds the plural forms in rule order, and null marks a known-but-untranslated id.
• contexts groups active translations by context; obsolete_contexts parks vanished contextual messages. Both use the same value types as messages.
• Plural rules for common languages are built in. A catalog may borrow another language's rule with 'plural' => 'ru'.

Extraction

Scanners find the calls; a Domain ties them to a catalog directory and locale set.

• PhpScanner walks the PHP token stream — no parser, no regex — and reads all eight helpers with literal message, domain, context, and plural arguments. Boiler templates are PHP, so they are covered too.
• JavascriptScanner reads .js, .ts, .jsx, .tsx, .svelte, and .vue. Only literal arguments are captured; a dynamic id, domain, context, or plural is reported as a warning and skipped.

JavaScript runtime

The JavaScript runtime in js/ mirrors the PHP one in the browser: the same eight functions, contexts, plural rules, and named :placeholder interpolation (positional sprintf arguments stay PHP-only). Hand it the catalogs with Translator::exportMany(), inlined as JSON — list only domains meant for the browser, since the payload is readable in the page source:

The runtime is plain ES modules with JSDoc types in js/src/, so a browser loads it as it is: the Composer package carries it, and an import map can point @celema/verba at js/src/index.js. The @celema/verba npm package ships the same files plus type declarations for bundlers.

With no translator active the functions return the interpolated message id, mirroring PHP. During SSR, loadAndActivate() returns null because no DOM is available, so the global helpers use this fallback. Do not call the module-global activate() from a request handler because concurrent requests could share translators. The helper API does not currently support request-local translated SSR.

Commands

Register the two commands with your celema/console runner, passing the domains to maintain:

• i18n:sync — scan sources and reconcile every catalog. New ids are added as untranslated, existing translations are kept, a reappearing id is restored from its obsolete section, and a vanished id is parked there and named in the output. Running it twice changes nothing. --prune drops ordinary and contextual obsolete sections, naming what it drops.
• i18n:status — report per locale how many ids are missing, untranslated, translated, and obsolete. --strict exits non-zero on any gap (a CI gate); --where lists the source locations of the gaps and the obsolete ids, telling those a sync already parked from those still in the live section.

Mutation testing

Mutation testing with Infection is not part of composer ci, but the CI workflow runs it after the coverage step and enforces the minimum mutation score from infection.json5.dist. Pushes only mutate the changed lines; a weekly scheduled run covers the whole codebase. Run it locally with:

Reports are written to .infection/.

License

This project is licensed under the MIT license.