Laravel Translation Linter Laravel Package

Getting Started

Install via Composer as a dev dependency: composer require fidum/laravel-translation-linter --dev. Publish the configuration file: php artisan vendor:publish --tag="translation-linter-config". The config (config/translation-linter.php) controls which paths are scanned and which translation files are checked. Run the linter with php artisan translation:linter. It scans your application for translation keys used in code (Blade, PHP, etc.) and compares them against your translation files, reporting missing and/or unused keys depending on configuration. First use case: run it locally before committing to catch missing translations early. For Laravel 13 support, ensure you are on v3.0.1 or later.

Implementation Patterns

• CI/CD integration: Add php artisan translation:linter as a step in your pipeline (e.g., GitHub Actions, GitLab CI) to fail builds when translations are missing. Check the command options (e.g., --fail-on-missing) to enforce strictness.
• Local pre-commit hook: Use a Git hook (or tools like Husky) to run the linter before each commit, preventing missing keys from being pushed.
• Multi-locale projects: Set locales in the config to check all supported languages. Use paths to include your app, resources, and any custom packages.
• Excluding dynamic keys: If you build translation keys dynamically (e.g., __('messages.' . $type)), add those patterns to the ignore list in the config to reduce false positives.
• Custom parsers: For non-standard translation usage (e.g., in Vue components or custom template engines), extend the linter with custom parsers if the package supports it (check the parsers config key).
• Workflow with translation updates: Run the linter after adding new features to verify all new keys are present in every locale before merging.

Gotchas and Tips

• False positives with dynamic keys: The linter may flag keys constructed at runtime. Use the ignore config to exclude specific keys or patterns (e.g., messages.*).
• Blade directives: Keys inside @lang, @choice, or {{ __('...') }} are detected, but keys in @php blocks or concatenated strings may be missed. Review the linter’s output carefully.
• Config paths: By default, the linter scans app, resources, and routes. If you have translations used in other directories (e.g., packages), add them to paths.
• Translation file formats: The linter supports PHP and JSON translation files. Ensure your files follow Laravel’s standard structure; non-standard formats may cause parsing errors.
• Debugging: Use -v or --verbose to see which files are being scanned and which keys are detected. This helps trace why a key is reported as missing or unused.
• Laravel 13 compatibility: As of v3.0.1, the package supports Laravel 13. If you’re upgrading from an older Laravel version, ensure you update to v3.0.1+ to avoid dependency conflicts.
• Extension points: The package may allow custom “linters” or “checkers” via the config checkers array. Refer to the source for advanced customization (e.g., adding a checker for a custom translation loading mechanism).