# SYS-Translate

The sys-translate module is a I18n helper library created to simplify internazionalization and localitaion.

It provides a react based component and a javascript object to translate the desired strings.

## Installation

install with npm:

```
npm install sys-translate
```

## Usage

The library provides two ways of use 
- I18nLocalizer javascript object
- React Translate component

### I18nLocalizer javascript object

The createDefaultI18nLocalizer function requires as argument a configuration object of this type:

```ts
export interface IDefaultI18nLocalizerConfig {
    polyGlot: Polyglot; // Polyglot.js
    loading: string[];
    defaultLocalizer: I18nLocalizer; // A default localizer can be passed to be replaced
}
```

And return a an I18nLocalizer object based on this interface: 

```ts
export interface I18nLocalizer {
    /**
     * Return the localization string for the provided key
     * @param {string} key the key to get the localization for.
     * @param {any} default the default value if a localization
     * value for the provided key could not be found.
     * @returns a localization string for the provided key or
     * the default value if provided otherwise, it return the
     * key.
     */
    get(key: string, def?: any): string;
    /**
     * Return the localization string for the provided key
     * and replacing any placeholders in that string with
     * values from the replacements array.
     * @param {string} key the key to get the localization for.
     * @param {any[]|any} replacements an array of replacements for
     * any placeholders in the localizatioin text.
     * @param {string} default a default localization string to use if
     * a localization for the provided key could not be found.
     * @returns localization string for the provided key.
     *
     * @example
     * ```javascript
     *
     *  var localizer;
     *  var valueForSomeKey = 'this is my localization text {1}, {0}';
     *  localizer.format('somekey',['there','here']);
     *  //result will be
     *  //this is my localization text here, there
     *
     * ```
     */
    format(key: string, replacements?: any[] | any, def?: string): string;

    /**
     * Loads the localization dictionary.
     * @returns {Promise<any>} a promise that resolves a dictionary
     * containing the localization of the current language.
     */
    load(): Promise<any>;

    formatNumber(num: number): string;
    randomLoadingMessage(): string;
}
```

#### Example of usage

```ts
const TranslateConfig = {
    polyGlot: Sysdoc.Locale.Polyglot,
    defaultLocalizer: Sysdoc.Locale.DefaultLocalizer,
    loading: Sysdoc.Locale.Data.loading,
};

const i18n = createDefaultI18nLocalizer(TranslateConfig);
const myFav:string = i18n.format(this.i18n.format('phrases.myFavourites'); // "My Favourite"
```

### React Translate component

```ts
import { Translate } from "sys-translate";

export class Example extends React.PureComponent<null, null> {
    render () {
        return (
            <div>
                <Translate>Title</Translate>
            </div>
        )
    }
}
```

## More information

This functionality was extracted from the JLR Way project. For more information refer to [https://bitbucket.org/sysdoc/jlrway2]