Easily manage all your Laravel translation strings with powerful features:

• Translate strings into other languages using OpenAI, Claude, Gemini or custom services.
• Proofread translations to fix grammar and syntax automatically (using OpenAI, Claude, Gemini or custom service).
• Find missing translation strings across locales.
• Detect unused translation keys in your codebase.
• Sort translations in natural order.
• Import & Export translations in a CSV file.

1. How does it work?
2. Installation
3. Configuring the Driver
4. Configuring the Locales
   • Automatic Detection
   • Manual Setup
5. Configuring the Code Scanner
   • Requirements
   • Included Paths
   • Excluded Paths
   • Ignored Translation Keys
6. Sorting and Formatting
   • CLI Commands
   • Using Code
7. Automatic Translation
   • Configuring Prism
   • Using Claude
   • Using Gemini
   • CLI Translation
   • Programmatic Translation
8. Proofreading Translations
   • CLI Proofreading
   • Programmatic Proofreading
9. Identifying Untranslated Translations
   • CLI Usage
   • Programmatic Usage
10. Detecting Missing Translations
    • CLI Usage
    • Programmatic Usage
11. Detecting Dead Translations
    • CLI Usage
    • Programmatic Usage
12. Export to a CSV
    • CLI Usage
    • Programmatic Usage
13. Import from a CSV
    • CLI Usage
    • Programmatic Usage

This package will directly modify your translation files like /lang/en/messages.php or /lang/fr.json for example.

Both PHP and JSON files are supported.

Advanced features like dead translations detection will scan your entire codebase to find unused translation strings.

Install the package via Composer:

composer require elegantly/laravel-translator --dev

Add the following line to your .gitignore file:

storage/.translator.cache

Publish the configuration file:

php artisan vendor:publish --tag="translator-config"

This package uses a driver-based architecture. By default, it supports two standard drivers: PHP and JSON.

• Use the PHP driver if you store your translation strings in .php files, such as /lang/en/message.php.
• Use the JSON driver if you store your translation strings in .json files, such as /lang/fr.json.

You can also create custom drivers for alternative storage methods, such as a database.

Set the default driver in the configuration file:

use Elegantly\Translator\Drivers\PhpDriver;

return [
    /**
     * Possible values: 'php', 'json', or a class-string implementing Driver.
     */
    'driver' => PhpDriver::class,

    // ...
];

By default, this package will attempt to determine the locales defined in your application by scanning your lang directory.

You can customize this behavior in the configuration file.

use Elegantly\Translator\Support\LocaleValidator;

return [
    // ...
    'locales' => LocaleValidator::class,
    // ...
];

To set the locales manually, use the following configuration:

return [
    // ...
    'locales' => ['en', 'fr', 'es'],
    // ...
];

Service: searchcode.

Features:

• Detecting Missing Translations
• Detecting Dead Translations

Both the detection of dead and missing translations rely on scanning your code.

• Missing translations are keys found in your codebase but missing in translation files.
• Dead translations are keys defined in your translation files but unused in your codebase.

At the moment, this package can only scan the following files:

• .php
• .blade.php

The default detector uses nikic/php-parser to scan all your .php files, including the Blade ones.

In order to be able to detect your keys, you will have to use one of the following Laravel function:

• __(...),
• trans(...)
• trans_choice(...)
• \Illuminate\Support\Facades\Lang::get(...)
• \Illuminate\Support\Facades\Lang::has(...)
• \Illuminate\Support\Facades\Lang::hasForLocale(...)
• \Illuminate\Support\Facades\Lang::choice(...)
• app('translator')->get(...)
• app('translator')->has(...)
• app('translator')->hasForLocale(...)
• app('translator')->choice(...)

Or one of the following Laravel Blade directive:

• @lang(...)

Here is some example of do's and don'ts:

__('messages.home.title'); // ✅ 'messages.home.title' is detected

foreach(__('messages.welcome.lines') as $line){
    // ✅ 'messages.welcome.lines' and all of its children are detected.
}

$key = 'messages.home.title';
__($key); // ❌ no key is detected

Specify paths to scan for translation keys. By default, both .php and .blade.php files are supported.

return [
    'searchcode' => [
        'paths' => [
            app_path(),
            resource_path(),
        ],
    ],
];

Exclude irrelevant paths for optimized scanning, such as test files or unrelated directories.

return [
    'searchcode' => [
        'excluded_paths' => [
            'tests'
        ],
    ],
];

Ignore specific translation keys:

return [
    'searchcode' => [
        'ignored_translations' => [
            'countries', // Ignore keys starting with 'countries'.
        ],
    ],
];

Sort translations with the default driver:

php artisan translator:sort

Specify a driver for sorting:

