Laravel Translation Audit Laravel Package

Technical Evaluation

• Architecture fit: The package remains a Laravel-native translation auditing tool exposed through Artisan commands, including translation:audit and translation:purge-unused. It fits Laravel applications that rely on Laravel’s translator and __() / @lang helpers, especially modular monoliths and apps with large, actively maintained locale files. v0.13.0 broadens pipeline fit by shipping a ready-made GitLab CI job alongside the GitHub workflow, so teams on either platform get a supported first-class integration. It remains a weaker fit for frontends with separate i18n pipelines or organizations standardizing on an external TMS unless export/import workflows are added.
• Integration feasibility: Still low application-code impact—adoption is Composer plus configuration plus CI. However, v0.13.0 is a breaking minor: unused_ignore_paths is removed and merged into ignore_paths, which is now scoped per audit via the new AuditType enum (Missing / Unused). The GitHub workflow publish tag is renamed to laravel-translation-audit-github-workflow. The public API is now delimited ahead of v1.0 (service provider, commands, AuditCommand, TranslationKeyResolver, Result and results, Data\Translation, DisplayFormat, SaveFormat, InvalidConfigException, AuditType), and every concrete class is final. Most applications will only need a config migration and a CI include; only teams that extended commands, results, or the service provider are materially affected.
• Technical risk: Pre-1.0 package, now with an explicit public/@internal boundary—good long-term signal, but v0.13.0 delivers real breaking changes. The highest-severity risk is the config merge: a published config that defines its own ignore_paths without adding the new defaults will cause Laravel’s own translation files (e.g. lang/*/validation.php) to be reported as unused and removed by translation:purge-unused. The tag rename can silently break existing publish scripts or CI bootstrap steps. Making classes final removes extension-based workarounds teams may have used to patch detection behavior. Per-audit ignore scoping is powerful but adds a new class of misconfiguration: a path ignored only for Missing still counts its keys as used (so purge-unused keeps them), while a path ignored only for Unused is still audited for missing keys—the inverse of what a reviewer might assume.
• Key questions:
  • Is there an upgrade guide or automated config migration for unused_ignore_paths → ignore_paths + AuditType, and does the package fail loudly when defaults are missing?
  • What Laravel and PHP versions are officially supported, and does the shipped GitLab CI job pin a PHP image, Composer install step, and cache strategy?
  • Do commands provide machine-readable output and non-zero CI exit codes for missing/unused keys?
  • How are dynamic keys resolved across locales, fallbacks, and vendor translations?
  • Does translation:purge-unused support dry-run, backup, or diff review, and does it fully honor AuditType scoping before deletion?
  • Are AuditType values and the public API surface now frozen until v1.0, or can they change in the next minor?
  • How does the package handle large codebases, many locales, and translation files that are unreadable or malformed?
  • What is the release cadence and backward-compatibility policy between now and 1.0?

Integration Approach

• Stack fit: Strong fit for Laravel apps using PHP-based locale files and Laravel’s translator. v0.13.0 makes this a genuine two-platform story: publish the GitHub workflow with --tag="laravel-translation-audit-github-workflow" or the GitLab job with --tag="laravel-translation-audit-gitlab-workflow" (written to .gitlab/ci/audit-translations.yml and included from .gitlab-ci.yml, running on default-branch pushes, merge requests, and web-UI pipelines). The umbrella laravel-translation-audit tag publishes config plus both workflows. Less direct fit for JavaScript-only translation files, mobile localization, or TMS-owned translation workflows.
• Migration path: Do not jump straight from an older version to v0.13.0 on a branch with purge enabled. First run a read-only pilot to capture a baseline of missing and unused keys, then upgrade and re-baseline—both because of the v0.12.7 dynamic-key/dotted-array-key detection changes and because v0.13.0 changes how unused keys are scoped. Explicitly audit the published config: add the former unused_ignore_paths patterns into ignore_paths mapped to AuditType::Unused (e.g. 'lang/*/validation.php' => AuditType::Unused) and re-add the Laravel defaults. Update any scripts referencing the old workflow publish tag. Only after triage and diff review should translation:purge-unused be introduced.
• Compatibility: Treat v0.13.0 as a breaking release despite the minor version, consistent with pre-1.0 SemVer. Validate against the project’s exact Laravel/PHP matrix, pin the package version, and test on the oldest and newest supported Laravel versions in use. Check whether any internal tooling extends the now-final commands, results, or service provider, or calls AuditTranslationsResult::withUnused() / jsonSections() (now @internal). Anything relying on those must be rewritten against the public API or pinned to v0.12.x.
• Sequencing:
  1. Confirm Laravel/PHP support, license, and whether the public API surface is stable until v1.0.
  2. Inventory existing customizations: config keys (unused_ignore_paths, ignore_paths, ignore_locales, ignore_keys), publish-tag usage, and any class extension of commands/results.
  3. Upgrade in a non-production branch; migrate unused_ignore_paths into ignore_paths with AuditType::Unused and restore the Laravel translation-file defaults.
  4. Run translation:audit to produce a fresh baseline and diff it against the v0.12.x baseline; triage new unused findings, especially any Laravel-provided translation files.
  5. Publish the GitHub or GitLab workflow and adapt it to the team’s PHP image, Composer caching, and branch policy.
  6. Add CI gating for the missing audit with a defined threshold or allowlist before enabling unused gating.
  7. Introduce translation:purge-unused only after dry-run/diff review and VCS rollback are established, verifying AuditType scoping protects shared/vendor files.
  8. Document ownership for locale files, AuditType ignore rules, CI exceptions, and periodic baseline refreshes.

Operational Impact

• Maintenance: Low runtime footprint—developer/CI tooling, not request-path infrastructure. Maintenance effort shifts slightly upward for this release: a one-time config migration, a publish-tag update in CI bootstrap, and a review of any extension points lost to final. The new public/@internal boundary should reduce future upgrade churn by making it clearer what is safe to depend on. Pre-1.0 status still warrants pinning and reading release notes before every upgrade.
• Support: Likely open-source community support without SLA. The shipped GitLab CI job lowers internal support burden for GitLab teams the same way the GitHub workflow did, and gives a canonical CI reference to point people to. The main new support topic will be AuditType semantics (which audit an ignore rule applies to) and the unused_ignore_paths migration; a short internal runbook covering both is worthwhile. A named internal owner should own configuration, AuditType rules, CI gating, and exception lists.
• Scaling: Suitable for large Laravel codebases if scans run in CI or scheduled jobs rather than developer hot paths. Runtime grows with number of PHP files, locales, and translation entries. Per-audit ignore scoping is a useful scaling lever—teams can exclude seeders or fixtures from Missing while still letting purge-unused see their key usage—but rule volume becomes its own maintenance surface at scale. Very large monorepos may still need scoped paths or split jobs, and purge-unused at scale can produce large diffs.
• Failure modes:
  • Highest risk: after upgrade, a published config with custom ignore_paths that omits the new defaults causes Laravel’s own translation files to be flagged unused and deleted by translation:purge-unused.
  • Publish scripts silently failing or publishing nothing after the GitHub workflow tag rename.
  • AuditType rules applied to the wrong audit—e.g. a path intended to be protected from deletion mapped to Missing only.
  • Broken internal tooling from final classes or @internal methods (withUnused(), jsonSections()).
  • False positives for dynamic keys the translator cannot resolve in scan context; false negatives for unrecognized key construction.
  • New “missing” reports for dotted array keys (behavioral since v0.12.7) creating baseline noise.
  • Unreadable or malformed locale files behaving differently; validate permissions and syntax in CI.
  • purge-unused removing keys used only through dynamic construction; require dry-run, diff review, and VCS rollback.
  • CI failures from newly detected missing keys blocking unrelated releases if no baseline or allowlist exists.
• Ramp-up: Low for Laravel developers on the commands; moderate for TPM-led rollout because the AuditType model and CI policy need explicit agreement. Budget roughly half a day for installation and baseline, an extra half day to a day for the v0.13.0 config migration and workflow integration, plus one sprint for triage, CI integration, and ownership definition. Define success metrics: missing-key count, false-positive rate on dynamic keys, unused-key cleanup volume, zero unintended deletions of framework translation files, CI pass stability, and time saved in localization QA.