ContextQMD
Back to Kibana

Internationalization (i18n) [external-plugin-localization]

docs/extend/tutorials/i18n.md

9.5.04.3 KB
Original Source

Internationalization (i18n) [external-plugin-localization]

To internationalize your plugin, use {{kib}}'s i18n tool to create translation IDs and default messages. The tool extracts IDs and default messages into localization JSON files that {{kib}} 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 and the i18n guidelines.

Adding localization to your plugin

Add a translations directory at the root of your plugin. This directory holds the translation files {{kib}} uses.

shell
.
├── translations
│   ├── en.json
│   ├── ja-JP.json
│   ├── de-DE.json
│   ├── fr-FR.json
│   └── zh-CN.json
└── .i18nrc.json

Using {{kib}} i18n tooling

{{kib}} provides tools to:

  • Verify that all translations have translatable strings, and extract default messages from templates.
  • Verify translation files and integrate them into {{kib}}.

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 and the full i18n tooling documentation.

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

{{kib}} uses React and needs localization in both browser and Node.js environments. The internationalization engine is framework-agnostic and usable anywhere in {{kib}}. For React, an additional abstraction is built around the i18n engine using 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.

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.

Resources