WIP

orkhanahmadov · Feb 28, 2023 · d5de51e · d5de51e
1 parent 2cce725
commit d5de51e
Show file tree

Hide file tree

Showing 2 changed files with 104 additions and 3 deletions.
diff --git a/README.md b/README.md
@@ -1,6 +1,35 @@
 ## Spreadsheet translations for Laravel
 
-### WIP
+Easily create Laravel translation files from spreadsheet.
+
+## Why?
+
+Maintaining multi-language support in Laravel applications can be hard
+
+- Laravel's translation files are in plain PHP files (or sometimes JSON).
+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:
+
+| key                   | en         | de        | es             |
+|-----------------------|------------|-----------|----------------|
+| dashboard.statistics  | Statistics | Statistik | Estadísticas   |
+| login.form.first_name | First name | Vorname   | Nombre de pila |
+| login.welcome         | Welcome    | Wilkommen | Bienvenida     |
+
+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 PHP files out of it that Laravel can work with.
 
 ## Installation
 
@@ -10,12 +39,70 @@ You can install the package via composer:
 composer require orkhanahmadov/spreadsheet-translations
 ```
 
+Publish config file using:
+
+```bash
+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 to `translations.xlsx` file in Laravel project's `lang` 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 is `null`. When `null`, 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 is `1`. Header row should contain locale codes that are defined `locales` config parameter
+- `key_column` - which column should be used for translation keys. Default is `A` 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 in `resources/lang/translations.xlsx` that contains:
+
+| comments                           | key                   | en         | de        | es             |
+|------------------------------------|-----------------------|------------|-----------|----------------|
+| Dashboard statistics section title | dashboard.statistics  | Statistics | Statistik | Estadísticas   |
+| ignore this row !!!!!              |                       |            |           |                |
+| First name field on login form     | login.form.first_name | First name | Vorname   | Nombre de pila |
+| Welcome page title                 | login.welcome         | Welcome    | Wilkommen | Bienvenida     |
+
+We want to:
+
+- Parse only `en` and `de` locale translations
+- Use `key` column as key, in this case column `B` in spreadsheet coordinates
+- Ignore row number 3
+
+Once we publish the config file we need to make follow adjustments:
+
 ```php
-// Usage description here
+[
+    '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`.
+
+```shell
+php artisan translations:generate
+```
+
+When executed it generates necessary folder structures and plain PHP translation files in Laravel's `lang` directory.
+
+For above spreadsheet file and configuration `translations:generate` will generate following folder and file structure:
+
+- `lang/`
+  - `en/`
+    - `dashboard.php`
+      - `['statistics' => 'Stastitics']`
+    - `login.php`
+      - `['form.first_name' => 'First name', 'welcome' => 'Welcome']`
+  - `de/`
+    - `dashboard.php`
+      - `['statistics' => 'Statistik']`
+    - `login.php`
+      - `['form.first_name' => 'Vorname', 'welcome' => 'Wilkommen']`
+
 ### Testing
 
 ```bash
@@ -31,7 +118,8 @@ Please see [CHANGELOG](CHANGELOG.md) for more information what has changed recen
 Please see [CONTRIBUTING](CONTRIBUTING.md) for details.
 
 The MIT License (MIT). Please see [License File](LICENSE.md) for more information.
-##_[#]()_ Security
+
+## Security
 
 If you discover any security related issues, please email [email protected] instead of using the issue tracker.
 

diff --git a/config/config.php b/config/config.php
@@ -4,16 +4,29 @@
 
 return [
 
+    // array of locale codes that parser should look for in spreadsheet for translations
     'locales' => ['en'],
 
+    // path to spreadsheet file
+    // by default, points to `translations.xlsx` file in Laravel project's `lang` directory
+    // 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
     'filepath' => lang_path('translations.xlsx'),
 
+    // defines which sheet should be used in spreadsheet file.
+    // default is `null`
+    // when `null`, 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
     'sheet' => null,
 
+    // which row should be used as header.
+    // header row should contain locale codes that are defined in `locales` parameter
     'header_row_number' => 1,
 
+    // which column should be used for translation keys
     'key_column' => 'A',
 
+    // array of row numbers which should be ignored when translations are parsed
     'ignored_rows' => [],
 
 ];