elegantly/laravel-translator

All on one translations management for Laravel

v2.0.2 2024-11-19 11:03 UTC

Requires

• php: ^8.2
• deeplcom/deepl-php: ^1.7
• illuminate/contracts: ^10.0||^11.0
• nikic/php-parser: ^5.1
• openai-php/laravel: ^0.10.1
• spatie/laravel-package-tools: ^1.16
• symfony/finder: ^6.0||^7.0

Requires (Dev)

• larastan/larastan: ^2.9
• laravel/pint: ^1.14
• nunomaduro/collision: ^8.1.1||^7.10.0
• orchestra/testbench: ^9.0.0||^8.22.0
• pestphp/pest: ^2.34
• pestphp/pest-plugin-arch: ^2.7
• pestphp/pest-plugin-laravel: ^2.3
• phpstan/extension-installer: ^1.3
• phpstan/phpstan-deprecation-rules: ^1.1
• phpstan/phpstan-phpunit: ^1.3

MIT

• Quentin Gabriele

• laravel
• laravel-translator
• laravel-translations
• Elegantly
• ElegantEngineering

README

Easily manage all your Laravel translation strings with powerful features:

• Translate strings into other languages using DeepL, OpenAI, or custom services.
• Proofread translations to fix grammar and syntax automatically (via OpenAI or custom services).
• Find missing translation strings across locales.
• Detect unused translation keys in your codebase.
• Sort translations in natural order.

Try Laratranslate – A Powerful UI for Managing Translations

Table of Contents

1. Installation
2. Configuring the Driver
3. Sorting and Formatting
   • CLI Commands
   • Using Code
4. Automatic Translation
   • Configuring OpenAI
   • Configuring DeepL
   • CLI Translation
   • Programmatic Translation
5. Proofreading Translations
   • CLI Proofreading
   • Programmatic Proofreading
6. Identifying Untranslated Translations
   • CLI Usage
   • Programmatic Usage
7. Detecting Missing Translations
   • CLI Usage
   • Programmatic Usage
8. Detecting Dead Translations
   • CLI Usage
   • Programmatic Usage
9. Code Scanner Configuration
   • Included Paths
   • Excluded Paths
   • Ignored Translation Keys

Installation

Install the package via Composer:

composer require elegantly/laravel-translator --dev

Add the following line to your .gitignore file:

.translator.cache

Publish the configuration file:

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

Configuring the Driver

This package uses a driver-based architecture. By default, it supports two standard drivers: PHP and JSON. You can 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,

    // ...
];

Sorting and Formatting

CLI Commands

Sort translations with the default driver:

php artisan translator:sort

Specify a driver for sorting:

php artisan translator:sort --driver=json

Using Code

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');

Automatic Translation

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

• OpenAI
• DeepL

Custom translation services can also be implemented.

Configuring OpenAI

Define your OpenAI credentials in the configuration file or via environment variables:

return [
    // ...

    'services' => [
        'openai' => [
            'key' => env('OPENAI_API_KEY'),
            'organization' => env('OPENAI_ORGANIZATION'),
            'request_timeout' => env('OPENAI_REQUEST_TIMEOUT'),
        ],
    ],

    // ...
];

Configuring DeepL

Add your DeepL API key to the configuration file or environment variables:

return [
    // ...

    'services' => [
        // ...
        'deepl' => [
            'key' => env('DEEPL_KEY'),
        ],
    ],

    // ...
];

CLI Translation

Translate untranslated French translations:

php artisan translator:untranslated en fr --translate

Translate using a specific driver:

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

Add a new locale with translations:

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

Programmatic Translation

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', ...]
);

Proofreading Translations

Proofreading corrects grammar and syntax.

Currently, OpenAI is the only built-in service, but custom services can be implemented.

CLI Proofreading

php artisan translator:proofread en

Programmatic Proofreading

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', ...]
);

Identifying Untranslated Translations

Find keys defined in one locale but missing in another.

CLI Usage

php artisan translator:untranslated en fr

Programmatic Usage

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

Detecting Missing Translations

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

CLI Usage

Find the missing keys in 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

Programmatic Usage

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

Detecting Dead Translations

Dead translations are keys defined in your files but unused in your codebase.

CLI Usage

php artisan translator:dead fr

Programmatic Usage

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

Code Scanner Configuration

Included Paths

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

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

Excluded Paths

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

Ignored Translation Keys

Ignore specific translation keys:

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

Testing

Run tests using:

composer test

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.