rpwebdevelopment/laravel-translate

Laravel Translate

Laravel Translate is a tool intended to automatically generate translated language files. Currently, the package leverages either DeepL API, Amazon Translate or the amazing Google Translate package from Stichoza which allows for zero configuration usage.

The default configuration makes use of Google translations and can be used straight out of the box with no sign-up or configuration. If you would rather use the DeepL translations API you will need to sign up here; DeepL configuration details described below.

Installation

You can install the package via composer:

composer require rpwebdevelopment/laravel-translate

You can publish the config file with:

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

This is the contents of the published config file:

return [
    'reader' => 'php',
    'default_source' => 'en_GB',
    'target_locales' => [],
    'lang_directory' => base_path('resources/lang'),
    'provider' => 'google',
    'providers' => [
        'google' => [
            'package' => GoogleTranslate::class,
        ],
        'deepl' => [
            'package' => DeeplTranslate::class,
            'token' => env('DEEPL_AUTH_TOKEN', null),
            'model_type' => 'prefer_quality_optimized',
            'formality' => 'default',
        ],
        'aws' => [
            'package' => AwsTranslate::class,
            'credentials' => [
                'key' => env('AWS_ACCESS_KEY_ID', null),
                'secret' => env('AWS_SECRET_ACCESS_KEY', null),
            ],
            'settings' => [
                "Formality" => "FORMAL"
            ],
            "region" => env('AWS_DEFAULT_REGION', "us-east-1"),
            "version" => "latest",
        ],
    ],
    'readers' => [
        'php' => PhpReader::class,
        'json' => JsonReader::class,
    ],
    'writers' => [
        'php' => PhpWriter::class,
        'json' => JsonWriter::class,
    ],
];

DeepL Configuration

In order to make use of the DeepL API you will need to publish the config file as detailed above and update the provider to deepl. You will then need to add your DeepL API auth token to your .env file under the env variable DEEPL_AUTH_TOKEN.

Amazon Configuration

In order to make use of the AWS Translate API you will need to publish the config file as detailed above and update the provider to aws. You will then need to ensure that you .env file contains the required AWS variables: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY & AWS_DEFAULT_REGION.

Note:

You will need to ensure that the AWS IAM role has the permission policy TranslateFullAccess .

Defining Locales

When configuring target languages it is important to follow the below conventions:

'target_locales' => [
    [FILE/DIR PATH] => [
        'lang' => [LANG CODE],
        'formality' => [OPTIONAL FORMALITY]
    ]
],

Example:

'target_locales' => [
    'de_DE_formal' => [
        'lang' => 'de_DE',
    ],
    'de_DE_casual' => [
        'lang' => 'de_DE',
        'formality' => 'less_formal',
    ],
]

The above would output two different German language translations; one using more formal language and one using less formal language

Note:

Formality is currently only available for DeepL and AWS translations. This setting will have no impact when using Google translate.

Usage

This package is designed to function with as much flexibility as possible, as such it is designed to work for multiple configurations with minimal setup, whether you have a single file or directory per language, or if you are using PHP lang files or JSON lang files.

php artisan laravel-translate {target} {--source=?} {--file=?} {--missing-only}

Options:

Bulk Processing

Rather than processing each target language manually you can add all your target locales to the target_locales option in the translations configuration file, this will enable the usage of the bulk translate command:

php artisan laravel-translate:bulk {--source=?} {--file=?} {--missing-only}

Options:

Key Validation

If you simply wish to ascertain if translations are missing from your project you can implement the missing command:

php artisan laravel-translate:bulk {--verbose}

Options:

This command can be used in conjunction with git-hooks in order to prevent changes being deployed to your repository with missing translations, this can be done by adding the following bash script to your .git/hooks/pre-commit:

#! /bin/bash

missing="$( php artisan laravel-translate:missing )"

if [ "$missing" = "translations missing" ];then
  echo "Translations Missing";
  exit 0
fi

Example Usages

Directory Structure:

Example directory structure:

resources 
|----lang
     |----en_GB
          |----auth.php
          |----global.php

Assuming the config default_source is set to en_GB; for the above structure the following command:

php artisan laravel-translate fr_FR

Would produce the following structure:

resources 
|----lang
     |----en_GB
     |    |----auth.php
     |    |----global.php
     |----fr_FR
          |----auth.php
          |----global.php

Alternately, you can explicitly declare the source locale:

php artisan laravel-translate fr_FR --source=en_GB

If you are only wanting to replace a specific file you can also pass in the file option (note the file extension is optional):

php artisan laravel-translate fr_FR --source=en_GB --file=auth

Single File Structure

If you are using a single file per language rather than a directory structure as below:

resources 
|----lang
     |----en_GB.php
     |----fr_FR.php

You can use the exact same command syntax, so the following:

php artisan laravel-translate de_DE --source=en_GB

Would result in the following output:

resources 
|----lang
     |----en_GB.php
     |----fr_FR.php
     |----de_DE.php

Notes

• Any existing translations will be overridden, it is recommended that you back-up any previously created lang files to allow for easy restoration if required.

• Translations are a result of machine translation and therefore some translation errors may occur.

• While efforts have been made to persist lang string attributes, their persistence cannot be 100% guaranteed, as such it is recommended to verify your files after production.

Credits

• Richard Porter

Changelog

Please see CHANGELOG for more information on what has changed recently.

License

The MIT License (MIT). Please see License File for more information.