Download the PHP package elegantly/laravel-translator without Composer

All-in-One Translations Manager for Laravel

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.

Try Laratranslate – A Powerful UI for Managing Translations

Table of Contents

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 the Laravel AI SDK
   • 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

How does it work?

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.

Installation

Install the package via Composer:

Add the following line to your .gitignore file:

Publish the configuration file:

Configuring the Driver

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:

[!NOTE] All features are supported in both the PHP and JSON drivers.

Configuring the Locales

Automatic Detection

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.

Manual Setup

To set the locales manually, use the following configuration:

Configuring the Code Scanner

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.

Requirements

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

• .php
• .blade.php

[!NOTE] If you use a React or Vue frontend, it would not be able to scan those files, making this feature irrelevant.

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:

Included Paths

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

Excluded Paths

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

Ignored Translation Keys

Ignore specific translation keys:

Sorting and Formatting

CLI Commands

Sort translations with the default driver:

Specify a driver for sorting:

Using Code

Sort translations programmatically with the default driver:

Specify a driver:

Automatic Translation

Service: translate.

By default, this package uses the Laravel AI SDK (laravel/ai) to perform translation requests through an AI provider. See the official documentation for more details: Laravel AI SDK documentation

You can also implement your own translation service if you need custom behavior or provider integration.

Configuring the Laravel AI SDK

You may override the Laravel AI SDK configuration through the translator.services.ai configuration options:

The Laravel AI SDK reads provider credentials and default settings from the config/ai.php configuration file.

CLI Translation

Translate all missing keys from English to every configured locale:

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

Translate from English to French:

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

Translate using a specific driver:

Inspect untranslated keys before translating:

Inspect untranslated keys with a specific driver:

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

Programmatic Translation

Translate translations programmatically with the default driver:

Specify a driver for translation:

Proofreading Translations

Service: proofread.

The proofreading service improves existing translation strings by correcting grammar, spelling, syntax, and wording while preserving the original meaning and translation context.

By default, this package uses the Laravel AI SDK (laravel/ai) to send proofreading requests to an AI provider. See the official documentation for more details: Laravel AI SDK documentation

See Configuring the Laravel AI SDK for configuration details.

You may also implement a custom proofreading service to integrate a different provider or customize the proofreading workflow.

CLI Proofreading

Proofread all strings in the target locale (English).

Programmatic Proofreading

Proofread translations with the default driver:

Specify a driver:

Identifying Untranslated Translations

Find keys defined in one locale but missing in another.

CLI Usage

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

Programmatic Usage

Detecting Missing Translations

Service: searchcode. Configuration: Configuring the Code Scanner

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

CLI Usage

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

Specify a driver:

Add the missing keys to your driver:

Programmatic Usage

Detecting Dead Translations

Service: searchcode. Configuration: Configuring the Code Scanner

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

CLI Usage

Programmatic Usage

Export to a CSV

Service: exporter

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

CLI Usage

Programmatic Usage

Import from a CSV

Service: exporter

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

CLI Usage

Programmatic Usage

Testing

Run tests using:

Changelog

See the CHANGELOG for recent updates.

Contributing

Check the CONTRIBUTING guide for details.

Security Vulnerabilities

Report security vulnerabilities via GitHub or email.

Credits

• Quentin Gabriele
• All Contributors

License

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