Po Parser Laravel Package

Technical Evaluation

Architecture fit. The package is a pure-PHP, Composer-installable parser with no framework coupling, no PHP extension requirements (notably it does not need ext-gettext), and a narrow responsibility: read a Gettext .po catalog into a PHP structure and (in recent versions) write it back. That narrowness is its main architectural virtue for a Laravel codebase — it slots in as an ingestion/adapter concern behind an interface we own, rather than as a runtime translation engine. The important framing for planning: Laravel's Translator expects key => string|array lookups via Illuminate\Contracts\Translation\Loader; PO files carry additional semantics (plurals, contexts, fuzzy flags, obsolete entries) that Laravel's storage model does not natively represent. So this package is a build-time and back-office dependency, not a per-request one. Judge it that way.

Integration feasibility. High for a first proof of concept, moderate to productionize. Parsing a file is a handful of lines; the work is entirely in the glue: a PoCatalogReader abstraction, a loader or compiler, a caching strategy, and validation. The package ships no Laravel service provider, config, facade, or published assets, so 100% of the framework integration is ours — realistically 2–4 engineering days including tests, not the 1 hour the README implies. There is also a naming trap: the canonical, maintained line is pherrymason/php-po-parser (namespace Sepia\PoParser, v3 requires PHP 8.1+), whereas sepia/po-parser is the long-abandoned original whose last releases target PHP 5.x. A composer require against the wrong name yields dead code.

Technical risk. Concentrated in correctness, not availability:

• Plural forms. msgid_plural / msgstr[0..n] need per-locale plural rules (CLDR) to select the right index. The parser gives you the raw array; correct selection is our code. Slavic and Arabic locales are where naive count() > 1 logic fails silently.
• Catalog semantics. msgctxt disambiguation can collapse two entries onto the same Laravel key; #, fuzzy entries must not be shipped; obsolete entries (#~) must be dropped; multi-line msgstr must be rejoined exactly; charset/Content-Type header handling matters for non-UTF-8 legacy catalogs.
• Memory and untrusted input. Parsing loads the whole catalog into memory and is regex/state-machine based, so a multi-megabyte catalog uploaded through an admin UI is a denial-of-service surface. Bound upload size and run imports in a queued job with a timeout.
• Lineage and bus factor. One maintainer, ~126 stars, effectively no downstream dependents to act as a canary. BSD-3-Clause means forking is legally trivial, which is the mitigation — but budget for it.
• No .mo compilation. If any runtime path expects compiled gettext binaries, this package does not provide them; that would be a separate tool.

Key questions to resolve before committing.

1. Is the .po file the source of truth, an interchange format with translators, or a build artifact? These lead to three different architectures.
2. Which component owns plural selection and locale rules — us, or an existing i18n library?
3. What is the realistic maximum catalog size, and is parsing ever on a request path?
4. Do we need round-trip write-back (export for translators, re-import), or read-only?
5. If upstream goes quiet, do we fork in-house, vendor the source, or fall back to gettext/gettext (more popular, broader PO/MO/translation-management surface)?
6. Does security review require sandboxing of user-supplied catalogs?

Integration Approach

Stack fit. PHP 8.1+, Composer, zero extensions, no global state — a clean fit for Laravel 10/11/12 with opcache. It also fits queue workers, Artisan commands, and CI containers without extra system packages, which is a real operational win versus installing gettext tooling.

Three viable architectures — pick one deliberately.

• (A) Compile-at-build (recommended). PO catalogs live in the repo; a translations:compile Artisan command parses them and writes optimized PHP arrays into lang/ (or a cached array store). Laravel's native FileLoader serves them at runtime; the parser never runs in production traffic. Best latency, smallest blast radius, easiest rollback.
• (B) Custom loader. Implement Illuminate\Contracts\Translation\Loader backed by the parser, reading PO directly. Simplest to wire, but pays parse cost per request unless aggressively cached, and pushes plural/context handling into the hot path. Acceptable only with a compiled cache in front of it, at which point it converges on (A).
• (C) Database-backed translation store. PO becomes the import/export format for an admin UI where product and localization vendors work. Highest business value if non-engineers edit copy, highest build cost. Pairs naturally with (A) as the export path.

Recommendation: (A) as the runtime path, (C)'s import/export as a separate, permissioned admin tool later. Do not adopt (B) as the steady state.

Compatibility and containment. Wrap the library behind our own PoCatalogReader interface returning a normalized DTO (key, context, plurals[], flags[], isObsolete) so upstream API changes, a fork, or a swap to gettext/gettext is a one-file change. Pin the exact version; require pherrymason/php-po-parser, never sepia/po-parser. Normalize encoding to UTF-8 at the boundary and reject catalogs whose declared charset disagrees with the bytes.

Sequencing.

1. Spike: parse two real, messy catalogs (one large, one with plurals/contexts/fuzzy/obsolete) and diff against msgfmt --check. Timebox one day.
2. Define the DTO and PoCatalogReader interface; write contract tests against fixtures.
3. Build the translations:compile command and cache-invalidation hook (deploy step, not request-time).
4. Add CI validation: parse every catalog, fail on duplicate keys, fuzzy-only entries, empty msgstr, and header/charset mismatch.
5. Migrate one low-risk locale end-to-end; compare rendered output against the incumbent path in staging.
6. Extend to all locales; retire the legacy loader.
7. Only then evaluate the admin import/export UI on top of the same reader.

Operational Impact

Maintenance. Low upstream churn — a plus for stability, a minus for bug turnaround. Assume no upstream SLA and plan a fork budget (a few hours per year, plus a security-watch task). The dependency is small and pure PHP, so composer audit exposure is minimal and patch application is cheap. The real maintenance cost sits in our adapter and in plural-rule correctness, both of which we own regardless of which library we choose.

Support. First-line support shifts to the internal team, because the failure modes are domain failures (bad catalogs, wrong plural index, mojibake) rather than library failures. Expect recurring tickets of the form "German string is English in production" — almost always a stale compile step or a dropped msgctxt. Build tooling that makes those two causes self-evident: a compile log per locale and a key-collision report.

Scaling. Parsing is O(file size) in memory and time; a 50k-string catalog is comfortably a build-time job in seconds and a bad idea per request. Compile output is plain PHP, so runtime cost collapses to Laravel's normal array lookup plus opcache — no scaling concern, no shared state, no concurrency hazards, horizontally safe across web and queue nodes. Import jobs for very large catalogs should be chunked or capped by upload size limit.

Failure modes to design against.

• Malformed or truncated PO aborts the import — wrap in try/catch, quarantine the file, alert, never partially publish.
• Silent partial parse (parser tolerates garbage) — enforce a post-parse assertion on expected entry count vs. previous build.
• Plural index out of range for the locale's rule set — validate at compile time, fail the build.
• msgctxt collisions collapsing distinct entries — detect and hard-fail.
• Encoding mangling on non-UTF-8 input — normalize and assert.
• Stale compiled cache after deploy or hotfix — make compilation part of the release pipeline, not a manual step.
• Uploaded catalog as a memory-exhaustion vector — size cap, queued execution, timeout.

Ramp-up. A mid-level Laravel developer reads the API in under an hour; shipping the reader, compiler, command, and test fixtures is 2–4 days. Add roughly a day of localization-domain onboarding (plurals, contexts, fuzzy workflow, POEdit round-trips) for whoever owns the tooling, since that knowledge — not the library — is what prevents incidents. Translator-facing stakeholders need a short briefing on the POEdit workflow and on what "fuzzy" means for whether their string ships.