kibana/docs/extend/external-plugin-localization.md

mapped_pages
https://www.elastic.co/guide/en/kibana/current/external-plugin-localization.html

Localization for plugins outside the Kibana repo [external-plugin-localization]

To introduce localization for your plugin, use our i18n tool to create IDs and default messages. You can then extract these IDs with respective default messages into localization JSON files for {{kib}} to use when running your plugin.

Adding localization to your plugin [_adding_localization_to_your_plugin]

You must add a translations directory at the root of your plugin. This directory will contain the translation files that {{kib}} uses.

.
├── translations
│   ├── en.json
│   ├── ja-JP.json
│   └── zh-CN.json
└── .i18nrc.json

Using {{kib}} i18n tooling [_using_kib_i18n_tooling]

To simplify the localization process, {{kib}} provides tools for the following functions:

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

To use {{kib}} i18n tooling, create a .i18nrc.json file with the following configs:

• paths. The directory from which the i18n translation IDs are extracted.
• exclude. The list of files to exclude while parsing paths.
• translations. The list of translations where JSON localizations are found.

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

An example {{kib}} .i18nrc.json is here.

Full documentation about i18n tooling is here.

Extracting default messages [_extracting_default_messages]

To extract the default messages from your plugin, run the following command:

node scripts/i18n_extract --output-dir ./translations --include-config ../kibana-extra/myPlugin/.i18nrc.json

This outputs a en.json file inside the translations directory. To localize other languages, clone the file and translate each string.

Checking i18n messages [_checking_i18n_messages]

Checking i18n does the following:

• Checks all existing labels for violations.

• Takes translations from .i18nrc.json and compares them to the messages extracted and validated.

  • Checks for unused translations. If you remove a label that has a corresponding translation, you must also remove the label from the translations file.
  • Checks for incompatible translations. If you add or remove a new parameter from an existing string, you must also remove the label from the translations file.

To check your i18n translations, run the following command:

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

Implementing i18n in the UI [_implementing_i18n_in_the_ui]

{{kib}} relies on ReactJS and requires localization in different environments (browser and NodeJS). The internationalization engine is framework agnostic and consumable in all parts of {{kib}} (ReactJS, and NodeJS).

To simplify internationalization in React, an additional abstraction is built around the I18n engine using React-intl for React.

i18n for vanilla JavaScript [_i18n_for_vanilla_javascript]

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

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

Full details are here.

i18n for React [_i18n_for_react]

To localize strings in React, use 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">
      </FormattedMessage>
    </div>
  );
};

Full details are here.

Resources [_resources]

To learn more about i18n tooling, see i18n dev tooling.

To learn more about implementing i18n in the UI, use the following links:

• i18n plugin
• i18n guidelines