Laravel Translation Audit

Laravel Translation Audit: trova le traduzioni mancanti e inutilizzate nella tua app Laravel

Laravel Translation Audit è un pacchetto open-source per applicazioni Laravel, pensato per facilitare il controllo delle traduzioni mancanti e orfane in progetti con UI multilingua. Scansiona file PHP e viste Blade alla ricerca delle chiavi di traduzione usate, le confronta con i file presenti nella cartella lang e segnala cosa manca, cosa non viene più usato e, se richiesto, rimuove le traduzioni superflue.

Installazione

È possibile installarlo tramite Composer come dipendenza di sviluppo:

composer require --dev simonecerruti/laravel-translation-audit

Non serve alcun setup: funziona subito con la configurazione di default. Per personalizzarla, è possibile pubblicare il file di configurazione:

php artisan vendor:publish --tag="laravel-translation-audit-config"

Comandi

php artisan translation:audit

Scansiona la codebase (secondo i percorsi specificati in config o nei flag del comando) alla ricerca di chiavi di traduzione, ovvero qualunque stringa passata agli helper di traduzione di Laravel, come __(), trans(), trans_choice(), @lang, Lang::get(), ecc., con supporto anche a helper custom. Controlla poi i file di traduzione in lang (o in resources/lang) e verifica che ogni chiave trovata sia presente. Se una chiave non viene trovata, viene segnalata come mancante per le lingue nei cui file non risulta, raggruppata per file sorgente in cui è usata.

Passando --unused è possibile anche individuare le traduzioni orfane, cioè presenti nei file di traduzione ma non usate in nessun punto del codice. I file di traduzione nativi di Laravel (auth.php, pagination.php, passwords.php, validation.php) vengono esclusi di default.

php artisan translation:purge-unused

Rimuove in un colpo solo le traduzioni orfane dai file in lang. Con --dry-run è possibile vedere in anticipo cosa verrebbe eliminato, senza modificare alcun file:

php artisan translation:purge-unused --dry-run

La rimozione è conservativa: nei file PHP vengono eliminate solo le righe delle traduzioni inutilizzate (lasciando intatti commenti e valori calcolati), mentre i file JSON mantengono la loro indentazione. Le traduzioni che non possono essere rimosse in sicurezza vengono lasciate dove sono e segnalate con il motivo.

Output, CI e agenti AI

• Formati di output: risultato stampabile come list, table o json tramite --display-format, e salvabile su file con --save.

• Integrazione CI/CD: il comando restituisce un exit code diverso da zero quando trova problemi, quindi può bloccare una pull request. Il pacchetto include workflow pronti per GitHub Actions e GitLab CI, pubblicabili con vendor:publish.

• Agenti AI: se eseguito da Claude Code, Codex, Cursor, Gemini CLI o GitHub Copilot, lo rileva automaticamente e stampa solo il JSON, facilmente interpretabile dall'agente (forzabile con --for-agent).

Configurazione avanzata

Per coprire anche i casi in cui le chiavi non sono scritte in modo letterale nel codice, il pacchetto mette a disposizione:

• Helper di traduzione custom (translation_calls): funzioni e metodi statici propri, anche con la chiave in una posizione diversa dal primo argomento.

• Chiavi dinamiche: chiavi come __("payments.{$method}") vengono interpretate come pattern payments.*, ed è possibile elencarne i valori possibili (anche tramite backed enum) con dynamic_keys.

• Chiavi aggiuntive (additional_keys): per le chiavi usate solo dal frontend o lette da database.

• Resolver custom: classi che restituiscono le chiavi generate a runtime da logica non analizzabile staticamente.

• Esclusioni granulari: path, lingue e chiavi da ignorare, anche limitatamente al solo controllo delle mancanti o delle orfane.

• Hook: codice eseguito prima o dopo i comandi, ad esempio per sincronizzare le traduzioni da un servizio esterno o notificare il team su Slack.

Open-source e licenza

Laravel Translation Audit è rilasciato con licenza MIT. Codice sorgente, documentazione completa e changelog sono disponibili su GitHub, mentre il pacchetto è pubblicato su Packagist.