a perfect readme

Author: medilies

README.md

@@ -7,23 +7,23 @@
 
 ![banner](https://banners.beyondco.de/Jigsaw%20Localization.png?theme=dark&packageManager=composer+require&packageName=elaborate-code%2Fjigsaw-localization&pattern=jigsaw&style=style_1&description=Brings+localization+feature+to+%22tightenco%2Fjigsaw%22+using+JSON+files&md=1&showWatermark=0&fontSize=100px&images=globe)
 
-Brings localization feature to [tightenco/jigsaw](https://jigsaw.tighten.com/) using JSON files.
+This package is built on top of [PHP JSON tongue](https://github.com/elaborate-code/php-json-tongue) to bring localization feature to [tightenco/jigsaw](https://jigsaw.tighten.com/) using JSON files.
 
 ## Get started
 
 ### Requirements
 
-- PHP 8.0 or higher.
+-   PHP 8.0 or higher.
 
 ### Setup
 
-Bring [jigsaw-localization](https://packagist.org/packages/elaborate-code/jigsaw-localization) to your `Jigsaw` project.
+Install the package using composer:
 
 ```text
 composer require elaborate-code/jigsaw-localization
 ```
 
-Plug `LoadLocalization` to the builder by registering it in `bootstrap.php`.
+Plug `LoadLocalization` to the builder by registering it in `bootstrap.php`:
 
 ```php
 <?php
@@ -40,8 +40,8 @@ $events->beforeBuild([LoadLocalization::class]);
 #### Defining Translation Strings
 
 1. Create a `lang` folder in the root of your project.
-2. Create subfolders for each language supported by the application.
-3. Populate the subfolders with JSON files that hold translations using translation strings as keys (as much as you want).
+2. Create subfolders for each language/locale.
+3. Populate the subfolders with JSON files that hold translations using the `original text` as a `key`, and the `translation` as a `value`.
 
 File structure example:
 
@@ -73,6 +73,9 @@ The output:
 
 `two or three lowercase letters` for the language code + **optionally** `a dash (-) with two uppercase letters` for the region code. For example, all the following codes `ar`, `es`, `fr-CA`, `haw-US` are considered valid.
 
+-   [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) or [ISO 639-2](https://www.loc.gov/standards/iso639-2/php/English_list.php) for language codes.
+-   [ISO 3166](https://www.iso.org/obp/ui/#search) for region codes.
+
 ## The multi folder
 
 For organizational purpose you can group internationalized translations in one JSON using many `locale` keys.
@@ -81,39 +84,33 @@ For organizational purpose you can group internationalized translations in one J
 /lang
     ...
     /multi
-        salutations.json
+        greetings.json
         projects_short_descriptions.json
         ...
 ```
 
-`salutations.json` example:
+`greetings.json` example:
 
 ```json
 {
-    "fr":{
+    "fr": {
         "Hello": "Salut",
         "Goodbye": "Au revoir"
     },
-    "es":{
+    "es": {
         "Hello": "Hola",
         "Goodbye": "Adiós"
     }
 }
 ```
 
-> First level keys must be lang codes
+> First level keys must be locale codes!
 
 ## Using folder structure for locale code prefix
 
-This section explains how to dump the `__` helper second argument `current_locale` for a more intuitive approach.
-
-```php
-echo __($page, $text);
-```
-
-### The default lang
+### The default locale
 
-First you need to define `defaultLocale` in `config.php`. If not set, the package with take `en` as a default.
+First you need to define `defaultLocale` in `config.php`. If not set, the package will take `en` as a default.
 
 ```php
 <?php
@@ -127,11 +124,19 @@ return [
 ];
 ```
 
+### The translation helper
+
+If you call the `__` helper without providing a `locale` parameter, it will try to resolve it from the page path.
+
+```php
+echo __($page, $text);
+```
+
 > If you provide the `__` helper with the `locale` parameter it will proceed with it and ignore the folder structure.
 
 ### The folder structure
 
-> example.com/{lang}
+> domain.com/{locale}/path
 
 Pages that reside in the web root folder `source` are assumed to be rendered using the `defaultLocale`. Other pages that reside in **subfolders named after a locale code** have their **locale** set to the **subfolder name**
 
@@ -156,12 +161,12 @@ Pages that reside in the web root folder `source` are assumed to be rendered usi
 
 ## The included page trick
 
-You may find your self creating a fully coded `source/index.blade.php` and repeating the same code in `source/fr/index.blade.php` and for other languages. To avoid that we suggest the following approach:
+You may find your self creating a fully coded `source/index.blade.php` and repeating the same code in `source/fr/index.blade.php` and for other locales. To avoid that we suggest the following approach:
 
 1. Create a `source/_pages` directory which will contain the master pages.
-2. A master page will look like any other ordinary page, *it will have the HTML structure and calls to `__` but no hardcoded `$current_locale` value* .For example You may directly copy the content of `source/index.blade.php` to `source/_pages/index.blade.php`.
-3. **Include** the master page into other pages that are language aware.
-4. The included content will be able to know which **language** to apply on the translation helper `__` calls as a `$current_locale`.
+2. A master page will look like any other ordinary page, _it will have the HTML structure and calls to `__` but no hardcoded `$current_locale` value_ .For example You may directly copy the content of `source/index.blade.php` to `source/_pages/index.blade.php`.
+3. **Include** the master page into other pages that are locale aware.
+4. The included content will be able to know which **locale** to apply on the translation helper `__` calls as a `$current_locale`.
 
 ```text
 /source
@@ -185,40 +190,40 @@ You may find your self creating a fully coded `source/index.blade.php` and repea
 
 ## Helpers
 
-> IMPORTANT: The following helpers require that you respect the locale prefix folder structure!
+> IMPORTANT: All the following helpers will try to resolve the locale code from the path if needed!
 
-> Setting `baseUrl` in **config** is essential if your site root URL isn't 'example.com/index.html'
+> Setting `baseUrl` in the **config** is essential if your site root URL isn't 'domain.com/index.html'
 
 ### current_path_locale
 
-Returns the `current_locale` *deduced from the lang prefix folder structure*.
+Returns the **current page locale** deduced from its path.
 
 ```php
-current_path_locale() // ar | es | fr-CA | haw-US
+current_path_locale($page) // ar | es | fr-CA | haw-US
 ```
 
 Usage example:
 
 ```php
 <!DOCTYPE html>
-<html lang="{{ current_path_locale() }}">
+<html lang="{{ current_path_locale($page) }}">
     <head>
     <!-- ... -->
 ```
 
 ### translate_path
 
-When you have a page that is available in many languages. `translate_path` helps you get the equivalent translated `path`.
+When you have a page that is available in many locales. `translate_path` helps you get the equivalent translated `path`.
 
 ```php
-translate_path($target_locale)
+translate_path($page, $target_locale)
 ```
 
 input/output examples:
 
 | current path  | translated path  | current_locale to target_locale |
 | ------------- | ---------------- | ------------------------------- |
-| ""            | "/fr"            | default -> fr                   |
+| "/"           | "/fr"            | default -> fr                   |
 | "/contact"    | "/fr/contact"    | default -> fr                   |
 | "/fr"         | "/"              | fr -> default                   |
 | "/fr/contact" | "/contact"       | fr -> default                   |
@@ -230,17 +235,17 @@ Usage example:
 ```php
 <nav>
     @foreach(['en', 'es', 'fr'] as $locale)
-        <a href="{{ translate_path($locale) }}"> {{ $locale }} </a>
+        <a href="{{ translate_path($page, $locale) }}"> {{ $locale }} </a>
     @endforeach
 </nav>
 ```
 
 ### locale_path
 
-To avoid hard coding the `current_locale` into `paths`, input only the partial path that comes after the `locale code` part into this helper and it will handle the rest for you.  
+To avoid hard coding the `current_locale` into `paths`, input only the partial path that comes after the `locale code` part into this helper and it will handle the rest for you.
 
 ```php
-$href = locale_path($partial_path)
+$href = locale_path($page, $partial_path)
 ```
 
 | $partial_path | current_locale | href          |
@@ -255,7 +260,7 @@ $href = locale_path($partial_path)
 Just like the `locale_path` helper, but it prepends the `baseUrl` if set in the config.
 
 ```php
-$href = locale_url($partial_path)
+$href = locale_url($page, $partial_path)
 ```
 
 ## Live test