@24i/bigscreen-sdk 1.0.34 → 1.0.35-alpha.2578

package/packages/i18n/README.md

@@ -1,460 +1,460 @@
----
-id: README
-title: i18n
-hide_title: true
-sidebar_label: i18n
----
-
-# i18n
-Internationalization for SmartApps BIGscreens is written with i18n used on SmartApps in mind.
-This means that it can use the same resources as their SmartApps counterparts.
-References:
-- [i18next](https://www.i18next.com/translation-function/essentials)
-- [smartapps i18n](https://github.com/24i/prd-nxg-sdk-ui/tree/develop/packages/sdk%40quarks/src/i18n)
-
-It is based on i18next interface (smartapps uses i18next directly under the hood). But since the i18next
-is a very large library and not all its features are utilized, the smartapps-bigscreen version 
-is code and feature split for smaller bundle size and better performance.
-
-## Usage
-
-### Initialization
-```ts
-import { i18n } from '@24i/bigscreen-sdk/i18n';
-import { en } from '../i18n/en';
-import { de } from '../i18n/de';
-
-const DICTIONARY = { en, de };
-
-i18n.init({
-    resources: DICTIONARY, // i18next format of resources, optional
-    lng: 'cs', // default language, mandatory, should be ISO 639-1 to have plurals working correctly
-    fallbackLng: 'en', // fallback language if default not found, optional, defaults to 'en'
-    defaultNS: 'common', // default NS in resources, optional, defaults to 'translation'
-    keySeparator: '_', // default key separator, optional, defaults to '.'
-    nsSeparator: '|', // default ns separator, optional, defaults to ':'
-});
-```
-
-### Translating
-```tsx
-import { t } from '@24i/bigscreen-sdk/i18n';
-
-const FetchError = ({ errorCode }) => (
-    <div className="error">
-        {t([`errors:server.${errorCode}`, 'errors:server.unknown'])}
-    </div>
-);
-```
-`t` is a function that under the hood returns a component. It takes two parameters:
-- `key: string | string[]` - translation key or an array of translation keys
-- `options: TranslationOptions | string` - options for a single translation or a default value.
-
-When the language changes it should update the translation automatically.
-
-### Typed translation functions
-If you want to have more security, you can try using typed translation functions:
-- `getTypedT` - for typed `t` function for use in JSX
-- `getTypedI18nT` - for typed `i18n.t` function for getting simple string
-
-#### Usage
-```ts
-// For global functions
-import { getTypedT, getTypedI18nT } from '@24i/bigscreen-sdk/i18n';
-import { en } from './dictionaries/en';
-
-export const t = getTypedT<typeof en>();
-export const i18nT = getTypedT<typeof en>();
-
-// Namespaced in components for example
-import { getTypedT } from '@24i/bigscreen-sdk/i18n';
-import { en } from '../../i18n/dictionaries/en';
-
-const t = getTypedT<typeof en['components']['epg']>('components.epg.');
-```
-Try it at: [https://tsplay.dev/Nd4VdN](https://tsplay.dev/Nd4VdN)
-
-### Text direction
-```tsx
-import { isRtl } from '@24i/bigscreen-sdk/i18n';
-
-const offset = isRtl() ? -100 : 100;
-```
-
-### Translation Key
-Translation key is a string in the format: `namespace:path.to.key`.
-- namespace - optional, overrides `defaultNS` setting, has higher priority than `ns` in options
-- path - optional, path in resources to find the key
-- key - name of the key in the path to choose the translation
-
-If no translation is found, the full-length translation key (including namespace and path) will be
-returned instead.
-
-If you use an array of translation keys, the first found translation will be used. If none of them is found,
-the last key in its full length will be returned.
-
-### Translation Options
-Translation Options is an object that can change the behaviour of the translating. Supported:
-- `lng: string` - set language to use
-- `defaultValue?: string` - default value to use
-- `fallbackLng?: string` - override i18n fallback language
-- `ns?: string` - override namespace (ns in key has higher priority)
-- `keySeparator?: string` - change key separator
-- `nsSeparator?: string` - change ns separator
-- `middlewares?: MiddlewareSetup[]` - list of middlewares to be used with this translation
-
-## addResourceBundle
-This utility allows you to dynamically add new resources. It is useful if you download resources from the API.
-If you want to add more languages/namespace, you will have to call `addResourceBundle` for each language/namespace.
-```ts
-import { addResourceBundle } from '@24i/bigscreen-sdk/i18n/utils/addResourceBundle';
-
-addResourceBundle(
-    language: string, // language of the bundle
-    namespace: string, // namespace of the bundle
-    resources: NamespaceResource, // dictionary of the given namespace
-    deep: boolean = false, // If set to true will deeply add/replace current dictionary, false will overwrite it at the root level
-    overwrite: boolean = false, // If deep set to true, this sets whether you only add (false) or also replace existing (true) translations
-) => void;
-```
-
-## i18n interface
-- `init(options: InitOptions) => void` - see [Initialization](#Initialization)
-- `t(translationKey: string | string[], options?: TranslationOptions | string) => string` - translating function
-- `getLanguage() => string` - returns current language
-- `getLanguages() => string[]` - returns all languages found in resources
-- `setLanguage(language: string) => void` - sets the current language
-- `middleware(...middlewares: MiddlewareSetup[]) => void` - see [Middlewares](#Middlewares)
-- `addEventListener(event: 'languagechange', listener: () => void) => void` - adding a listener on language change
-- `removeEventListener(event: 'languagechange', listener: () => void) => void` - removing a listener on language change
-- `getResources() => Resources` - returns a complete dictionary currently in use
-- `setResources(resources: Resources) => void` - sets complete dictionary (equivalent of resources field in init)
-- `dir(language: string = currentLanguage) => 'ltr' | 'rtl'` - returns direction of the language
-
-## Middlewares
-There are two types of middlewares supported. One are more legacy compatible with i18next translation formats.
-I18next was the utility and format that got used in early days of NextGen (former name for SmartApps).
-Nowadays the translation format has been changed to Unicode ICU and unified across all platforms.
-If you start new project, it is recommended to use ICU format to make it compatible with other platforms more
-easily.
-
-## Middlewares - ICU
-All the middlewares you need for your project need to be enabled together with init or during the translation.
-They are separated to reduce the size of the bundle and to increase the performance.
-
-They all come with a performance hit:
-- *Interpolation* - <b style="color: #fb0;">MEDIUM</b>
-- *DateInterpolation* - <b style="color: #f60;">MEDIUM-HIGH</b>
-- *TimeInterpolation* - <b style="color: #f60;">MEDIUM-HIGH</b>
-- *NumberInterpolation* - <b style="color: #f60;">MEDIUM-HIGH</b>
-- *Plurals* - <b style="color: #f00;">HIGH</b>
-- *Select* - <b style="color: #f00;">HIGH</b>
-
-```tsx
-import { i18n } from '@24i/bigscreen-sdk/i18n';
-import { Interpolation } from '@24i/bigscreen-sdk/i18n/middlewares/icu/Interpolation';
-import { Plurals } from '@24i/bigscreen-sdk/i18n/middlewares/icu/Plurals';
-import { Select } from '@24i/bigscreen-sdk/i18n/middlewares/icu/Select';
-
-i18n.init(/* ... */);
-/**
- * Because middlewares come with a performance impact you have two options:
- * 1 - Initialize them for all translations - use this when the middleware is used a lot in dictionary
- * 2 - Use it through translation options - use this if the middleware is needed only for a handful of keys
- */
-
-/**
- * Option 1 - the order of middlewares is not important
- */
-i18n.middleware(Interpolation, Plurals, Select);
-
-/**
- * Option 2 - used with t function inside JSX, the order is not important
- */
-<h1>
-    {
-        t('friend', {
-            name: user.name,
-            gender: user.gender,
-            friendsCount: 2,
-            middlewares: [Interpolation, Select, Plurals],
-        })
-    }
-</h1>
-```
-
-### Interpolation - ICU
-Interpolation allows you to pass variable into translation.
-
-#### Usage
-```ts
-resource = { introduction: 'Hello, {name}!' };
-i18n.t('introduction', { name: 'Petr' }); // --> 'Hello, Petr!'
-```
-
-### DateInterpolation - ICU
-Allows you to format a variable date into translation.
-
-#### Options
-```
-{nameOfKeyInOptions, date, dateFormat}
-```
-- `nameOfKeyInOptions` - name of variable that you pass
-- `date` - identifier of DateInterpolation (fixed value)
-- `dateFormat` - one of `short`, `medium`, `long`, `full` or string from these letters (e.g. `dMy`):
-- - `y` - for using numeric year
-- - `M` - for using 2-digit month
-- - `L` - for using long month name
-- - `d` - for using 2-digit day
-- - `e` - for using long weekday name
-
-#### Usage
-```ts
-resource = { today: 'Today is, {dateToDisplay, date, full}' };
-i18n.t('today', { dateToDisplay: new Date('2021-09-23') }); // --> 'Today is, Thursday 23 September 2021'
-```
-
-### TimeInterpolation - ICU
-Allows you to format a variable time into translation.
-
-#### Options
-```
-{nameOfKeyInOptions, time, timeFormat}
-```
-- `nameOfKeyInOptions` - name of variable that you pass
-- `time` - identifier of TimeInterpolation (fixed value)
-- `timeFormat` - one of `short`, `medium`, `long`, `full` or string from these letters (e.g. `hm`):
-- - `h` - for using numeric hour
-- - `H` - for using 2-digit hour
-- - `k` - for using numeric hour
-- - `K` - for using 2-digit hour
-- - `m` - for using 2-digit minute
-- - `s` - for using 2-digit second
-
-#### Usage
-```ts
-resource = { now: 'Now is, {timeToDisplay, time, short}' };
-i18n.t('now', { timeToDisplay: new Date('2021-09-23T09:45') }); // --> 'Now is, 9:45'
-```
-
-### NumberInterpolation - ICU
-Allows you to format a variable number into translation.
-
-<b style="color: #f00;">!IMPORTANT!</b> Formatting is not yet supported. If you need support, please,
-implement it in l10n package.
-It is better to use basic Interpolation instead as it might be faster. This is kept for minimal compatibility.
-
-#### Options
-```
-{myNumber, number, ::formatting-options}
-```
-- `myNumber` - name of variable that you pass
-- `number` - identifier of NumberInterpolation (fixed value)
-- `format` - refer to [ICU spec](https://unicode-org.github.io/icu/userguide/format_parse/numbers/skeletons.html)
-
-#### Usage
-Limited to just number passing without any format.
-```ts
-resource = { moneyTotal: 'In total, you need to pay {sum, number, ::currency/USD}.' };
-i18n.t('moneyTotal', { sum: 99 }); // --> 'In total, you need to pay 99.'
-```
-
-### Plurals - ICU
-Plurals make it possible to support different translations based on the count.
-
-#### Options
-```
-{count, plural, offset:1, =0 {Nothing} few {Few things} other {# things}}
-```
-- `count` - name of variable you pass
-- `plural` - identifier of Plurals (fixed value)
-- `offset:1` - optional offset for worded amount and `#` replacement
-- cases in format `count {translation}`
-- - `=0` - or any other number for concrete amount
-- - `zero` - for languages that have special grammar for zero
-- - `one` - for languages that have special grammar for one
-- - `two` - for languages that have special grammar for two
-- - `few` - for languages that have special grammar for few items (e.g. czech for 2-4)
-- - `many` - for languages that have special grammar for many items
-- - `other` - required value for other cases
-
-#### Usage
-```ts
-resource = {
-    simple: 'I have {numCats, plural, =0 {no cat} =1 {a cat} other {# cats}}.',
-    complex: 'I invited {count, plural, offset:1, =0 {no one} =1 {{name}} =2 {{name} and someone else} other {{name} and # more people}}.',
-};
-i18n.t('simple', { numCats: 4 }); // --> I have 4 cats.
-i18n.t('complex', { count: 5, name: 'Lucy' }); // --> I invited Lucy and 4 more people.
-```
-
-### Select - ICU
-Select makes it possible to provide different translations based on variable (e.g. gender).
-
-#### Options
-```
-{variableName, select, case1 {translation1} case2 {translation2} other {translation3}}
-```
-- `variableName` - name of variable you pass
-- `select` - identifier of Select (fixed value)
-- cases in format `caseName {translation}` - `other` is required
-
-#### Usage
-```ts
-resource = { arrived: '{gender, select, male {He} female {She} other {They}} arrived.' };
-i18n.t('arrived', { gender: 'female' }); // --> She arrived.
-```
-
-### ICU - Complex examples
-Translation needs to be written in top-down: 'Select', 'Plurals', 'Interpolations'.
-```ts
-const resource = {
-    example: [
-        '{gender_of_host, select, ',
-            'female {',
-                '{num_guests, plural, offset:1, ',
-                '=0 {{host} does not give a party.}',
-                '=1 {{host} invites {guest} to her party.}',
-                '=2 {{host} invites {guest} and one other person to her party.}',
-                'other {{host} invites {guest} and # other people to her party.}}}',
-            'male {',
-                '{num_guests, plural, offset:1, ',
-                '=0 {{host} does not give a party.}',
-                '=1 {{host} invites {guest} to his party.}',
-                '=2 {{host} invites {guest} and one other person to his party.}',
-                'other {{host} invites {guest} and # other people to his party.}}}',
-            'other {',
-                '{num_guests, plural, offset:1, ',
-                '=0 {{host} does not give a party.}',
-                '=1 {{host} invites {guest} to their party.}',
-                '=2 {{host} invites {guest} and one other person to their party.}',
-                'other {{host} invites {guest} and # other people to their party.}}}}',
-    ].join(''),
-};
-i18n.t('example', { gender_of_host: 'robot', host: 'Bastion', num_guests: 5, guest: 'Reinhardt' });
-// --> Bastion invites Reinhardt and 4 other people to their party.
-```
-
-## Middlewares - i18next
-All the middlewares you need for your project need to enabled together with init or during the translation.
-They are separated to reduce the size of the bundle and to increase the performance.
-
-They all come with a performance hit:
-- *Interpolation* - <b style="color: #f80;">MEDIUM</b>
-- *Plurals* - <b style="color: #f00;">HIGH</b>
-- *Nesting* - <b style="color: #ff0;">LOW-MEDIUM</b> for simple keys, but higher if combined with interpolation or plurals
-- *Context* - <b style="color: #0f0;">LOW</b> for simple keys, but higher if combined with interpolation or plurals
-
-```tsx
-import { i18n } from '@24i/bigscreen-sdk/i18n';
-import { Interpolation } from '@24i/bigscreen-sdk/i18n/middlewares/i18next/Interpolation';
-import { Plurals } from '@24i/bigscreen-sdk/i18n/middlewares/i18next/Plurals';
-import { Nesting } from '@24i/bigscreen-sdk/i18n/middlewares/i18next/Nesting';
-import { Context } from '@24i/bigscreen-sdk/i18n/middlewares/i18next/Context';
-
-i18n.init(/* ... */);
-/**
- * Because middlewares come with a performance impact you have two options:
- * 1 - Initialize them for all translations - use this when the middleware is used a lot in dictionary
- * 2 - Use it through translation options - use this if the middleware is needed only for a handful of keys
- */
-
-/**
- * Option 1 - the order of middlewares is not important
- */
-i18n.middleware(Interpolation, Plurals, Nesting, Context);
-
-/**
- * Option 2 - used with t function inside JSX, the order is not important
- */
-<h1>{t('friend', { context: friend.gender, middlewares: [Interpolation, Context, Plurals] })}</h1>
-```
-
-### Interpolation - i18next
-Interpolation allows you to replace parts of the translation.
-#### Options
-- `format(value: any, valueFormat: string) => string` - optional, formats the value before replacement
-- `formatSeparator: string` - optional, sets the separator char(s), defaults to `,`
-- `prefix: string` - optional, sets custom prefix to separate values for interpolation, defaults to `{{`
-- `suffix: string` - optional, sets custom suffix to separate values for interpolation, defaults to `}}`
-#### Usage
-```ts
-// simple
-resource = { introduction: 'Hello, {{name}}!' };
-i18n.t('introduction', { name: 'Petr' }); // --> 'Hello, Petr!'
-
-// from object
-resource = { introduction: 'Hello, {{user.names.first}}!' };
-i18n.t('introduction', { user: { names: { first: 'Petr' } } }); // --> 'Hello, Petr!'
-
-// format
-resource = { shout: '{{topic, lowercase}}! {{topic}}!! {{topic, uppercase}}!!!' };
-i18n.t('shout', { topic: 'SmartApps', interpolation: { format: (value: string, format: string) => {
-    if (format === 'uppercase') return value.toUpperCase();
-    if (format === 'lowercase') return value.toLowerCase();
-    return value;
-} } }); // --> 'smartapps! SmartApps!! SMARTAPPS!!!'
-```
-
-### Plurals - i18next
-Plurals allows you to automatically choose correct translation based on the `count` option.
-It supports basic plurals (`[[key]]_plural`), form plurals (`[[key]]_1`) and intervals.
-Form plurals are supported for all languages.
-See [http://docs.translatehouse.org/projects/localization-guide/en/latest/l10n/pluralforms.html?id=l10n/pluralforms](http://docs.translatehouse.org/projects/localization-guide/en/latest/l10n/pluralforms.html?id=l10n/pluralforms)
-for the rules and forms for each language.
-#### Usage
-```ts
-// basic
-resource = {
-    item: 'Item',
-    item_plural: 'Items',
-};
-i18n.t('item'); // --> 'Item'
-i18n.t('item', { count: 1 }); // --> 'Item'
-i18n.t('item', { count: 2 }); // --> 'Items'
-
-// form
-resource = { // CS
-    'item': 'Polozka',
-    'item_1': 'Polozky',
-    'item_2': 'Polozek',
-};
-i18n.t('item'); // --> 'Polozka'
-i18n.t('item', { count: 3 }); // --> 'Polozky'
-i18n.t('item', { count: 5 }); // --> 'Polozek'
-i18n.t('item', { count: 0 }); // --> 'Polozek'
-
-// interval
-resource = {
-    'item': 'Item',
-    'item_interval': '(1){One item};(2-5){Two to five items};(6-inf){More than 5 items};';
-};
-i18n.t('item'); // --> 'Item'
-i18n.t('item', { count: 1 }); // --> 'One item'
-i18n.t('item', { count: 3 }); // --> 'Two to five items'
-i18n.t('item', { count: 8 }); // --> 'More than 5 items'
-```
-
-### Nesting - i18next
-Nesting allows you to place a translation key into a translation value and have it translated.
-#### Usage
-```ts
-resource = {
-    welcome: 'Welcome, {{name}}!',
-    introduction: '$t(welcome) I am your i18n module',
-};
-i18n.t('introduction', { name: 'Radim' }); // --> 'Welcome, Radim! I am your i18n module.'
-```
-
-### Context - i18next
-Context middleware allows you to have one translation in multiple contexts. Useful for gender for example.
-```ts
-resource = {
-    friend: 'A friend',
-    friend_male: 'A boyfriend',
-    friend_female: 'A girlfriend',
-};
-i18n.t('friend'); // --> 'A friend'
-i18n.t('friend', { context: 'male' }); // --> 'A boyfriend'
-i18n.t('friend', { context: 'female' }); // --> 'A girlfriend'
-```
+---
+id: README
+title: i18n
+hide_title: true
+sidebar_label: i18n
+---
+
+# i18n
+Internationalization for SmartApps BIGscreens is written with i18n used on SmartApps in mind.
+This means that it can use the same resources as their SmartApps counterparts.
+References:
+- [i18next](https://www.i18next.com/translation-function/essentials)
+- [smartapps i18n](https://github.com/24i/prd-nxg-sdk-ui/tree/develop/packages/sdk%40quarks/src/i18n)
+
+It is based on i18next interface (smartapps uses i18next directly under the hood). But since the i18next
+is a very large library and not all its features are utilized, the smartapps-bigscreen version 
+is code and feature split for smaller bundle size and better performance.
+
+## Usage
+
+### Initialization
+```ts
+import { i18n } from '@24i/bigscreen-sdk/i18n';
+import { en } from '../i18n/en';
+import { de } from '../i18n/de';
+
+const DICTIONARY = { en, de };
+
+i18n.init({
+    resources: DICTIONARY, // i18next format of resources, optional
+    lng: 'cs', // default language, mandatory, should be ISO 639-1 to have plurals working correctly
+    fallbackLng: 'en', // fallback language if default not found, optional, defaults to 'en'
+    defaultNS: 'common', // default NS in resources, optional, defaults to 'translation'
+    keySeparator: '_', // default key separator, optional, defaults to '.'
+    nsSeparator: '|', // default ns separator, optional, defaults to ':'
+});
+```
+
+### Translating
+```tsx
+import { t } from '@24i/bigscreen-sdk/i18n';
+
+const FetchError = ({ errorCode }) => (
+    <div className="error">
+        {t([`errors:server.${errorCode}`, 'errors:server.unknown'])}
+    </div>
+);
+```
+`t` is a function that under the hood returns a component. It takes two parameters:
+- `key: string | string[]` - translation key or an array of translation keys
+- `options: TranslationOptions | string` - options for a single translation or a default value.
+
+When the language changes it should update the translation automatically.
+
+### Typed translation functions
+If you want to have more security, you can try using typed translation functions:
+- `getTypedT` - for typed `t` function for use in JSX
+- `getTypedI18nT` - for typed `i18n.t` function for getting simple string
+
+#### Usage
+```ts
+// For global functions
+import { getTypedT, getTypedI18nT } from '@24i/bigscreen-sdk/i18n';
+import { en } from './dictionaries/en';
+
+export const t = getTypedT<typeof en>();
+export const i18nT = getTypedT<typeof en>();
+
+// Namespaced in components for example
+import { getTypedT } from '@24i/bigscreen-sdk/i18n';
+import { en } from '../../i18n/dictionaries/en';
+
+const t = getTypedT<typeof en['components']['epg']>('components.epg.');
+```
+Try it at: [https://tsplay.dev/Nd4VdN](https://tsplay.dev/Nd4VdN)
+
+### Text direction
+```tsx
+import { isRtl } from '@24i/bigscreen-sdk/i18n';
+
+const offset = isRtl() ? -100 : 100;
+```
+
+### Translation Key
+Translation key is a string in the format: `namespace:path.to.key`.
+- namespace - optional, overrides `defaultNS` setting, has higher priority than `ns` in options
+- path - optional, path in resources to find the key
+- key - name of the key in the path to choose the translation
+
+If no translation is found, the full-length translation key (including namespace and path) will be
+returned instead.
+
+If you use an array of translation keys, the first found translation will be used. If none of them is found,
+the last key in its full length will be returned.
+
+### Translation Options
+Translation Options is an object that can change the behaviour of the translating. Supported:
+- `lng: string` - set language to use
+- `defaultValue?: string` - default value to use
+- `fallbackLng?: string` - override i18n fallback language
+- `ns?: string` - override namespace (ns in key has higher priority)
+- `keySeparator?: string` - change key separator
+- `nsSeparator?: string` - change ns separator
+- `middlewares?: MiddlewareSetup[]` - list of middlewares to be used with this translation
+
+## addResourceBundle
+This utility allows you to dynamically add new resources. It is useful if you download resources from the API.
+If you want to add more languages/namespace, you will have to call `addResourceBundle` for each language/namespace.
+```ts
+import { addResourceBundle } from '@24i/bigscreen-sdk/i18n/utils/addResourceBundle';
+
+addResourceBundle(
+    language: string, // language of the bundle
+    namespace: string, // namespace of the bundle
+    resources: NamespaceResource, // dictionary of the given namespace
+    deep: boolean = false, // If set to true will deeply add/replace current dictionary, false will overwrite it at the root level
+    overwrite: boolean = false, // If deep set to true, this sets whether you only add (false) or also replace existing (true) translations
+) => void;
+```
+
+## i18n interface
+- `init(options: InitOptions) => void` - see [Initialization](#Initialization)
+- `t(translationKey: string | string[], options?: TranslationOptions | string) => string` - translating function
+- `getLanguage() => string` - returns current language
+- `getLanguages() => string[]` - returns all languages found in resources
+- `setLanguage(language: string) => void` - sets the current language
+- `middleware(...middlewares: MiddlewareSetup[]) => void` - see [Middlewares](#Middlewares)
+- `addEventListener(event: 'languagechange', listener: () => void) => void` - adding a listener on language change
+- `removeEventListener(event: 'languagechange', listener: () => void) => void` - removing a listener on language change
+- `getResources() => Resources` - returns a complete dictionary currently in use
+- `setResources(resources: Resources) => void` - sets complete dictionary (equivalent of resources field in init)
+- `dir(language: string = currentLanguage) => 'ltr' | 'rtl'` - returns direction of the language
+
+## Middlewares
+There are two types of middlewares supported. One are more legacy compatible with i18next translation formats.
+I18next was the utility and format that got used in early days of NextGen (former name for SmartApps).
+Nowadays the translation format has been changed to Unicode ICU and unified across all platforms.
+If you start new project, it is recommended to use ICU format to make it compatible with other platforms more
+easily.
+
+## Middlewares - ICU
+All the middlewares you need for your project need to be enabled together with init or during the translation.
+They are separated to reduce the size of the bundle and to increase the performance.
+
+They all come with a performance hit:
+- *Interpolation* - <b style="color: #fb0;">MEDIUM</b>
+- *DateInterpolation* - <b style="color: #f60;">MEDIUM-HIGH</b>
+- *TimeInterpolation* - <b style="color: #f60;">MEDIUM-HIGH</b>
+- *NumberInterpolation* - <b style="color: #f60;">MEDIUM-HIGH</b>
+- *Plurals* - <b style="color: #f00;">HIGH</b>
+- *Select* - <b style="color: #f00;">HIGH</b>
+
+```tsx
+import { i18n } from '@24i/bigscreen-sdk/i18n';
+import { Interpolation } from '@24i/bigscreen-sdk/i18n/middlewares/icu/Interpolation';
+import { Plurals } from '@24i/bigscreen-sdk/i18n/middlewares/icu/Plurals';
+import { Select } from '@24i/bigscreen-sdk/i18n/middlewares/icu/Select';
+
+i18n.init(/* ... */);
+/**
+ * Because middlewares come with a performance impact you have two options:
+ * 1 - Initialize them for all translations - use this when the middleware is used a lot in dictionary
+ * 2 - Use it through translation options - use this if the middleware is needed only for a handful of keys
+ */
+
+/**
+ * Option 1 - the order of middlewares is not important
+ */
+i18n.middleware(Interpolation, Plurals, Select);
+
+/**
+ * Option 2 - used with t function inside JSX, the order is not important
+ */
+<h1>
+    {
+        t('friend', {
+            name: user.name,
+            gender: user.gender,
+            friendsCount: 2,
+            middlewares: [Interpolation, Select, Plurals],
+        })
+    }
+</h1>
+```
+
+### Interpolation - ICU
+Interpolation allows you to pass variable into translation.
+
+#### Usage
+```ts
+resource = { introduction: 'Hello, {name}!' };
+i18n.t('introduction', { name: 'Petr' }); // --> 'Hello, Petr!'
+```
+
+### DateInterpolation - ICU
+Allows you to format a variable date into translation.
+
+#### Options
+```
+{nameOfKeyInOptions, date, dateFormat}
+```
+- `nameOfKeyInOptions` - name of variable that you pass
+- `date` - identifier of DateInterpolation (fixed value)
+- `dateFormat` - one of `short`, `medium`, `long`, `full` or string from these letters (e.g. `dMy`):
+- - `y` - for using numeric year
+- - `M` - for using 2-digit month
+- - `L` - for using long month name
+- - `d` - for using 2-digit day
+- - `e` - for using long weekday name
+
+#### Usage
+```ts
+resource = { today: 'Today is, {dateToDisplay, date, full}' };
+i18n.t('today', { dateToDisplay: new Date('2021-09-23') }); // --> 'Today is, Thursday 23 September 2021'
+```
+
+### TimeInterpolation - ICU
+Allows you to format a variable time into translation.
+
+#### Options
+```
+{nameOfKeyInOptions, time, timeFormat}
+```
+- `nameOfKeyInOptions` - name of variable that you pass
+- `time` - identifier of TimeInterpolation (fixed value)
+- `timeFormat` - one of `short`, `medium`, `long`, `full` or string from these letters (e.g. `hm`):
+- - `h` - for using numeric hour
+- - `H` - for using 2-digit hour
+- - `k` - for using numeric hour
+- - `K` - for using 2-digit hour
+- - `m` - for using 2-digit minute
+- - `s` - for using 2-digit second
+
+#### Usage
+```ts
+resource = { now: 'Now is, {timeToDisplay, time, short}' };
+i18n.t('now', { timeToDisplay: new Date('2021-09-23T09:45') }); // --> 'Now is, 9:45'
+```
+
+### NumberInterpolation - ICU
+Allows you to format a variable number into translation.
+
+<b style="color: #f00;">!IMPORTANT!</b> Formatting is not yet supported. If you need support, please,
+implement it in l10n package.
+It is better to use basic Interpolation instead as it might be faster. This is kept for minimal compatibility.
+
+#### Options
+```
+{myNumber, number, ::formatting-options}
+```
+- `myNumber` - name of variable that you pass
+- `number` - identifier of NumberInterpolation (fixed value)
+- `format` - refer to [ICU spec](https://unicode-org.github.io/icu/userguide/format_parse/numbers/skeletons.html)
+
+#### Usage
+Limited to just number passing without any format.
+```ts
+resource = { moneyTotal: 'In total, you need to pay {sum, number, ::currency/USD}.' };
+i18n.t('moneyTotal', { sum: 99 }); // --> 'In total, you need to pay 99.'
+```
+
+### Plurals - ICU
+Plurals make it possible to support different translations based on the count.
+
+#### Options
+```
+{count, plural, offset:1, =0 {Nothing} few {Few things} other {# things}}
+```
+- `count` - name of variable you pass
+- `plural` - identifier of Plurals (fixed value)
+- `offset:1` - optional offset for worded amount and `#` replacement
+- cases in format `count {translation}`
+- - `=0` - or any other number for concrete amount
+- - `zero` - for languages that have special grammar for zero
+- - `one` - for languages that have special grammar for one
+- - `two` - for languages that have special grammar for two
+- - `few` - for languages that have special grammar for few items (e.g. czech for 2-4)
+- - `many` - for languages that have special grammar for many items
+- - `other` - required value for other cases
+
+#### Usage
+```ts
+resource = {
+    simple: 'I have {numCats, plural, =0 {no cat} =1 {a cat} other {# cats}}.',
+    complex: 'I invited {count, plural, offset:1, =0 {no one} =1 {{name}} =2 {{name} and someone else} other {{name} and # more people}}.',
+};
+i18n.t('simple', { numCats: 4 }); // --> I have 4 cats.
+i18n.t('complex', { count: 5, name: 'Lucy' }); // --> I invited Lucy and 4 more people.
+```
+
+### Select - ICU
+Select makes it possible to provide different translations based on variable (e.g. gender).
+
+#### Options
+```
+{variableName, select, case1 {translation1} case2 {translation2} other {translation3}}
+```
+- `variableName` - name of variable you pass
+- `select` - identifier of Select (fixed value)
+- cases in format `caseName {translation}` - `other` is required
+
+#### Usage
+```ts
+resource = { arrived: '{gender, select, male {He} female {She} other {They}} arrived.' };
+i18n.t('arrived', { gender: 'female' }); // --> She arrived.
+```
+
+### ICU - Complex examples
+Translation needs to be written in top-down: 'Select', 'Plurals', 'Interpolations'.
+```ts
+const resource = {
+    example: [
+        '{gender_of_host, select, ',
+            'female {',
+                '{num_guests, plural, offset:1, ',
+                '=0 {{host} does not give a party.}',
+                '=1 {{host} invites {guest} to her party.}',
+                '=2 {{host} invites {guest} and one other person to her party.}',
+                'other {{host} invites {guest} and # other people to her party.}}}',
+            'male {',
+                '{num_guests, plural, offset:1, ',
+                '=0 {{host} does not give a party.}',
+                '=1 {{host} invites {guest} to his party.}',
+                '=2 {{host} invites {guest} and one other person to his party.}',
+                'other {{host} invites {guest} and # other people to his party.}}}',
+            'other {',
+                '{num_guests, plural, offset:1, ',
+                '=0 {{host} does not give a party.}',
+                '=1 {{host} invites {guest} to their party.}',
+                '=2 {{host} invites {guest} and one other person to their party.}',
+                'other {{host} invites {guest} and # other people to their party.}}}}',
+    ].join(''),
+};
+i18n.t('example', { gender_of_host: 'robot', host: 'Bastion', num_guests: 5, guest: 'Reinhardt' });
+// --> Bastion invites Reinhardt and 4 other people to their party.
+```
+
+## Middlewares - i18next
+All the middlewares you need for your project need to enabled together with init or during the translation.
+They are separated to reduce the size of the bundle and to increase the performance.
+
+They all come with a performance hit:
+- *Interpolation* - <b style="color: #f80;">MEDIUM</b>
+- *Plurals* - <b style="color: #f00;">HIGH</b>
+- *Nesting* - <b style="color: #ff0;">LOW-MEDIUM</b> for simple keys, but higher if combined with interpolation or plurals
+- *Context* - <b style="color: #0f0;">LOW</b> for simple keys, but higher if combined with interpolation or plurals
+
+```tsx
+import { i18n } from '@24i/bigscreen-sdk/i18n';
+import { Interpolation } from '@24i/bigscreen-sdk/i18n/middlewares/i18next/Interpolation';
+import { Plurals } from '@24i/bigscreen-sdk/i18n/middlewares/i18next/Plurals';
+import { Nesting } from '@24i/bigscreen-sdk/i18n/middlewares/i18next/Nesting';
+import { Context } from '@24i/bigscreen-sdk/i18n/middlewares/i18next/Context';
+
+i18n.init(/* ... */);
+/**
+ * Because middlewares come with a performance impact you have two options:
+ * 1 - Initialize them for all translations - use this when the middleware is used a lot in dictionary
+ * 2 - Use it through translation options - use this if the middleware is needed only for a handful of keys
+ */
+
+/**
+ * Option 1 - the order of middlewares is not important
+ */
+i18n.middleware(Interpolation, Plurals, Nesting, Context);
+
+/**
+ * Option 2 - used with t function inside JSX, the order is not important
+ */
+<h1>{t('friend', { context: friend.gender, middlewares: [Interpolation, Context, Plurals] })}</h1>
+```
+
+### Interpolation - i18next
+Interpolation allows you to replace parts of the translation.
+#### Options
+- `format(value: any, valueFormat: string) => string` - optional, formats the value before replacement
+- `formatSeparator: string` - optional, sets the separator char(s), defaults to `,`
+- `prefix: string` - optional, sets custom prefix to separate values for interpolation, defaults to `{{`
+- `suffix: string` - optional, sets custom suffix to separate values for interpolation, defaults to `}}`
+#### Usage
+```ts
+// simple
+resource = { introduction: 'Hello, {{name}}!' };
+i18n.t('introduction', { name: 'Petr' }); // --> 'Hello, Petr!'
+
+// from object
+resource = { introduction: 'Hello, {{user.names.first}}!' };
+i18n.t('introduction', { user: { names: { first: 'Petr' } } }); // --> 'Hello, Petr!'
+
+// format
+resource = { shout: '{{topic, lowercase}}! {{topic}}!! {{topic, uppercase}}!!!' };
+i18n.t('shout', { topic: 'SmartApps', interpolation: { format: (value: string, format: string) => {
+    if (format === 'uppercase') return value.toUpperCase();
+    if (format === 'lowercase') return value.toLowerCase();
+    return value;
+} } }); // --> 'smartapps! SmartApps!! SMARTAPPS!!!'
+```
+
+### Plurals - i18next
+Plurals allows you to automatically choose correct translation based on the `count` option.
+It supports basic plurals (`[[key]]_plural`), form plurals (`[[key]]_1`) and intervals.
+Form plurals are supported for all languages.
+See [http://docs.translatehouse.org/projects/localization-guide/en/latest/l10n/pluralforms.html?id=l10n/pluralforms](http://docs.translatehouse.org/projects/localization-guide/en/latest/l10n/pluralforms.html?id=l10n/pluralforms)
+for the rules and forms for each language.
+#### Usage
+```ts
+// basic
+resource = {
+    item: 'Item',
+    item_plural: 'Items',
+};
+i18n.t('item'); // --> 'Item'
+i18n.t('item', { count: 1 }); // --> 'Item'
+i18n.t('item', { count: 2 }); // --> 'Items'
+
+// form
+resource = { // CS
+    'item': 'Polozka',
+    'item_1': 'Polozky',
+    'item_2': 'Polozek',
+};
+i18n.t('item'); // --> 'Polozka'
+i18n.t('item', { count: 3 }); // --> 'Polozky'
+i18n.t('item', { count: 5 }); // --> 'Polozek'
+i18n.t('item', { count: 0 }); // --> 'Polozek'
+
+// interval
+resource = {
+    'item': 'Item',
+    'item_interval': '(1){One item};(2-5){Two to five items};(6-inf){More than 5 items};';
+};
+i18n.t('item'); // --> 'Item'
+i18n.t('item', { count: 1 }); // --> 'One item'
+i18n.t('item', { count: 3 }); // --> 'Two to five items'
+i18n.t('item', { count: 8 }); // --> 'More than 5 items'
+```
+
+### Nesting - i18next
+Nesting allows you to place a translation key into a translation value and have it translated.
+#### Usage
+```ts
+resource = {
+    welcome: 'Welcome, {{name}}!',
+    introduction: '$t(welcome) I am your i18n module',
+};
+i18n.t('introduction', { name: 'Radim' }); // --> 'Welcome, Radim! I am your i18n module.'
+```
+
+### Context - i18next
+Context middleware allows you to have one translation in multiple contexts. Useful for gender for example.
+```ts
+resource = {
+    friend: 'A friend',
+    friend_male: 'A boyfriend',
+    friend_female: 'A girlfriend',
+};
+i18n.t('friend'); // --> 'A friend'
+i18n.t('friend', { context: 'male' }); // --> 'A boyfriend'
+i18n.t('friend', { context: 'female' }); // --> 'A girlfriend'
+```