Skip to content

Commit e97b329

Browse files
schershSarah Hersh
schersh
authored and
Sarah Hersh
committed
resolve merge conflict between master and 6.7 (#34570)
[DOCS] Adds i18n docs to master
1 parent 53cc4ff commit e97b329

5 files changed

+209
-1
lines changed

‎docs/development/plugin-development.asciidoc

+3
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ The Kibana plugin interfaces are in a state of constant development. We cannot
99
* <<development-plugin-resources>>
1010
* <<development-uiexports>>
1111
* <<development-plugin-functional-tests>>
12+
* <<development-plugin-localization>>
1213
* <<development-visualize-index>>
1314
* <<add-data-guide>>
1415

@@ -19,6 +20,8 @@ include::plugin/development-uiexports.asciidoc[]
1920

2021
include::plugin/development-plugin-functional-tests.asciidoc[]
2122

23+
include::plugin/development-plugin-localization.asciidoc[]
24+
2225
include::visualize/development-visualize-index.asciidoc[]
2326

2427
include::add-data-guide.asciidoc[]

‎docs/development/plugin/development-plugin-localization.asciidoc

+164
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,164 @@
1+
[[development-plugin-localization]]
2+
=== Localization for plugins
3+
4+
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 Kibana to use when running your plugin.
5+
6+
[float]
7+
==== Adding localization to your plugin
8+
9+
You must add a `translations` directory at the root of your plugin. This directory will contain the translation files that Kibana uses.
10+
11+
["source","shell"]
12+
-----------
13+
.
14+
├── translations
15+
│ ├── en.json
16+
│ └── zh-CN.json
17+
└── .i18nrc.json
18+
-----------
19+
20+
21+
[float]
22+
==== Using Kibana i18n tooling
23+
To simplify the localization process, Kibana provides tools for the following functions:
24+
25+
* Verify all translations have translatable strings and extract default messages from templates
26+
* Verify translation files and integrate them into Kibana
27+
28+
To use Kibana i18n tooling, create a `.i18nrc.json` file with the following configs:
29+
30+
* `paths`. The directory from which the i18n translation IDs are extracted.
31+
* `exclude`. The list of files to exclude while parsing paths.
32+
* `translations`. The list of translations where JSON localizations are found.
33+
34+
["source","json"]
35+
-----------
36+
{
37+
"paths": {
38+
"myPlugin": "src/ui",
39+
},
40+
"exclude": [
41+
],
42+
"translations": [
43+
"translations/zh-CN.json"
44+
]
45+
}
46+
-----------
47+
48+
An example Kibana `.i18nrc.json` is {blob}.i18nrc.json[here].
49+
50+
Full documentation about i18n tooling is {blob}src/dev/i18n/README.md[here].
51+
52+
[float]
53+
==== Extracting default messages
54+
To extract the default messages from your plugin, run the following command:
55+
56+
["source","shell"]
57+
-----------
58+
node scripts/i18n_extract --output-dir ./translations --include-config ../kibana-extra/myPlugin/.i18nrc.json
59+
-----------
60+
61+
This outputs a `en.json` file inside the `translations` directory. To localize other languages, clone the file and translate each string.
62+
63+
[float]
64+
==== Checking i18n messages
65+
66+
Checking i18n does the following:
67+
68+
* Checks all existing labels for violations.
69+
* Takes translations from .i18nrc.json and compares them to the messages extracted and validated at the step above and:
70+
** Checks for unused translations. If you remove a label that has a corresponding translation, you must also remove the label from the translations file.
71+
* 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.
72+
73+
To check your i18n translations, run the following command:
74+
75+
["source","shell"]
76+
-----------
77+
node scripts/i18n_check --fix --include-config ../kibana-extra/myPlugin/.i18nrc.json
78+
-----------
79+
80+
81+
[float]
82+
==== Implementing i18n in the UI
83+
84+
Kibana relies on several UI frameworks (ReactJS and AngularJS) and
85+
requires localization in different environments (browser and NodeJS).
86+
The internationalization engine is framework agnostic and consumable in
87+
all parts of Kibana (ReactJS, AngularJS and NodeJS). In order to simplify
88+
internationalization in UI frameworks, additional abstractions are
89+
built around the I18n engine: `react-intl` for React and custom
90+
components for AngularJS. https://github.com/yahoo/react-intl[React-intl]
91+
is built around https://github.com/yahoo/intl-messageformat[intl-messageformat],
92+
so both React and AngularJS frameworks use the same engine and the same
93+
message syntax.
94+
95+
96+
[float]
97+
===== i18n for vanilla JavaScript
98+
99+
["source","js"]
100+
-----------
101+
import { i18n } from '@kbn/i18n';
102+
103+
export const HELLO_WORLD = i18n.translate('hello.wonderful.world', {
104+
defaultMessage: 'Greetings, planet Earth!',
105+
});
106+
-----------
107+
108+
Full details are {repo}tree/6.7/packages/kbn-i18n#vanilla-js[here].
109+
110+
[float]
111+
===== i18n for React
112+
113+
To localize strings in React, use either `FormattedMessage` or `i18n.translate`.
114+
115+
116+
["source","js"]
117+
-----------
118+
import { i18n } from '@kbn/i18n';
119+
import { FormattedMessage } from '@kbn/i18n/react';
120+
121+
export const Component = () => {
122+
return (
123+
<div>
124+
{i18n.translate('xpack.someText', { defaultMessage: 'Some text' })}
125+
<FormattedMessage id="xpack.someOtherText" defaultMessage="Some other text">
126+
</FormattedMessage>
127+
</div>
128+
);
129+
};
130+
-----------
131+
132+
Full details are {repo}tree/6.7/packages/kbn-i18n#react[here].
133+
134+
135+
136+
[float]
137+
===== i18n for Angular
138+
139+
AngularJS wrapper has 4 entities: translation `provider`, `service`, `directive` and `filter`. Both the directive and the filter use the translation `service` with i18n engine under the hood.
140+
141+
142+
The translation directive has the following syntax:
143+
["source","js"]
144+
-----------
145+
<ANY
146+
i18n-id="{string}"
147+
i18n-default-message="{string}"
148+
[i18n-values="{object}"]
149+
[i18n-description="{string}"]
150+
></ANY>
151+
-----------
152+
153+
Full details are {repo}tree/6.7/packages/kbn-i18n#angularjs[here].
154+
155+
156+
[float]
157+
==== Resources
158+
159+
To learn more about i18n tooling, see {blob}src/dev/i18n/README.md[i18n dev tooling].
160+
161+
To learn more about implementing i18n in the UI, follow the links below:
162+
163+
* {blob}packages/kbn-i18n/README.md[i18n plugin]
164+
* {blob}packages/kbn-i18n/GUIDELINE.md[i18n Guidelines]

‎docs/settings/i18n-settings.asciidoc

+17
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
[role="xpack"]
2+
[[i18n-settings-kb]]
3+
=== i18n settings in Kibana
4+
5+
You do not need to configure any settings to run Kibana in English.
6+
7+
[float]
8+
[[general-i18n-settings-kb]]
9+
==== General i18n Settings
10+
11+
`i18n.locale`::
12+
Kibana currently supports the following locales:
13+
+
14+
- English - `en` (default)
15+
- Chinese - `zh-CN`
16+
17+

‎docs/settings/settings-xkb.asciidoc

+21
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
[role="xpack"]
2+
[[settings-xpack-kb]]
3+
== {xpack} Settings in {kib}
4+
[subs="attributes"]
5+
++++
6+
<titleabbrev>{xpack} Settings</titleabbrev>
7+
++++
8+
9+
include::{asciidoc-dir}/../../shared/settings.asciidoc[]
10+
11+
For more {kib} configuration settings, see <<settings>>.
12+
13+
include::apm-settings.asciidoc[]
14+
include::dev-settings.asciidoc[]
15+
include::graph-settings.asciidoc[]
16+
include::infrastructure-ui-settings.asciidoc[]
17+
include::logs-ui-settings.asciidoc[]
18+
include::ml-settings.asciidoc[]
19+
include::reporting-settings.asciidoc[]
20+
include::spaces-settings.asciidoc[]
21+
include::i18n-settings.asciidoc[]

‎docs/setup/settings.asciidoc

+4-1
Original file line numberDiff line numberDiff line change
@@ -294,6 +294,9 @@ disable the License Management user interface.
294294
`xpack.rollup.enabled:`:: *Default: true* Set this value to false to disable the
295295
Rollup user interface.
296296

297+
`i18n.locale`:: *Default: en* Set this value to change the Kibana interface language. Valid locales are: `en`, `zh-CN`.
298+
299+
297300
include::{docdir}/settings/apm-settings.asciidoc[]
298301
include::{docdir}/settings/dev-settings.asciidoc[]
299302
include::{docdir}/settings/graph-settings.asciidoc[]
@@ -304,4 +307,4 @@ include::{docdir}/settings/monitoring-settings.asciidoc[]
304307
include::{docdir}/settings/reporting-settings.asciidoc[]
305308
include::secure-settings.asciidoc[]
306309
include::{docdir}/settings/security-settings.asciidoc[]
307-
include::{docdir}/settings/spaces-settings.asciidoc[]
310+
include::{docdir}/settings/spaces-settings.asciidoc[]

0 commit comments

Comments
 (0)