Laravel Translation Audit Laravel Package

Getting Started

• Install with Composer and publish the config. Note that v0.13.0 renames the GitHub workflow publish tag to laravel-translation-audit-github-workflow (the old laravel-translation-audit-workflow tag no longer works). The laravel-translation-audit tag publishes config, GitHub workflow, and the new GitLab CI job together; the GitLab job alone is laravel-translation-audit-gitlab-workflow.
• Start with the command reference, then configuration, then advanced key detection. The options table is the source of truth for dry-run, path, locale, and force-style flags.
• First use case: run the missing-translation audit across your app. Dynamic keys such as __('payments.'.$method) resolve through Laravel's translator, so they are checked like static keys.
• Then run translation:purge-unused on a branch, review the output and diff before committing deletions.
• When upgrading, do the config migration first (see Gotchas): unused_ignore_paths is gone and merged into ignore_paths, and published configs that define their own ignore_paths must re-add the Laravel translation defaults or translation:purge-unused will remove framework translation files.

Implementation Patterns

• Put missing-translation checks in CI for pull requests. Use the shipped GitHub workflow (republish under the new tag) or the new GitLab job: publish it to .gitlab/ci/audit-translations.yml with php artisan vendor:publish --tag="laravel-translation-audit-gitlab-workflow" and include it from .gitlab-ci.yml. It runs translation:audit on pushes to the default branch, merge requests, and web-UI pipelines.
• Scope ignore rules per audit using the public AuditType enum (Missing or Unused, or its string value). For example 'database/seeders/**' => AuditType::Missing, 'en' => AuditType::Missing, 'Bye' => AuditType::Missing, or 'Ciao' => ['en', AuditType::Unused].
• Remember the asymmetry: a file ignored only for the missing audit still has its keys counted as used, so translation:purge-unused keeps them. A file ignored only for the unused audit is still checked for missing translations. Use this to keep runtime-built key sources out of purge while still auditing them.
• Use 'en' => AuditType::Missing when English keys are the source text; you still get unused-key reporting and purging for that locale.
• Centralize dynamic key construction in enums, constants, or helper methods. Dynamic keys now resolve through the translator and are caught by the same audit as static keys.
• Prefer nested translation arrays over dotted array keys, e.g. 'ipmi' => ['type' => ['help' => ...]], because keys under an array key containing dots cannot be resolved.
• Rely on Laravel's built-in validation translations and nested arrays; validation.password and framework-provided keys are no longer reported as missing.
• Treat dynamic-key namespaces carefully with translation:purge-unused: unused detection is largely static, so runtime-built keys may need allowlisting, exclusion, or an AuditType-scoped ignore rule.
• Build against the public API surface only: the service provider, commands, AuditCommand, the TranslationKeyResolver and Result contracts and results, Data\Translation, DisplayFormat/SaveFormat enums, and InvalidConfigException. Everything else is @internal and may change in any release; AuditTranslationsResult::withUnused() and jsonSections() are explicitly internal despite living on a public class.
• Every concrete class is now final. Do not plan on extending commands, results, or the service provider — use composition, config, or implement the TranslationKeyResolver / Result contracts instead.

Gotchas and Tips

• The config migration is the highest-risk change. unused_ignore_paths no longer exists. If your published config defines its own ignore_paths, you must add the former defaults yourself, mapped to AuditType::Unused, e.g. 'lang/*/validation.php' => AuditType::Unused. Skip this and Laravel's own translation files are reported as unused and deleted by translation:purge-unused.
• ignore_paths, ignore_locales, and ignore_keys now take per-audit mappings (AuditType case or value), not plain string lists. Audit any custom entries in these arrays during the upgrade.
• The GitHub workflow publish tag changed. Scripts or docs referencing --tag="laravel-translation-audit-workflow" will fail silently-ish — update them to laravel-translation-audit-github-workflow.
• final classes break any extension points you relied on (custom command subclasses, result subclasses, service provider overrides). Refactor to composition or the resolver/result contracts before upgrading.
• Dotted array keys remain a real pitfall: 'ipmi.type' => ['help' => ...] can be reported as missing because the translator cannot resolve it. Restructure as nested arrays.
• Unreadable locale files are skipped rather than reported as missing. Add a separate lint/parse check for translation files in CI so permission or syntax problems do not silently hide missing keys.
• translation:purge-unused may flag dynamically constructed keys as unused. Review removals carefully, or exclude them with an unused-scoped ignore rule.
• Nested keys like validation.password are valid and should not be chased as missing.
• If a key is unexpectedly reported as missing, test it directly with Laravel's translator in the target locale, check for dotted array keys, and verify the locale file is readable.
• v0.13.0 has no behavioral change to key resolution itself, but the API-stability contract and config shape changed. After upgrading, re-run both audits and diff the output — the per-audit ignore scoping can change which keys are reported or purged compared with v0.12.x.