Loading

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 and the i18n guidelines.

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

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

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.
{
  "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.

Extract the default messages from your plugin:

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.

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:

node scripts/i18n_check --fix --include-config ../kibana-extra/myPlugin/.i18nrc.json

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.

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

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

See the vanilla JS i18n docs.

Localize strings in React with either FormattedMessage or i18n.translate:

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.