orkhanahmadov / spreadsheet-translations
Spreadsheet translations for Laravel
Fund package maintenance!
orkhanahmadov
Installs: 2 924
Dependents: 0
Suggesters: 0
Security: 0
Stars: 22
Watchers: 2
Forks: 1
Open Issues: 0
Requires
- php: ^8.1
- guzzlehttp/guzzle: ^6.0 || ^7.0
- illuminate/console: ^9.0 || ^10.0 || ^11.0
- illuminate/contracts: ^9.0 || ^10.0 || ^11.0
- illuminate/http: ^9.0 || ^10.0 || ^11.0
- illuminate/support: ^9.0 || ^10.0 || ^11.0
- phpoffice/phpspreadsheet: ^1.28 || ^2.0 || ^3.0
Requires (Dev)
- ergebnis/composer-normalize: ^2.42
- friendsofphp/php-cs-fixer: ^3.14
- larastan/larastan: ^1.0 || ^2.4
- mockery/mockery: ^1.4
- orchestra/testbench: ^7.0 || ^8.0 || ^9.0
- phpunit/phpunit: ^9.0 || ^10.0 || ^11.0
README
Why?
Maintaining multi-language support in Laravel applications can be hard
- Laravel's translation files are in plain PHP/JSON files. This assumes that the person who's going to translate the application know how to work with PHP/JSON file, which is not always the case
- Each locale translations are localed under different folders. For example,
en
folder for English translations,de
folder for German. This separation is good on the code level, but makes it hard to maintain 2+ locale translations. - It is easy to add one new key and translation for English but forget to do it in German, since there's nothing that forces this or makes it easy to spot.
Alternatively you can store application's translations in a spreadsheet file, something like:
This solves all above-mentioned problems:
- Translations maintainer does not need to know how to work with PHP or JSON
- All translations are maintained in a single file and view
- Each translation is located under locale column, which makes is very easy to spot missing translations
But now the problem is, Laravel cannot directly work with this spreadsheet file to display translations.
Here comes spreadsheet-translations
package!
It reads spreadsheet file that contains translations for multiple locales and generates plain JSON files out of it that Laravel can work with.
Installation
You can install the package via composer:
composer require orkhanahmadov/spreadsheet-translations
Publish config file using:
php artisan vendor:publish --provider="Orkhanahmadov\SpreadsheetTranslations\SpreadsheetTranslationsServiceProvider"
Config file contains following parameters:
locales
- array of locale codes that parser should look for in spreadsheet. Default is['en']
filepath
- path to spreadsheet file. By default, points totranslations.xlsx
file in Laravel project'slang
directory. This config parameter can also use URL as remote file location. When a valid URL is provided parse will try to download the file to a temporary local file and parse it.sheet
- defines which sheet should be used in spreadsheet file. Default isnull
. Whennull
, parser selects active sheet in the spreadsheet to parse translations from. If you want to use a different sheet, provide sheet's name on this parameter.header_row_number
- which row should be used as header. Default is1
. Header row should contain locale codes that are definedlocales
config parameterkey_column
- which column should be used for translation keys. Default isA
column.ignored_rows
- array of row numbers which should be ignored when translations are parsed. Default is empty array.
Usage
Let's imagine we have the following Excel spreadsheet file which is located in remote server with public URL https://example.com/translations.xlsx
.
Spreadsheet contains:
We want to:
- Point parser to the remote file to download and parse
- Parse only
en
andde
locale translations - Use
key
column as key, in this case columnB
in spreadsheet coordinates - Ignore row number 3
Once we publish the config file we need to make follow adjustments:
[ 'filepath' => 'https://example.com/translations.xlsx', // direct download URL of the file 'locales' => ['en', 'de'], // parse `en` and `de` translations only, which means `es` will be ignored 'key_column' => 'B', // sets key column to B 'ignored_rows' => [3], // ignore row number 3 ]
Package ships with an artisan command translations:generate
.
php artisan translations:generate
When executed it generates necessary JSON translation files in Laravel's lang
directory.
For above spreadsheet file and configuration translations:generate
will generate following folder and file structure:
lang/
en.json
{"dashboard.statistics": "Stastitics", "login.form.first_name": "First name", "welcome": "Welcome"}
de.json
{"dashboard.statistics": "Statistik", "login.form.first_name": "Vorname", "welcome": "Wilkommen"}
Testing
composer test
Changelog
Please see CHANGELOG for more information what has changed recently.
Contributing
Please see CONTRIBUTING for details.
The MIT License (MIT). Please see License File for more information.
Security
If you discover any security related issues, please email hey@orkhan.dev instead of using the issue tracker.
Credits
License
The MIT License (MIT). Please see License File for more information.
Alternatives
You can check larswiegers/laravel-translations-checker if you want to detect missing translations.