Extractor Laravel Package

Technical Evaluation

Architecture fit The package is a statically-analyzable, CLI-first code scanner, not a runtime dependency. It parses PHP ASTs (via nikic/php-parser 5) plus Blade/Twig templates and emits translation catalogues. For a Laravel codebase this means it sits cleanly at the build-time layer: it reads app/, resources/views/, and lang/, and writes/updates lang/**/*.php or *.json. It does not intercept __()/trans() at runtime, does not alter the request path, and does not add bundle weight to production. That is the right architectural shape for localization tooling and keeps blast radius low — a bad extraction run corrupts catalogues, not user traffic.

The v2.2.x–2.4.x line tells a coherent modernization story that matters for a TPM: dropped PHP 7.x/8.0, added PHP 8.1–8.3, Symfony 7 (v2.2.0) then Symfony 8 (v2.4.0), nikic/php-parser 5 only (v2.2.2), and removal of Doctrine annotations (v2.3.0). v2.3.2's "use host PHP version instead of hardcoded version to parse newer syntax" is the single most important architectural detail — it removes the classic extractor failure where the parser lags the language and silently misses new syntax. The remaining architectural gap is JavaScript/TypeScript and Vue/React string extraction; the description claims JS scanning, but the Laravel reality is that most modern front-ends need a separate scanner (i18next-scanner, vue-i18n-extract). Any plan that assumes one tool covers the whole stack is wrong.

Integration feasibility High, with caveats. Integration is composer require --dev php-translation/extractor, a config file declaring source paths and target catalogues, and a CLI invocation in CI. No service account, no network egress, no vendor onboarding, no data-processing agreement — a meaningful procurement advantage versus Crowdin/Lokalise. Two integration concerns are real:

1. Format and key-strategy coupling. The extractor's output must match the key convention your app already uses. Laravel apps commonly mix __('messages.welcome') (keyed) with __('Welcome back') (string-as-key). The package handles both, but mixing them in one catalogue produces duplicated, unmergeable entries. This is a decision, not a bug, and it must be made before the first run — retrofitting key strategy across a mature catalogue is expensive.
2. Write semantics. "Creates missing entries while preserving existing" is the right default, but the team must verify empirically whether it removes stale keys, reorders files, or rewrites formatting. Any of those turns every extraction run into a large, review-hostile diff and invites merge conflicts with the translation vendor's export files.

Technical risk The dominant risk is silent false negatives, not crashes. An extractor that misses a string produces a catalogue that looks complete and ships an untranslated string to a customer in a target market. This is a quality failure with commercial consequences, and it does not surface in tests. Contributing factors:

• Coverage is heuristic. Symfony Form constraints, concatenated labels, and array placeholders were each added in discrete PRs (v2.1.0, v2.2.x). This is a coverage-by-patchwork pattern: expect gaps in less common idioms — dynamic key construction (__("errors.{$code}")), keys from config or DB, translations in packages/vendor, Livewire/Inertia payloads, and strings inside @php blocks.
• Ecosystem signal is thin. 128 stars and 0 dependents is a genuine flag for a TPM. Zero dependents usually means "consumed as a CLI dev-tool, so it never appears as a library dependency" — but it also means few organizations have stress-tested it at scale. Do not treat this as enterprise-supported software.
• Release cadence is responsive but bursty. Most recent work is single-PR patch releases from individual contributors (mgiraud, GCth, nexxome, BenoitLeveque). Good for turnaround, weak for predictable SLAs. There is no vendor to escalate to.
• PHP-version coupling. Host-version parsing is a feature and a constraint: the extractor can only understand syntax your build agent's PHP can parse. Pin the CI PHP version deliberately.

Key questions for engineering

• What percentage of our translatable strings are (a) static literals in Blade/PHP, (b) dynamically constructed keys, (c) in JS/Vue/React, (d) in DB or config? We need this ratio before committing — the extractor only owns category (a).
• Which key convention do we standardize on, and does the extractor's output format match our existing lang/ layout exactly?
• Does a run on our current main produce a diff of zero lines? If not, why — and is that diff churn or genuine drift?
• Can we run the extractor twice and get a byte-identical result (idempotency)? This is a hard gate for CI adoption.
• Is the tool deterministic across machines (file ordering, locale, line endings)?
• What is our baseline false-negative measurement? We need a manual spot-audit of a sample of views against extracted output, or the coverage number is fiction.
• Does our CI runner pin a PHP version, and is it ≥ 8.1?

