Laravel Translation Scanner Laravel Package

Technical Evaluation

Architecture fit

• Developer-tooling package, not runtime infrastructure. It belongs in require-dev, ships Artisan commands, and produces a report plus optional file mutations against lang/ (or resources/lang/ on older skeletons).
• Fits naturally into the "shift-left quality gate" layer alongside Pint, PHPStan/Larastan, and Pest — no service provider surface area in production, no DB, no queue, no external service.
• Value is concentrated in one job: reconcile static translation key usage against translation catalogs (missing keys, unused keys). Treat it as a lint rule, not a translation management system.

Integration feasibility

• Low-friction install: composer require --dev, auto-discovered provider, optional config publish, single scan command. A developer can produce a first report in under an hour on a mid-size app.
• No schema, no migrations, no data backfill, no credential handling. Reversible by removing one dependency.
• CI integration is the main work item: deciding report-only vs. blocking, and scoping paths to exclude vendor/generated code.

Technical risk

• Core risk is heuristic accuracy. Static scanning of __(), @lang, trans(), trans_choice() will produce false positives for dynamically composed keys (__('errors.'.$code)), and false negatives for keys built at runtime or resolved from packages. Teams that over-trust a green scan will ship untranslated strings.
• Secondary risk is catalog-shape coverage: nested PHP arrays, JSON translation files, pluralization variants, and Laravel 11+'s moved lang/ directory are all places where a scanner's assumptions can silently diverge from the framework's.
• Release-specific risk: v5.6.3 is published with only a compare-link changelog and no described entries. A patch bump implies no intended breaking change, but the actual diff is unverified — bug fixes to the parser and config defaults both land in patch releases and both change scan output. Change content is opaque; pin the version and read the diff before adopting.
• Key questions to put to the maintainer or resolve in a spike:
  • What changed in 5.6.3, and does it alter scan results versus 5.6.2?
  • Supported PHP and Laravel version matrix (specifically Laravel 11/12 lang-path handling).
  • Does it handle trans_choice, JSON catalogs, vendor namespaced keys (package::file.key), and keys inside Enums/attributes?
  • Are false positives suppressible via config/ignore annotations, or only by editing paths?
  • Does any command write to files by default, or is dry-run the default?

Integration Approach

Stack fit

• Assumes a conventional Laravel app or package with Blade + PHP translation calls and file-based catalogs. Poor fit for apps that resolve translations from a database, a headless CMS, or a third-party TMS at runtime — in those cases the scanner's source of truth isn't the source of truth.
• Language/framework fit should be confirmed before anything else; a version-constraint mismatch here is a hard stop.

Migration path

• No data or schema migration. The only "migration" is process: baseline the existing debt, decide the acceptable threshold, then ratchet.
• Keep it dev-only and out of production images. If the build runs composer install --no-dev, the tool must not be referenced by any runtime code path.

Compatibility

• Pin an exact version in composer.json rather than a caret range, given the changelog void. Re-evaluate deliberately on each bump.
• Verify coexistence with existing static-analysis config: overlapping concerns with unused-key detection already implemented in some i18n linters, and duplicate CI minutes if both run.
• Verify path configuration explicitly on Laravel 11+, where lang/ moved to the project root — misconfiguration here yields an empty catalog and a deceptively clean report.

Sequencing

1. Spike on one representative repository; capture key counts, runtime, and a sample of false positives.
2. Publish a baseline report (informational only) so the team sees the debt before it becomes a gate.
3. Triage findings: real missing keys fixed; false positives recorded as documented exclusions.
4. Enable blocking CI on changed files only, not the whole repo, to avoid a frozen backlog blocking unrelated PRs.
5. Add a scheduled full scan (nightly/weekly) for drift the incremental gate won't catch.

Operational Impact

Maintenance

• Small, single-purpose dev dependency: low ongoing maintenance burden, but a correspondingly thin release-notes culture. Upgrades require diff review rather than trust in semver. Budget ~1–2 hours per bump for a mid-size app.
• Parser behavior depends on the codebase's idioms; refactors that change how keys are composed can change scan output without any package upgrade. Re-baseline after large i18n refactors.

Support

• Community OSS with bus-factor exposure. No SLA, no vendor escalation path. Contingency is a fork, or replacing the scan with an in-house script — a few days of work, and worth pre-agreeing as the fallback so the CI gate is never load-bearing on an unmaintained tool.

Scaling

• Cost scales with file count and catalog size, not traffic. Fine for typical apps; on monorepos, scope the scan to changed paths and run the full sweep out-of-band.
• The human cost scales faster than the compute cost: a large unused-key report is a triage backlog, not an automatable fix. Plan ownership before enabling the gate.

Failure modes

• False positives block merges → team disables the gate → tool becomes decorative. Mitigate with report-only rollout and an exclusion mechanism.
• False negatives give false confidence ("scan is green, so we're translated") — the most expensive failure because it is silent.
• Config drift after a Laravel upgrade produces an empty scan that looks like success. Assert on a known key in a smoke test.
• Opaque patch releases introduce behavior changes nobody reviews.
• If commands mutate files by default, a mis-scoped run can rewrite catalogs; confirm dry-run default before the first execution.

Ramp-up

• Low: a Laravel developer is productive within an hour; the config surface is small.
• The real onboarding is policy, not tooling: who owns the exclusion list, what threshold blocks a PR, and how false positives get adjudicated. Document those three things in the repo README and name a single owner.