Laravel Translations Checker Laravel Package

Getting Started

Install the package as a dev dependency:

composer require --dev larswiegers/laravel-translations-checker

Run the check immediately:

php artisan translations:check

By default, it scans resources/lang and reports missing translations per language. The output is human-readable and highlights both missing files (e.g., passwords.php) and individual keys (e.g., nl.passwords.reset).

Start by running it locally during development, especially after adding new translations in your base language (usually en). Use the output to fill gaps in other languages before deployment.

Implementation Patterns

• CI Integration: Add php artisan translations:check --excludedDirectories=vendor to your GitHub Actions or GitLab CI pipeline to fail builds when translations are missing.
• Config-Driven Exclusions: Publish the config (php artisan vendor:publish --tag=translation-checker-config) and configure:
  • excluded_directories (e.g., ['lang/vendor'])
  • exclude_languages (e.g., ['xx', 'zz'])
  • excluded_file_extensions (e.g., ['csv', 'yaml'] if supported by your stack but not checked)
• Pre-commit Hooks: Use a tool like husky + lint-staged to run a limited check (e.g., only changed language files) before committing new translation keys.
• Multi-Project Support: For monorepos or shared translation repos, use --directory=src/Translations to point to non-standard paths.

Gotchas and Tips

• Empty files cause errors: Ensure all language files exist (even if empty arrays) — v0.4+ handles empty files gracefully, but missing.php should not be deleted entirely.
• Case sensitivity: Language codes are matched as-is (e.g., en-US ≠ en_us). Use ISO standard codes consistently across app.php and language directories.
• Nested keys matter: Keys like auth.failed vs auth.falied (typo) are both reported as missing — the tool doesn’t validate spelling, only presence.
• Config precedence: CLI options (--excludedDirectories=...) override config file settings. Use config for project-wide defaults, CLI for one-off overrides.
• JSON support is shallow: Supports lang/en.json and lang/en/auth.json, but does not merge nested JSON structures across files — each file is validated independently.
• Debugging: For subtle issues, run with --verbose (though not documented, it helps trace file scanning) or temporarily enable logging via LOG_CHANNEL=single.
• Extension support: Be explicit with --excludedFileExtensions — if you accidentally include .blade.php or .yml, the parser will fail or misreport.