Laravel Translation Linter Laravel Package

Technical Evaluation

Architecture fit. fidum/laravel-translation-linter is a developer-tooling package, not a runtime dependency. It fits as a require-dev entry in a Laravel application or package and surfaces as an Artisan command that scans lang/ files for missing, unused, or malformed translation keys. It does not participate in request handling, so it has no bearing on application architecture, service container bindings, or runtime performance. Fit is therefore high for any Laravel codebase that maintains translations, and neutral for codebases that do not.

Integration feasibility. Integration is a single Composer install plus optional CI wiring. There is no configuration surface to speak of, no migrations, no published assets, and no service provider behavior that alters the application. The realistic work is deciding where it runs (local pre-commit, CI job, or both) and agreeing on a failure policy for its exit code.

Technical risk. Low. The 3.0.1 release is a dependency-support patch that widens the constraint to include Laravel 13 (PR #34, first contribution from a new maintainer). There are no reported API changes, no deprecations, and no behavioral changes. Residual risks are the usual ones for a small, single-maintainer-adjacent package: bus-factor, low release cadence, and the possibility that a future major version changes its output format or CLI flags in ways that break CI parsing. Because it is dev-only, a breakage degrades developer workflow rather than production availability.

Key questions.

• Does the team need this in CI only, or also as a local pre-commit gate? This determines the enforcement model.
• Do we parse its output, or only rely on exit codes? Output parsing is the main coupling risk across future majors.
• Does the package support non-standard translation loading (JSON translations, lang paths registered by packages, or Spatie-style translation storage)? Scope coverage is unclear from the release notes alone.
• What is the maintainer's track record beyond this release, and is there a documented upgrade path for majors 1 → 2 → 3?
• Is the Laravel 13 bump a constraint widening only, or does it also raise the minimum PHP version? That governs whether our oldest supported app can use 3.0.1.

Integration Approach

Stack fit. Requires a Laravel application and a traditional file-based lang/ directory. It assumes PHP and Composer versions consistent with the Laravel 13 support matrix. If the estate runs Laravel 10/11/12 with older PHP, 3.0.1 should remain installable assuming the constraint is a range rather than a floor, but that must be verified in composer.json before rollout. Applications that read translations exclusively from a database or external service will get little value.

Migration path. Since there is no prior installation, this is a greenfield adoption rather than a migration. Recommended sequence: add as a require-dev dependency pinned with a caret constraint (^3.0), run the command manually against one small service to observe output volume, then codify it. If a comparable tool already exists in the pipeline (e.g. a custom script or PHPStan rule), retire the overlapping check only after the new command has run in warn-only mode for a sprint.

Compatibility. The 3.0.1 change is additive compatibility. The main compatibility question is not Laravel 13 but the reverse: confirm that adopting ^3.0 does not drop support for the oldest Laravel version still in production. For teams standardized on Laravel 13, 3.0.1 removes a pinning workaround that would otherwise be needed with 3.0.0 — that is the concrete benefit of this release. No lockfile conflicts or transitive dependency risks are introduced by a dev-only tool.

Sequencing.

1. Verify PHP/Laravel constraints of the package against the fleet's oldest supported application.
2. Install in one representative repository; baseline the current violation count so the first run does not block delivery.
3. Add a CI job in non-blocking mode; publish a short internal note on how to remediate common findings.
4. After two to four weeks, promote to blocking and consider a pre-commit hook.
5. Roll out to remaining repositories using the same pin and job template.

Operational Impact

Maintenance. Near-zero runtime maintenance; the only recurring task is routine dependency bumps alongside Laravel upgrades. The package itself is small and has a narrow surface, so version churn should be infrequent. Assign a named owner for the CI job — unowned lint gates rot into either permanent noise or silent disablement.

Support. Support burden is developer-facing, not user-facing. Expect questions of the form "why is this key flagged?" during the first weeks, particularly for dynamically constructed translation keys (e.g. __("errors.{$code}")), which static analysis typically cannot resolve and may report as unused. Document the suppression mechanism, if one exists, before enabling blocking mode.

Scaling. Scales linearly and cheaply: the command runs in CI per pull request, completes in seconds for typical lang/ trees, and adds no production footprint. Very large monorepos with thousands of keys may see slower runtimes or noisier first-run baselines; scope the command to changed directories if that becomes a friction point.

Failure modes.

• False positives on dynamic keys — the most likely cause of abandonment; mitigate with a baseline or suppression list.
• Constraint breakage — a future major bump arrives with a Laravel upgrade and blocks the lockfile; dev-only, so low blast radius.
• Silent disablement — the job is made non-blocking during an incident and never re-enabled.
• Output-format coupling — if we parse its console output for reporting, a minor release can break the parser; prefer exit codes.
• Patch-level supply-chain exposure — 3.0.1 ships a first-time contributor's change; standard review of the diff (a dependency constraint edit) is proportionate here.
• Abandonment — low release cadence is a real possibility; the exit path is a custom Artisan command, which is a day or two of work.

Ramp-up. Effectively zero for developers: install, run, read output. Budget roughly half a day of engineering time for initial setup and CI wiring, plus a small amount of TPM/tech-lead time to agree on enforcement policy. Recommend adopting with a caret pin on ^3.0, non-blocking initially, and a single named owner.