README

Why use this Package?

Have you ever worked on a project with multiple locales to be supported, created a new branch, worked for a few days, then wondered exactly what translations you have added or changed? If so, you know it is time intensive and error prone for developers to be managing what translations need to be added or updated.

This package's intended purpose is to make this entire process a breeze. Want to know what has been updated, deleted and added? Simple. Want to export everything needing to be translated to a file that can be sent to a translator? No problem. Want to automatically update all of the files that were translated so there are no more errors? Done.

Laravel Translations Manager

Installation

You can install the package via composer:

composer require kfriars/laravel-translations-manager

This package should work out of the box without any changes to configuration. However, you can publish the config file using:

php artisan vendor:publish --provider="Kfriars\TranslationsManager\TranslationsManagerServiceProvider" --tag="config"

This is the contents of the published config file:

return [

    /*
    |--------------------------------------------------------------------------
    | Laravel Lang Directory
    |--------------------------------------------------------------------------
    |
    | This value is the path to laravels 'lang' folder. This value is used to
    | find your applications translations files using __() and Trans
    |
    */

    'lang_dir' => resource_path('lang'),

    /*
    |--------------------------------------------------------------------------
    | Reference Locales
    |--------------------------------------------------------------------------
    |
    | This is the locale that the development team or a developer works in.
    | This setting assumes all changes to translations files are being made in
    | this locale.
    |
    */

    'reference_locale' => config('app.locale'),

    /*
    |--------------------------------------------------------------------------
    | Supported Locales
    |--------------------------------------------------------------------------
    |
    | These are the locales supported by your application. By default, the
    | Supported locales are all folders listed in the lang directory. You can
    | override the setting if you do not want all locales to be validated using
    | this package.
    |
    */

    // 'supported_locales' => [],

    /*
    |--------------------------------------------------------------------------
    | Fix Files
    |--------------------------------------------------------------------------
    |
    | The fix files are used to fix errors in the translations.
    |
    | 'formatter' is the class that will be used to write and parse the fix files.
    | The default format is a JSON format, since it is easily readable by humans
    | and reliably parseable. You can implement your own formatter as long as it
    | implements the FormatterContract, and use it by changing the setting below.
    |
    | 'fix_name_format' is the way fix files will be named. The currently
    | supported formats are 'git' and 'date'.
    |
    | 'git'  format is 'fixes-{locale}-{git branch name}.txt'
    | 'date' format is 'fixes-{locale}-{Y-m-d}.txt'
    |
    */
    'formatter' => Kfriars\TranslationsManager\TranslationsFixesJSONFormatter::class,
    'fix_name_format' => 'git',
];

Reference Locale

The reference locale is the language your development team uses for development. This package is built around the idea that the current reference locale's translations are the correct version of the translations for the project.

For example:

You are working on a project for a French company but the project also supports English, German and Spanish. The mock-ups are given in French, so you make French the default app locale, and create translations files in French first. Then everything is translated to English, German and Spanish after the fact. French would be the reference locale.

Workflow

Assume standard git-flow is used, where the master branch gets deployed to production and the develop branch should be kept in a deployable state.

This package is intended to be used as part of a project's workflow. For a branch to be in a deploayble state there should be no translation errors.

When a feature branch is completed, and ready to make a pull request to develop, the following steps should be taken to ensure there are no translation errors.

1) Check for errors

This command will list all translation errors in your project.

php artisan translations:errors

Example output:

There are 9 error(s) in the translations files:

+-------------+-------------------------------+
| de/common                                   |
+-------------+-------------------------------+
| Key         | Message                       |
+-------------+-------------------------------+
| company     | translation_missing           |
+-------------+-------------------------------+


+-------------+-------------------------------+
| de/contact                                  |
+-------------+-------------------------------+
| Key         | Message                       |
+-------------+-------------------------------+
| email       | translation_missing           |
+-------------+-------------------------------+
| straße      | no_reference_translation      |
+-------------+-------------------------------+
| phone       | reference_translation_updated |
+-------------+-------------------------------+