Integration Approach

Stack fit The extractor is a strong fit for the Laravel/PHP half of the stack and a non-fit for the front-end half. Concretely:

• Fits well: Blade templates (@lang, @choice), PHP translation calls (__(), trans()), Symfony/Laravel form types, validation constraint messages, JSON and PHP catalogue formats, Composer-based dependency management, PSR-4 source trees.
• Does not fit: JS/TS/Vue/React strings, translations held in a CMS or database, runtime-generated keys, and any non-PHP service. Those need a separate track or an explicit scoping decision to defer.
• Composer hygiene: install as require-dev. It should never appear in the production dependency graph; if it does, that is a review defect.

Migration path Recommended as a three-phase, non-destructive rollout rather than a switchover:

1. Shadow mode (1–2 sprints). Run the extractor to a separate output directory (lang/extracted/ or a build artifact). Never touch the live catalogues. Diff the generated output against the existing catalogues to quantify drift: how many keys are missing, how many are stale, how many are duplicated. This produces the business case and the coverage baseline in one step, at near-zero risk.
2. Additive mode. Once the drift report is understood, allow the tool to write missing keys only, on a branch, with human review. Keep existing keys immutable. This is where you validate idempotency and diff-noise.
3. Gated automation. Only after phases 1 and 2 are clean does extraction run on merge and open/update a PR, or run as a scheduled job. Never let it commit directly to main initially — a bot commit that rewrites 400 catalogue files is unreviewable and unrevertable in practice.

Compatibility

• PHP: pin CI to 8.1–8.3. Do not assume 8.4 syntax parses until verified; v2.3.2's host-version parsing helps but the parser version is the ceiling.
• Laravel: works against Laravel 10/11-era stacks. Verify Blade directive coverage for any custom directives in use; @lang/@choice are supported, bespoke @trans-style directives may not be.
• Symfony: explicit Symfony 7 support (v2.2.0) and Symfony 8 allowance (v2.4.0). If we later move to Symfony 8, the version constraint is already open — but "allowed" is not "tested"; re-run the audit after any major framework bump.
• Dependency conflicts: low risk (no hard Laravel/Symfony coupling), but verify nikic/php-parser v5 alignment with existing dev tooling (PHPStan, PHP-CS-Fixer, Rector all consume the parser) using composer why-not nikic/php-parser 5.x. A parser version split between two dev tools is the most likely integration blocker.
• Format compatibility: confirm the tool's PHP/JSON output matches what our translation vendor imports/exports, or we create a lossy translation step in the middle of the pipeline.

Sequencing

1. Decide key convention and catalogue format (product + eng, ~1 week).
2. Shadow-mode run and drift report (eng, ~1 week) — gate for everything else.
3. Build-vs-buy checkpoint: compare drift report and effort against adopting a managed platform. This is the natural decision fork; do not skip it because the package is free. "Free" excludes the engineer-hours for the audit, the CI wiring, and ongoing gap triage.
4. Additive-mode extraction with PR review (~1 sprint).
5. CI gating + a documented manual-escalation path for dynamic strings.
6. Only then: front-end string extraction (separate tool), vendor sync, and locale onboarding.

Operational Impact

Maintenance Light on dependencies, non-trivial on process. The package itself requires little upkeep: MIT licence, Composer install, no version-pinned service. The sustained cost is elsewhere:

