---
title: Internationalization (i18n)
description: Internationalize a Kibana plugin — add translatable strings, use the i18n tooling, and implement translations in vanilla JS and React.
url: https://docs-v3-preview.elastic.dev/elastic/kibana/tree/main/extend/tutorials/i18n
products:
  - Kibana
---

# Internationalization (i18n)
To internationalize your plugin, use Kibana's i18n tool to create translation IDs and default messages. The tool extracts IDs and default messages into localization JSON files that Kibana uses when running your plugin.
Elastic-supported translations ship in the built-in `translations` plugin, owned by the Localizations team. For the underlying API reference, see [`@kbn/i18n`](https://github.com/elastic/kibana/tree/main/src/platform/packages/shared/kbn-i18n) and the [i18n guidelines](https://github.com/elastic/kibana/blob/master/src/platform/packages/shared/kbn-i18n/GUIDELINE.md).

## Adding localization to your plugin

Add a `translations` directory at the root of your plugin. This directory holds the translation files Kibana uses.
```shell
.
├── translations
│   ├── en.json
│   ├── ja-JP.json
│   ├── de-DE.json
│   ├── fr-FR.json
│   └── zh-CN.json
└── .i18nrc.json
```


## Using Kibana i18n tooling

Kibana provides tools to:
- Verify that all translations have translatable strings, and extract default messages from templates.
- Verify translation files and integrate them into Kibana.

To use the tools, create a `.i18nrc.json` file with:
- `paths`: directories from which i18n translation IDs are extracted.
- `exclude`: files to exclude while parsing paths.
- `translations`: translation files where JSON localizations live.

```json
{
  "paths": {
    "myPlugin": "src/ui"
  },
  "exclude": [],
  "translations": [
    "translations/zh-CN.json",
    "translations/fr-FR.json",
    "translations/de-DE.json",
    "translations/ja-JP.json"
  ]
}
```

See an [example `.i18nrc.json`](https://github.com/elastic/kibana/blob/current/.i18nrc.json) and the [full i18n tooling documentation](https://github.com/elastic/kibana/blob/current/src/dev/i18n/README.md).

## Extracting default messages

Extract the default messages from your plugin:
```shell
node scripts/i18n_extract --output-dir ./translations --include-config ../kibana-extra/myPlugin/.i18nrc.json
```

This outputs an `en.json` file inside the `translations` directory. To localize another language, copy the file and translate each string.

## Checking i18n messages

The i18n check:
- Checks existing labels for violations.
- Takes translations from `.i18nrc.json` and compares them against the extracted and validated messages.
  - **Unused translations:** if you remove a label that has a corresponding translation, you must also remove the label from the translations file.
- **Incompatible translations:** if you add or remove a parameter from an existing string, you must also remove the label from the translations file.

Run the check:
```shell
node scripts/i18n_check --fix --include-config ../kibana-extra/myPlugin/.i18nrc.json
```


## Implementing i18n in the UI

Kibana uses React and needs localization in both browser and Node.js environments. The internationalization engine is framework-agnostic and usable anywhere in Kibana. For React, an additional abstraction is built around the i18n engine using [React-intl](https://github.com/yahoo/react-intl).

### Vanilla JavaScript

```js
import { i18n } from '@kbn/i18n';

export const HELLO_WORLD = i18n.translate('hello.wonderful.world', {
  defaultMessage: 'Greetings, planet Earth!',
});
```

See the [vanilla JS i18n docs](https://github.com/elastic/kibana/tree/main/src/platform/packages/shared/kbn-i18n#vanilla-js).

### React

Localize strings in React with either `FormattedMessage` or `i18n.translate`:
```js
import { i18n } from '@kbn/i18n';
import { FormattedMessage } from '@kbn/i18n-react';

export const Component = () => {
  return (
    <div>
      {i18n.translate('xpack.someText', { defaultMessage: 'Some text' })}
      <FormattedMessage id="xpack.someOtherText" defaultMessage="Some other text" />
    </div>
  );
};
```

See the [React i18n docs](https://github.com/elastic/kibana/tree/main/src/platform/packages/shared/kbn-i18n#react).

## Resources

- [i18n dev tooling](https://github.com/elastic/kibana/blob/master/src/dev/i18n/README.md)
- [`@kbn/i18n` package](https://github.com/elastic/kibana/blob/master/src/platform/packages/shared/kbn-i18n/README.md)
- [i18n guidelines](https://github.com/elastic/kibana/blob/master/src/platform/packages/shared/kbn-i18n/GUIDELINE.md)