# I18n

Class · extends [`EventHandler`](https://api.playcanvas.com/engine/classes/EventHandler.md) · category: Other

Source: https://github.com/playcanvas/engine/blob/dfcc50fbbfba2388843041a875ec0ef5d1a586c5/src/framework/i18n/i18n.js#L16

Handles localization. Responsible for loading localization assets and returning translations for
a certain key. Can also handle plural forms. To override its default behavior define a different
implementation for [getText](https://api.playcanvas.com/engine/classes/I18n.md#gettext) and [getPluralText](https://api.playcanvas.com/engine/classes/I18n.md#getpluraltext).

## Constructors

### constructor

```ts
new I18n(app: AppBase)
```

Create a new I18n instance.

**Parameters**

- `app` ([`AppBase`](https://api.playcanvas.com/engine/classes/AppBase.md)): The application.

## Accessors

### assets

```ts
get assets(): number[] | Asset[]
set assets(value: number[] | Asset[])
```

Gets the array of asset ids that contain localization data in the expected format.

### locale

```ts
get locale(): string
set locale(value: string)
```

Gets the current locale.

## Methods

### addData

```ts
addData(data: any): void
```

Adds localization data. If the locale and key for a translation already exists it will be
overwritten.

**Parameters**

- `data` (`any`): The localization data. See example for the expected format of the
  data.

**Example**

```ts
this.app.i18n.addData({
    header: {
        version: 1
    },
    data: [{
        info: {
            locale: 'en-US'
        },
        messages: {
            "key": "translation",
            // The number of plural forms depends on the locale. See the manual for more information.
            "plural_key": ["one item", "more than one items"]
        }
    }, {
        info: {
            locale: 'fr-FR'
        },
        messages: {
            // ...
        }
    }]
});
```

### destroy

```ts
destroy(): void
```

Frees up memory.

### findAvailableLocale

```ts
findAvailableLocale(desiredLocale: string): string
```

Returns the first available locale based on the desired locale specified. First tries to
find the desired locale in the loaded translations and then tries to find an alternative
locale based on the language.

**Parameters**

- `desiredLocale` (`string`): The desired locale e.g. en-US.

**Returns** `string`: The locale found or if no locale is available returns the default en-US
locale.

**Example**

```ts
const locale = this.app.i18n.getText('en-US');
```

### getPluralText

```ts
getPluralText(key: string, n: number, locale?: string): string
```

Returns the pluralized translation for the specified key, number n and locale. If the locale
is not specified it will use the current locale.

**Parameters**

- `key` (`string`): The localization key.
- `n` (`number`): The number used to determine which plural form to use. E.g. For the
  phrase "5 Apples" n equals 5.
- `locale` (`string`, optional): The desired locale.

**Returns** `string`: The translated text. If no translations are found at all for the locale
then it will return the en-US translation. If no translation exists for that key then it
will return the localization key.

**Example**

```ts
// manually replace {number} in the resulting translation with our number
const localized = this.app.i18n.getPluralText('{number} apples', number).replace("{number}", number);
```

### getText

```ts
getText(key: string, locale?: string): string
```

Returns the translation for the specified key and locale. If the locale is not specified it
will use the current locale.

**Parameters**

- `key` (`string`): The localization key.
- `locale` (`string`, optional): The desired locale.

**Returns** `string`: The translated text. If no translations are found at all for the locale
then it will return the en-US translation. If no translation exists for that key then it will
return the localization key.

**Example**

```ts
const localized = this.app.i18n.getText('localization-key');
const localizedFrench = this.app.i18n.getText('localization-key', 'fr-FR');
```

### removeData

```ts
removeData(data: any): void
```

Removes localization data.

**Parameters**

- `data` (`any`): The localization data. The data is expected to be in the same format
  as [addData](https://api.playcanvas.com/engine/classes/I18n.md#adddata).

## Events

### EVENT_CHANGE

```ts
static EVENT_CHANGE: string = 'change'
```

Fired when the locale is changed.

**Example**

```ts
app.i18n.on('change', (newLocale, oldLocale) => {
   console.log(`Locale changed from ${oldLocale} to ${newLocale}`);
});
```

## Inherited from [EventHandler](https://api.playcanvas.com/engine/classes/EventHandler.md)

- `fire(name: string, arg1?: any, arg2?: any, arg3?: any, arg4?: any, arg5?: any, arg6?: any, arg7?: any, arg8?: any): EventHandler`
- `hasEvent(name: string): boolean`
- `off(name?: string, callback?: HandleEventCallback, scope?: any): EventHandler`
- `on(name: string, callback: HandleEventCallback, scope?: any): EventHandle`
- `once(name: string, callback: HandleEventCallback, scope?: any): EventHandle`