lukasss93/laravel-larex

Translate your Laravel application from a single CSV file!

Fund package maintenance!
Lukasss93

v4.2 2022-07-12 17:00 UTC

This package is auto-updated.

Last update: 2022-08-12 17:12:12 UTC


README

68747470733a2f2f62616e6e6572732e6265796f6e64636f2e64652f4c61726176656c2532304c617265782e706e673f7468656d653d6461726b267061636b6167654d616e616765723d636f6d706f7365722b72657175697265267061636b6167654e616d653d6c756b6173737339332532466c61726176656c2d6c617265782b2d2d646576267061747465726e3d67726170685061706572267374796c653d7374796c655f31266465736372697074696f6e3d5472616e736c6174652b796f75722b4c61726176656c2b6170706c69636174696f6e2b776974682b612b73696e676c652b4353562b66696c652532312b266d643d312673686f7757617465726d61726b3d3026666f6e7453697a653d313235707826696d616765733d7461626c65

Laravel Larex

Version Downloads PHP Laravel License Build Coverage

Laravel Larex lets you translate your whole Laravel application with a single CSV file.

You can import translation entries from lang folder into a structured CSV, edit the translations and export them back to Laravel PHP files.

Laravel Larex also supports functionalities to sort entries and find strings that aren't localized yet.

See Plugins section for other features.

🚀 Installation

You can install the package using composer

composer require lukasss93/laravel-larex --dev

Then add the service provider to config/app.php.
This step can be skipped if package auto-discovery is enabled.

'providers' => [
    Lukasss93\Larex\LarexServiceProvider::class
];

⚙ Publishing the config file

Publishing the config file is optional:

php artisan vendor:publish --provider="Lukasss93\Larex\LarexServiceProvider" --tag="larex-config"

👓 Usage

  1. First, you must create the initial CSV file with php artisan larex:init.
    Or you can use php artisan larex:import to import entries from lang folder.
    The csv file has the following columns:

    • group (basically the file name)
    • key (the array key)
    • en (the language code)
    • other language codes...
  2. Open the project-root/lang/localization.csv file and edit it as you see fit.

  3. Finally, you can use php artisan larex:export to translate your entries from the csv file to the laravel php files.

✨ Tips

  • You can import existing laravel php files with php artisan larex:import.
  • You can use php artisan larex:init --base to init the CSV file with default Laravel entries.
  • The key column inside the CSV file supports the dot notation for nested arrays.
  • You can watch your CSV file with php artisan larex:export --watch
  • You can use php artisan larex:sort to sort the CSV file by group and key.
  • Be careful when using the php artisan larex:export command! It will overwrite all files named with the group names inside the CSV.
  • Be careful when using the dot notation! Only the last entry will override the value.
  • You can use php artisan larex:insert to add new items via CLI too!
  • You can use php artisan larex:import --include=en,it to import only "en" and "it" items.
  • You can use php artisan larex:import --exclude=it to import all items except "it" item.
  • You can use php artisan larex:export --include=en,it to export only "en" and "it" columns.
  • You can use php artisan larex:export --exclude=it to export all columns except "it" column.
  • You can use php artisan larex:localize to find unlocalized strings (use the --import option to add strings in your CSV).
  • You can use php artisan larex:find to search existing groups or keys in your CSV file.
  • You can use php artisan larex:remove to remove existing strings in your CSV file.
  • You can use php artisan larex:lang:add to add a new language column to your CSV file.
  • You can use php artisan larex:lang:remove to remove a language column from your CSV file.

📝 Example

  1. Run php artisan larex:init command

  2. Edit the project-root/lang/localization.csv file

group key en it
app hello Hello Ciao
app list.developers Developers Sviluppatori
app list.teachers Teachers Insegnanti
  1. Run php artisan larex:export command

  2. You'll get the following files:

    //project-root/lang/en/app.php
    
    <?php
    
    return [
        'hello' => 'Hello',
        'list' => [
            'developers' => 'Developers',
            'teachers' => 'Teachers',
        ]
    ];
    //project-root/lang/it/app.php
    
    <?php
    
    return [
        'hello' => 'Ciao',
        'list' => [
            'developers' => 'Sviluppatori',
            'teachers' => 'Insegnanti',
        ]
    ];

⏫ Exporters

The larex:export <exporter> command exports CSV strings to a specific location based on the selected exporter.

Exporter Default Description
laravel Export data from CSV to Laravel localization files
json:group Export data from CSV to JSON by group
json:lang Export data from CSV to JSON by language
How to create an exporter:
  1. Create a class that implements the Lukasss93\Larex\Contracts\Exporter interface
  2. Add your exporter inside the larex config

⏬ Importers

The larex:import <importer> command imports the strings of the selected importer, into the CSV.

Importer Default Description
laravel Import data from Laravel localization files to CSV
json:group Import data from JSON by group to CSV
json:lang Import data from JSON by language to CSV
How to create an importer:
  1. Create a class that implements the Lukasss93\Larex\Contracts\Importer interface
  2. Add your importer inside the larex config

🔍 Linters

Larex provides a linting system by using the php artisan larex:lint command to validate your CSV file.

Available linters:
Linter Enabled
by default
Description
ValidHeaderLinter Validate the header structure
ValidLanguageCodeLinter Validate the language codes in the header columns
DuplicateKeyLinter Find duplicated keys
ConcurrentKeyLinter Find concurrent keys
NoValueLinter Find missing values
DuplicateValueLinter Find duplicated values in the same row
UntranslatedStringsLinter Find untranslated strings
UntranslatedStringsLinter Find unused strings
ValidHtmlValueLinter Check valid html values
SameParametersLinter Check same parameters in each language

You can enable/disable any linter you want by comment/uncomment it inside the larex config.

How to create a linter:
  1. Create a class that implements the Lukasss93\Larex\Contracts\Linter interface
  2. Add your linter inside the larex config

🧩 Plugins

  • Crowdin Plugin
    A Laravel Larex plugin to import/export localization strings from/to Crowdin

⚗️ Testing

composer test

🔰 Version Support

Larex L5.8 L6.x L7.x L8.x L9.x
^1.0
^1.2 | ^2.0
^3.0
^4.0
Larex PHP7.2 PHP7.3 PHP7.4 PHP8.0 PHP8.1
^1.0
^1.6 | ^2.0
^3.0
^4.0

📃 Changelog

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

🏅 Credits

📖 License

Please see the LICENSE.md file for more information.