Laravel Translations Checker Laravel Package

Getting Started

Minimal Steps

1. Installation:

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

   Add the package as a dev dependency to avoid bloating production builds.

2. First Run: Execute the command in your project root:

   php artisan translations:check
   

   This scans the default resources/lang directory for missing translations across all supported languages.

3. Quick Check: For a one-time sanity check before a release, run:

   php artisan translations:check --directory=resources/lang --excludedDirectories=vendor
   

   This excludes vendor-specific translations (common in packages like laravel-ui).

Where to Look First

• Output Format: Review the command’s output for missing files (e.g., nl/passwords.php) or keys (e.g., nl.passwords.reset).
• Configuration: Check config/translation-checker.php (auto-generated) for customization options.
• CI Integration: Reference the GitHub Actions example to add checks to your pipeline.

First Use Case

Scenario: Your team adds a new translation key (auth.login.failed) in English but forgets to include it in French (fr/auth.php). Users report seeing raw keys (auth.login.failed) in production.

Solution:

1. Run the checker:

   php artisan translations:check
   

2. Output highlights:

   Missing the translation with key: fr.auth.login.failed
   

3. Fix: Add the missing key to resources/lang/fr/auth.php and re-run the check to confirm resolution.

Implementation Patterns

Core Workflow

1. Development Phase:

   • Run the checker locally after adding new translation keys to catch gaps early.
   • Example:

     php artisan translations:check --directory=resources/lang/custom
     

     (Useful for custom language directories.)

2. CI/CD Integration:

   • Add the command to your pipeline’s test phase (e.g., GitHub Actions, GitLab CI).
   • Example (GitHub Actions):

     - name: Check translations
       run: php artisan translations:check --excludedDirectories=vendor,storage
     

   • Fail the build if missing translations are found by exiting with a non-zero status:

     php artisan translations:check || exit 1
     

3. Exclusion Strategies:

   • Vendor Packages: Exclude directories like vendor/lang or lang/vendor:

     'excluded_directories' => ['vendor/*', 'lang/vendor'],
     

   • File Types: Ignore .php files if using JSON-only translations:

     php artisan translations:check --excludedFileExtensions=php
     

   • Languages: Skip the default language (e.g., English) or test languages:

     'exclude_languages' => ['en', 'test'],
     

Integration Tips

1. Custom Directories: If translations are stored outside resources/lang (e.g., app/translations), specify the directory:

   php artisan translations:check --directory=app/translations
   

2. Partial Checks: Validate only specific languages during development:

   php artisan translations:check --languages=es,fr
   

3. Blade Directives: The checker works with @lang directives and __() helpers. Ensure all dynamic keys (e.g., @lang('auth.login')) are statically defined in translation files.

4. Dynamic Keys: For runtime-generated keys (e.g., Lang::get("user.$id")), the checker cannot detect them. Document these cases in your team’s translation guidelines.

5. JSON vs. PHP: The package supports both formats. Prefer JSON for simpler projects (easier to diff) and PHP for complex nested structures (e.g., arrays).

Gotchas and Tips

Pitfalls

1. False Negatives:

   • Dynamic Keys: Keys generated via variables (e.g., Lang::get("key.$id")) are ignored. Solution: Use static keys where possible or document exceptions.
   • Nested Directories: If a language directory is missing (e.g., resources/lang/fr doesn’t exist), the checker won’t flag nested files (e.g., fr/auth.php). Solution: Ensure all language directories exist, even if empty.

2. Performance:

   • Large Projects: Scanning 10,000+ translation files may slow down CI. Solution: Exclude unnecessary directories or run checks in parallel (e.g., split by language).

3. Configuration Overrides:

   • CLI flags override config file settings. Example:

     php artisan translations:check --directory=custom/path --excludedFileExtensions=php
     

     This ignores config/translation-checker.php for this run.

4. Case Sensitivity:

   • The checker is case-sensitive for language codes (e.g., fr ≠ FR). Solution: Use lowercase consistently.

Debugging

1. Silent Failures: If the command runs but doesn’t output errors, verify:

   • The resources/lang directory exists.
   • The lang folder isn’t excluded (check excluded_directories).
   • PHP has permissions to read the files.

2. Empty Files: The checker skips empty files. Solution: Add a placeholder (e.g., return [];) to PHP files or {} to JSON files.

3. Mac Files: Hidden .DS_Store files (common on macOS) may cause errors. Solution: Exclude them:

   php artisan translations:check --excludedFileExtensions=DS_Store
   

Tips

1. CI Optimization: Cache dependencies to speed up CI runs:

   - name: Install Dependencies
     run: composer install --optimize-autoloader --no-dev
   - name: Run translations check
     run: php artisan translations:check
   

2. Team Adoption:

   • Add the command to your package.json scripts for frontend teams:

     "scripts": {
       "check:translations": "php artisan translations:check"
     }
     

   • Run it pre-commit via Husky:

     npm install husky --save-dev
     npx husky add .husky/pre-commit "php artisan translations:check"
     

3. Partial Validation: For large projects, validate incrementally:

   # Check only auth-related files
   php artisan translations:check --directory=resources/lang --excludedFileExtensions=*.php --languages=es,fr
   

4. Custom Output: Redirect output to a file for auditing:

   php artisan translations:check > missing_translations.txt
   

5. Laravel 11+: The package supports Laravel’s new lang directory structure (e.g., lang/en/auth.php). No changes needed—it works out of the box.

Extension Points

1. Custom Validators: Extend the checker by creating a custom command that integrates with the package’s logic. Example:

   use LarsWiegers\TranslationChecker\TranslationChecker;
   
   class CustomTranslationChecker extends Command {
       protected function handle() {
           $checker = new TranslationChecker();
           $results = $checker->check($this->option('directory'));
   
           // Add custom logic (e.g., Slack notifications for critical misses)
           foreach ($results->missingKeys() as $key) {
               if (str_contains($key, 'auth.')) {
                   $this->error("Critical auth key missing: $key");
               }
           }
       }
   }
   

2. Database-Backed Translations: The package doesn’t support database-driven translations. Workaround: Use a pre-commit hook to validate JSON/PHP files against a snapshot of DB translations.

3. Multi-Project Monorepos: For monorepos, specify project-specific directories:

   php artisan translations:check --directory=packages/auth/resources/lang