147 lines
4.5 KiB
Plaintext
147 lines
4.5 KiB
Plaintext
[[external-plugin-localization]]
|
|
== Localization for plugins outside the {kib} repo
|
|
|
|
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.
|
|
|
|
[discrete]
|
|
=== 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.
|
|
|
|
["source","shell"]
|
|
-----------
|
|
.
|
|
├── translations
|
|
│ ├── en.json
|
|
│ ├── ja-JP.json
|
|
│ └── zh-CN.json
|
|
└── .i18nrc.json
|
|
-----------
|
|
|
|
|
|
[discrete]
|
|
=== 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.
|
|
|
|
["source","json"]
|
|
-----------
|
|
{
|
|
"paths": {
|
|
"myPlugin": "src/ui",
|
|
},
|
|
"exclude": [
|
|
],
|
|
"translations": [
|
|
"translations/zh-CN.json",
|
|
"translations/ja-JP.json"
|
|
]
|
|
}
|
|
-----------
|
|
|
|
An example {kib} `.i18nrc.json` is {blob}.i18nrc.json[here].
|
|
|
|
Full documentation about i18n tooling is {blob}src/dev/i18n/README.md[here].
|
|
|
|
[discrete]
|
|
=== Extracting default messages
|
|
To extract the default messages from your plugin, run the following command:
|
|
|
|
["source","shell"]
|
|
-----------
|
|
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.
|
|
|
|
[discrete]
|
|
=== 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:
|
|
|
|
["source","shell"]
|
|
-----------
|
|
node scripts/i18n_check --fix --include-config ../kibana-extra/myPlugin/.i18nrc.json
|
|
-----------
|
|
|
|
|
|
[discrete]
|
|
=== Implementing i18n in the UI
|
|
|
|
{kib} relies on several UI frameworks (ReactJS and AngularJS) and
|
|
requires localization in different environments (browser and NodeJS).
|
|
The internationalization engine is framework agnostic and consumable in
|
|
all parts of {kib} (ReactJS, AngularJS and NodeJS).
|
|
|
|
To simplify
|
|
internationalization in UI frameworks, additional abstractions are
|
|
built around the I18n engine: `react-intl` for React and custom
|
|
components for AngularJS. https://github.com/yahoo/react-intl[React-intl]
|
|
is built around https://github.com/yahoo/intl-messageformat[intl-messageformat],
|
|
so both React and AngularJS frameworks use the same engine and the same
|
|
message syntax.
|
|
|
|
|
|
[discrete]
|
|
==== i18n for vanilla JavaScript
|
|
|
|
["source","js"]
|
|
-----------
|
|
import { i18n } from '@kbn/i18n';
|
|
|
|
export const HELLO_WORLD = i18n.translate('hello.wonderful.world', {
|
|
defaultMessage: 'Greetings, planet Earth!',
|
|
});
|
|
-----------
|
|
|
|
Full details are {kib-repo}tree/master/packages/kbn-i18n#vanilla-js[here].
|
|
|
|
[discrete]
|
|
==== i18n for React
|
|
|
|
To localize strings in React, use either `FormattedMessage` or `i18n.translate`.
|
|
|
|
|
|
["source","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">
|
|
</FormattedMessage>
|
|
</div>
|
|
);
|
|
};
|
|
-----------
|
|
|
|
Full details are {kib-repo}tree/master/packages/kbn-i18n#react[here].
|
|
|
|
[discrete]
|
|
=== Resources
|
|
|
|
To learn more about i18n tooling, see {blob}src/dev/i18n/README.md[i18n dev tooling].
|
|
|
|
To learn more about implementing i18n in the UI, use the following links:
|
|
|
|
* {blob}packages/kbn-i18n/README.md[i18n plugin]
|
|
* {blob}packages/kbn-i18n/GUIDELINE.md[i18n guidelines]
|