php artisan translator:sort --driver=json

Sort translations programmatically with the default driver:

use Elegantly\Translator\Facades\Translator;

Translator::sortTranslations(locale: 'fr');

Specify a driver:

Translator::driver('json')->sortTranslations(locale: 'fr');

Service: translate.

Before translating, configure a translation service. The package supports:

• Prism (prism-php/prism)
• Any Prism provider (OpenAI, Anthropic/Claude, Gemini, Ollama, ...)

Custom translation services can also be implemented.

Enable Prism as your translation service in config/translator.php:

return [
    // ...

    'translate' => [
        'service' => 'prism',
        // ...
    ],
];

Choose the provider/model used by the translator:

return [
    // ...

    'services' => [
        'prism' => [
            'provider' => env('TRANSLATOR_PRISM_PROVIDER', 'openai'),
            'model' => env('TRANSLATOR_PRISM_MODEL', 'gpt-4.1-mini'),
        ],
    ],

    // ...
];

Prism itself reads provider credentials from config/prism.php.

If you haven't published the Prism config yet:

php artisan vendor:publish --tag=prism-config

To translate with Claude via Prism, set the provider to anthropic and pick a Claude model:

return [
    // ...

    'services' => [
        'prism' => [
            'provider' => 'anthropic',
            'model' => 'claude-3-7-sonnet-latest',
        ],
    ],

    // ...
];

To translate with Gemini via Prism, set the provider to gemini and pick a Gemini model:

return [
    // ...

    'services' => [
        'prism' => [
            'provider' => 'gemini',
            'model' => 'gemini-2.0-flash',
        ],
    ],
];

Translate all missing keys from English to every configured locale:

php artisan translator:translate en

Force re-translation of all keys (overwrites existing values):

php artisan translator:translate en --force

Translate from English to French:

php artisan translator:translate en --target=fr

Translate using smaller/larger chunks (defaults to 10):

php artisan translator:translate en --chunk=25

Translate using a specific driver:

php artisan translator:translate en --driver=json

Inspect untranslated keys before translating:

php artisan translator:untranslated en fr

Inspect untranslated keys with a specific driver:

php artisan translator:untranslated en fr --driver=json

Add a new locale and immediately translate it from an existing source locale:

php artisan translator:add-locale fr en --translate

Translate translations programmatically with the default driver:

Translator::translateTranslations(
    source: 'en',
    target: 'fr',
    keys: ['validation.title', ...]
);

Specify a driver for translation:

Translator::driver('json')->translateTranslations(
    source: 'en',
    target: 'fr',
    keys: ['My Title', ...]
);

Service: proofread.

Proofreading corrects the grammar and syntax of your translation strings.

This package ships with a Prism-based proofreading service (prism-php/prism), and custom services can also be implemented.

Enable it by setting translator.proofread.service to prism, and configure Prism as described in Configuring Prism.

Proofread all strings in the target locale (English).

php artisan translator:proofread en

Proofread translations with the default driver:

Translator::proofreadTranslations(
    locale: 'fr',
    keys: ['auth.email', ...]
);

Specify a driver:

Translator::driver('json')->proofreadTranslations(
    locale: 'fr',
    keys: ['My Title', ...]
);

Find keys defined in one locale but missing in another.

Display all keys defined in the source locale (English) but not in the target locale (French).

php artisan translator:untranslated en fr

Translator::getUntranslatedTranslations(source: 'en', target: 'fr');

Service: searchcode. Configuration: Configuring the Code Scanner

Missing translations are keys found in your codebase but missing in translation files.

Find keys defined in your codebase but missing in your locale (English) using your default driver:

php artisan translator:missing en

Specify a driver:

php artisan translator:missing en --driver=json

Add the missing keys to your driver:

php artisan translator:missing en --sync

Translator::getMissingTranslations(locale: 'en');

Service: searchcode. Configuration: Configuring the Code Scanner

Dead translations are keys defined in your locale (English) but unused in your codebase.

php artisan translator:dead en

Translator::getDeadTranslations(locale: 'fr');

Service: exporter

Export all your translation strings to a CSV file in the following format:

php artisan translator:export /path/to/my/file.csv

$path = Translator::exportTranslations('/path/to/my/file.csv');

Service: exporter

Import translation strings from a CSV file. Ensure your CSV follows the format below:

php artisan translator:import /path/to/my/file.csv

$translations = Translator::importTranslations('/path/to/my/file.csv');

Run tests using:

composer test

See the CHANGELOG for recent updates.

Check the CONTRIBUTING guide for details.

Report security vulnerabilities via GitHub or email.

• Quentin Gabriele
• All Contributors

This package is licensed under the MIT License. See the License File for more details.