+------------+----------------------+
| de/admin                          |
+------------+----------------------+
| Key        | Message              |
+------------+----------------------+
| FILE_ERROR | file_not_translated  |
+------------+----------------------+

+-------------+-------------------------------+
| en/contact                                  |
+-------------+-------------------------------+
| Key         | Message                       |
+-------------+-------------------------------+
| phone       | reference_translation_updated |
+-------------+-------------------------------+

+------------+----------------------+
| en/admin                          |
+------------+----------------------+
| Key        | Message              |
+------------+----------------------+
| FILE_ERROR | file_not_translated  |
+------------+----------------------+

+-------------+---------------------+
| es/contact                        |
+-------------+---------------------+
| Key         | Message             |
+-------------+---------------------+
| FILE_ERROR  | file_not_translated |
+-------------+---------------------+

+------------+----------------------+
| es/admin                          |
+------------+----------------------+
| Key        | Message              |
+------------+----------------------+
| FILE_ERROR | file_not_translated  |
+------------+----------------------+

Error Types:

Error	Description
translation_missing	This error is when a translation is present in the reference locale, but not present in one of the supported locales.
file_not_translated	This error is when an entire translations file from the reference locale is not present in one of the supported locales.
reference_translation_updated	This error occurs when a locked translation of the reference locale does not match the current translation in the reference locale. This error helps you know what you have changed in your current branch, so it can be updated in the supported locales.
no_reference_translation	This error occurs when a supported locale has a translation that cannot be found in the reference locale. This error is for eliminating dead translations.
incorrect_translation_type	This error occurs when translation keys match in the reference and supported locales, but their types are different

2) Clean Up Dead Translations

php artisan translations:clean de en es

The no_reference_translation errors likely indicate dead translations from removing keys in the reference locale, and forgetting to remove them in the supported locales. After you have inspected all of these errors and ensured they are in fact dead translations, you can run the clean command to remove all of these keys from your the supported locales.

3) Ignoring Errors

php artisan translations:ignore locale file key?

If there are any translations that do not need to be maintained in the supported locales, then those errors can be ignored. In the example output from #1, it is likely the admin interface's translations do need to be translated.

As such, they can be ignored using:

php artisan translations:ignore de admin
php artisan translations:ignore en admin
php artisan translations:ignore es admin

4) Fix-File Generation

php artisan translations:generate-fixes de en es

Now that all remaining errors require some action, fix-files can be generated containing all translations required to fix the errors in each locale. This file is intended to be sent to a translator, and returned in its current format. The files are in JSON since it is human readable, and reliably parseable.

By default, the files are generated with the naming pattern fixes-{locale}-{git-branch-name}.txt. These files are saved in the configured fixes_dir. The default is storage/translations/fixes.

The following fix files would be generated using French as the reference locale.

fixes-de-feature-xzy.txt

{
    "reference": "fr",
    "locale": "de",
    "files": [{
        "file": "common",
        "translations": {
            "company": "Compagnie"
        }
    }, {
        "file": "contact",
        "translations": {
            "email": "Adresse électronique",
            "phone": "Numéro de téléphone",
        }
    }]
}

fixes-en-feature-xzy.txt

{
    "reference": "fr",
    "locale": "en",
    "files": [{
        "file": "contact",
        "translations": {
            "phone": "Numéro de téléphone"
        }
    }],
}

fixes-es-feature-xzy.txt

{
    "reference": "fr",
    "locale": "es",
    "files": [{
        "file": "contact",
        "translations": {
            "first_name": "Prénom",
            "last_name": "Nom de famille",
            "email": "Adresse électronique",
            "phone": "Numéro de téléphone",
        }
    }],
}

5) Fixing Files

When the fix files have been completed and returned by the translator, you can place them in the configured fixed_dir. The default is storage/translations/fixed. Once the files have been placed in the directory you can run the following command.

