[DOCS][Dev] Add Internationalisation

docs/developer/src/SUMMARY.md

@@ -28,7 +28,7 @@
     - [ORM and Caching](./core/orm_and_caching.md)
     - [Interfaces](./core/interfaces.md)
     - [UI](./core/ui.md)
-    - [Internationalization](./core/i18n.md)
+    - [Internationalisation](./core/i18n.md)
     - [Utils](./core/util.md)
     - [Queues](./core/queues.md)
     - [Files](./core/files.md)

docs/developer/src/core.md

@@ -15,4 +15,5 @@ The `core` tries to be minimal. The essence of it being various wrappers around
 - [Queues](./core/queues.md);
 - [Files](./core/files.md);
 - [Sessions and Security](./core/security.md);
-- [HTTP Client](./core/http.md).
+- [HTTP Client](./core/http.md).
+- [Exceptions](./core/exception_handler.md).

docs/developer/src/i18n.md

@@ -1,14 +1,61 @@
-### Internationalization and localization
+Internationalisation
+====================
 
-For info on helping with translations, see the platform currently in use
-for translations: https://www.transifex.com/projects/p/gnu-social/
+Usage
+-----
 
-Translations use the gettext system <http://www.gnu.org/software/gettext/>.
-If you for some reason do not wish to sign up to the Transifex service,
-you can review the files in the "locale/" sub-directory of GNU social.
-Each plugin also has its own translation files.
+Basic usage is made by calling `App\Core\I18n\I18n::_m`, it works like this:
+```php
+// Both will return the string 'test string'
+_m('test string');
+_m('test {thing}', ['thing' => 'string']);
+```
 
-To get your own site to use all the translated languages, and you are
-tracking the git repo, you will need to install at least 'gettext' on
-your system and then run:
-    $ make translations
+This function also supports ICU format, you can refer to [ICU User Guide](https://unicode-org.github.io/icu/userguide/),
+for more details on how it works. Below you find some examples:
+```php
+$apples = [1 => '1 apple', '# apples'];
+
+_m($apples, ['count' => -42]); // -42 apples
+_m($apples, ['count' => 0]); // 0 apples
+_m($apples, ['count' => 1]); // 1 apple
+_m($apples, ['count' => 2]); // 2 apples
+_m($apples, ['count' => 42]); // 42 apples
+
+$apples = [0 => 'no apples', 1 => '1 apple', '# apples'];
+_m($apples, ['count' => 0]); // no apples
+_m($apples, ['count' => 1]); // 1 apple
+_m($apples, ['count' => 2]); // 2 apples
+_m($apples, ['count' => 42]); // 42 apples
+
+$pronouns = ['she' => 'her apple', 'he' => 'his apple', 'they' => 'their apple', 'someone\'s apple'];
+_m($pronouns, ['pronoun' => 'she']); // her apple
+_m($pronouns, ['pronoun' => 'he']); // his apple
+_m($pronouns, ['pronoun' => 'they']); // their apple
+_m($pronouns, ['pronoun' => 'unknown']); // someone's apple
+
+$complex = [
+    'she'   => [1 => 'her apple', 'her # apples'],
+    'he'    => [1 => 'his apple', 'his # apples'],
+    'their' => [1 => 'their apple', 'their # apples'],
+];
+
+_m($complex, ['pronoun' => 'she',  'count' => 1]); // her apple
+_m($complex, ['pronoun' => 'he',   'count' => 1]); // his apple
+_m($complex, ['pronoun' => 'she',  'count' => 2]); // her 2 apples
+_m($complex, ['pronoun' => 'he',   'count' => 2]); // his 2 apples
+_m($complex, ['pronoun' => 'she',  'count' => 42]); // her 42 apples
+_m($complex, ['pronoun' => 'they', 'count' => 1]); // their apple
+_m($complex, ['pronoun' => 'they', 'count' => 3]); // their 3 apples
+```
+
+Utilities
+---------
+
+Some common needs regarding user internationalisation are to know
+his language and whether it should be handled Right to left:
+
+```php
+$user_lang = $user->getLanguage();
+App\Core\I18n\I18n::isRtl($user_lang);
+```