• Ownership must be named. Localization tooling is classically unowned — it works until someone changes a key convention, and then no one remembers who owns the pipeline. Assign a named engineer (rotating is acceptable) for the extraction job and the catalogue merge policy.
• Version pinning. Pin the extractor version in composer.json and upgrade deliberately, testing against the diff, not automatically. Patch releases here are behavioural (v2.4.2 fixed an argument-length crash), and a behaviour change in a scanner is a silent catalogue change.
• Parser coupling. Any nikic/php-parser major bump in the dev toolchain requires a re-audit of extraction output.
• Deprecation watch. v2.3.0 removed Doctrine annotations and v2.3.1 deprecated the annotation classes. If we rely on annotations anywhere, plan the migration now rather than at the removal release.

Support There is no support contract and no vendor escalation. Support model is community GitHub issues on a 128-star project. Realistic assessment: bug turnaround is decent (many recent PRs are one-line fixes from individual contributors) but there is no response-time commitment, no security advisory process we can point to, and no roadmap we can plan against. Mitigations:

• Treat it as a dev-time tool only, which caps the security posture question — nothing in the production runtime path means no new attack surface.
• Vendor the version and keep a documented fallback: a manual or scripted extraction path that a single engineer can execute if the tool breaks. The fallback needs to be written down, not assumed.
• Do not build a customer-facing SLA on top of this tool's reliability.

Scaling Scales linearly with codebase size and cleanly across locales — each locale is another output target, not another tool instance. Practical limits:

• Run time grows with source tree size; fine for a monolith, potentially slow in a large monorepo. Acceptable as a scheduled job rather than a per-commit gate if it becomes slow.
• Catalogue size is the more interesting constraint: extraction accuracy matters more as locales multiply, because a missed key is one untranslated string but a spurious key is one untranslated string × N locales × perpetual maintenance. Key hygiene is the scaling lever.
• Team scaling: the tool does not scale translation workflow — it scales string discovery. Reviewer throughput and vendor turnaround become the bottleneck well before the extractor does.
• Front-end scaling is out of scope and will need its own decision, budget, and owner. Do not let "we solved localization" be the conclusion when only PHP/Blade is covered.

Failure modes Ranked by actual business impact:

1. Silent false negatives (highest impact, lowest visibility). A string is missed, the catalogue looks complete, an English string ships in a German store. Detection requires either a manual audit or runtime monitoring for untranslated content — the extractor will never tell you. Mitigation: quarterly sampled manual audit; a lint rule that forbids dynamic key construction where avoidable; runtime logging of untranslated keys in staging.
2. Catalogue churn / merge conflicts. If runs reorder or reformat files, every run collides with translator exports and human edits. Mitigation: idempotency test as a CI gate; extraction to a dedicated branch; a merge policy that makes the extractor the sole writer of missing keys only.
3. Accidental key deletion or overwrite. Verify "preserves existing entries" empirically before enabling writes. If a run can delete keys, a bad run removes translated content for every locale simultaneously. Mitigation: extraction must run against a clean tree with the catalogue change reviewable and revertable as a single commit.
4. Dependency/parser breakage in CI. A parser version conflict blocks the whole dev toolchain (PHPStan, Rector, CS-Fixer), not just extraction. Mitigation: composer why-not check in the upgrade checklist; pin parser major.
5. PHP version drift. CI upgraded to a PHP version the extractor can't parse → extraction silently degrades or fails. Mitigation: explicit PHP pin in the CI image and a smoke test that asserts a known string is extracted.
6. Abandonment. Low stars, small contributor pool. Mitigation: acceptable because it is dev-time and MIT; the fallback path plus a periodic "is this still maintained?" review covers it. This is a review item, not a blocker.

Ramp-up Low for engineers, moderate for the organization.

• Engineer ramp: under a day. Composer install, one config file, one CLI command. The learning curve is in understanding what it misses, not how to run it.
• Process ramp: 2–3 sprints to shadow mode, drift analysis, and gated automation. The sequencing above is the ramp; skipping the shadow phase is the most common way this goes wrong.
• Org ramp: the real effort is policy — key convention, translation vendor handoff, who reviews catalogue PRs, what "done" means for a locale launch. That is product/TPM work, not engineering work, and it gates the value more than the tool does.
• Ramp artifacts to produce: a one-page runbook (how to run, how to revert), a coverage baseline number with its measurement method, and a documented manual fallback. Without the baseline, you cannot tell whether the tool is helping.