php artisan translations:fix de en es

It is important to note, that this command will remove all translations with no_reference_translation errors from the supported locales.

Also, any translations that have reference_translations_updated and were included in the fix file, will have their lockfile updated with the current reference locale translation.

6) Validating Translations

Now you can test whether there are any translation errors by running the following command:

php artisan translations:validate

If the output is Validation Passed, then you can move on to the next step. I strongly recommend you add this command and ensure it passes in your ci/cd flow for deployments to production.

7) Locking Translations

If validation has failed due to reference_translation_updated errors, but you are satisfied with the state of the supported locales translations, you can lock the current state of the reference locale's translations by running the following command:

php artisan translations:lock

This will eliminate all reference_translation_updated errors.

8) Create PR and Merge

Once translations validation passes, you are ready to merge your code!

Commands

Validate

Signature: php artisan translations:validate locales?* --no-ignore

Determine if there are any errors present in the specified locales. If no locales are provided all supported locales will be validated.

Argument	Required	Description	Example Values
locales	✗	The locales you want to ensure are valid.	de, en, es, fr

Options	Description	Example Values
no-ignore	Do not filter ignored errors from the results.	--no-ignore

Errors

Signature: php artisan translations:errors locales?* --no-ignore

List any errors present in the specified locales.

Argument	Required	Description	Example Values
locales	✗	The locales you want to ensure are valid.	de, en, es, fr

Options	Description	Example Values
no-ignore	Do not filter ignored errors from the results.	--no-ignore

Clean

Signature: php artisan translations:clean locales?*

Clean the dead translations -- errors with the message 'no_reference_translation' -- from the specified locales.

Argument	Required	Description	Example Values
locales	✗	The locales of the translations to be cleaned.	de, en, es, fr

Ignore

Signature: php artisan translations:ignore locale file key?

Ignore a translations error. Omitting the key argument from the command will ignore all errors from the file. Ignoring an error allows the Validate command to pass if there are errors you do not wish to address.

Argument	Required	Description	Example Values
locale	✓	The locale of the translations to be ignored.	de, en, es, fr
file	✓	The file of the translation to be ignored. This should be specified as the path from the base of the locale's lang folder.	path/to/file
key	✗	The key to be ignored in dot notation.	keys.to.translation

Unignore

Signature: php artisan translations:unignore locale file key?

Unignore a translations error. Omitting the key argument from the command will unignore all errors from the file.

Argument	Required	Description	Example Values
locale	✓	The locale of the translations to be unignored.	de, en, es, fr
file	✓	The file of the translation to be unignored. This should be specified as the path from the base of the locale's lang folder.	path/to/file
key	✗	The key to be unignored in dot notation.	keys.to.translation

Generate Fixes

Signature: php artisan translations:generate-fixes locales?*

Generate fix files for the locales specified. If no locales are provided, all supported locales will have fix files generated. Fix files are generated to the configured fixes_dir.

Argument	Required	Description	Example Values
locales	✗	The locales you want to generate fix files for.	de, en, es, fr

Fix

Signature: php artisan translations:fix locales?*

Fix the specified locales using the fix files. If no locales are provided, all supported locales will be fixed. The comand looks for the fix files in the the configured fixed_dir.

Argument	Required	Description	Example Values
locales	✗	The locales you want to be fix using the fix files.	de, en, es, fr

Status

Signature: php artisan translations:status locales?*

Get a complete listing of the status of the translations manager. The status shows the state of every translation file's error and ignore information for every local specified. If no locales are provided, all supported locales will have their status listed.

Argument	Required	Description	Example Values
locales	✗	The locales you want included in the status.	de, en, es, fr

Testing

composer test

Changelog

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

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please email kfriars@gmail.com instead of using the issue tracker.

Credits

License

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

kfriars / laravel-translations-manager

Maintainers

Details