From c5c14be19eb9f9501b61d35ec97b59acb599a666 Mon Sep 17 00:00:00 2001 From: Bamieh Date: Wed, 6 Mar 2019 16:38:28 +0400 Subject: [PATCH 1/9] add i18n kibana config docs --- docs/settings/i18n-settings.asciidoc | 19 +++++++++++++++++++ docs/settings/settings-xkb.asciidoc | 1 + docs/setup/settings.asciidoc | 2 ++ 3 files changed, 22 insertions(+) create mode 100644 docs/settings/i18n-settings.asciidoc diff --git a/docs/settings/i18n-settings.asciidoc b/docs/settings/i18n-settings.asciidoc new file mode 100644 index 0000000000000..17dad3ead5e93 --- /dev/null +++ b/docs/settings/i18n-settings.asciidoc @@ -0,0 +1,19 @@ +[role="xpack"] +[[i18n-settings-kb]] +=== Internationalization Settings in Kibana +++++ +i18n Settings +++++ + +You do not need to configure any settings to have kibana in English locale. + +[float] +[[general-i18n-settings-kb]] +==== General i18n Settings + +`i18n.locale`:: +Set to `en` (default) for english localization. + ++ +Current available translations are `en` for English locale and `zh-CN` for Chinese locale. + + diff --git a/docs/settings/settings-xkb.asciidoc b/docs/settings/settings-xkb.asciidoc index 98e2784bbb0a8..186124e77efd7 100644 --- a/docs/settings/settings-xkb.asciidoc +++ b/docs/settings/settings-xkb.asciidoc @@ -17,3 +17,4 @@ include::logs-ui-settings.asciidoc[] include::ml-settings.asciidoc[] include::reporting-settings.asciidoc[] include::spaces-settings.asciidoc[] +include::i18n-settings.asciidoc[] diff --git a/docs/setup/settings.asciidoc b/docs/setup/settings.asciidoc index 7d9ee6b98a463..48f7834bd9cb1 100644 --- a/docs/setup/settings.asciidoc +++ b/docs/setup/settings.asciidoc @@ -231,3 +231,5 @@ unauthenticated users to access the Kibana server status API and status page. `rollup.enabled:`:: *Default: true* Set this value to false to disable the Rollup user interface. `license_management.enabled`:: *Default: true* Set this value to false to disable the License Management user interface. + +`i18n.locale`:: *Default: en* Set this value to change Kibana interface language. Valid locales are: `en`, `zh-CN`. \ No newline at end of file From 07f3ca7c4015a5e7ea5e09fd0eb041d7f3983200 Mon Sep 17 00:00:00 2001 From: Bamieh Date: Tue, 26 Mar 2019 15:11:22 +0300 Subject: [PATCH 2/9] add development settings and tell about locale --- .../development-plugin-localization.asciidoc | 182 ++++++++++++++++++ docs/index.asciidoc | 2 + docs/localization.asciidoc | 19 ++ docs/settings/localization-settings.asciidoc | 0 4 files changed, 203 insertions(+) create mode 100644 docs/development/plugin/development-plugin-localization.asciidoc create mode 100644 docs/localization.asciidoc create mode 100644 docs/settings/localization-settings.asciidoc diff --git a/docs/development/plugin/development-plugin-localization.asciidoc b/docs/development/plugin/development-plugin-localization.asciidoc new file mode 100644 index 0000000000000..870ca6fa39767 --- /dev/null +++ b/docs/development/plugin/development-plugin-localization.asciidoc @@ -0,0 +1,182 @@ +[[development-plugin-localization]] +=== Localization for Plugins + +To introduce localization for your plugin. Use our i18n tool to create Ids and default messages. Then extract those Ids into localization json files to be used by kibana when running your plugin. +The following guide will help you setup localization for your plugin. + +[float] +==== Adding localizations to your plugin + +To create translations add a `translations` directory at the root of your plugin. This folder will include the translations files which will be automatically parsed and used by kibana. + +["source","shell"] +----------- +. +├── translations +│ ├── en.json +│ └── zh-CN.json +└── .i18nrc.json +----------- + + +[float] +==== Using kibana i18n tooling +In order to simplify localization process, some additional tools were implemented: +- tool for verifying all translations have translatable strings and extracting default messages from templates +- tool for verifying translation files and integrating them to Kibana + +To use kibana i18n tooling, create a `.i18nrc.json` file providing the following configs: +* `paths` directory paths where i18n translation ids are to be extracted from +* `exclude` list of files to exclude while parsing paths +* `translations` list of translations where json localizations are to be found. + +["source","json"] +----------- +{ + "paths": { + "myPlugin": "src/ui", + }, + "exclude": [ + ], + "translations": [ + "translations/zh-CN.json" + ] +} +----------- + +A full example for kibana `.i18nrc.json` can be {blob}6.7/.i18nrc.json[found here]. + +Full documentation about i18n tooling can be {blob}6.7/src/dev/i18n/README.md[found here]. + +[float] +==== Extracting default messages +To extract the default messages from your plugin run the following command: + +["source","shell"] +----------- +node ../../kibana/scripts/i18n_extract --include-config ./.i18nrc.json --output-dir ./translations +node scripts/i18n_extract --output-dir ./translations --include-config ../kibana-extra/myPlugin/.i18nrc.json +----------- + +This will output a `en.json` file inside the `translations` directory. To localize other languages, clone the file and translate each string. + +[float] +==== Checking i18n messages + +Checking i18n does the following: +- Check all existing labels for violations +- Take translations from .i18nrc.json and compare them to the messages extracted and validated at the step above and: + - Check for unused translations - if developer removed a label which has corresponding translation they will need to remove this label from translations file as well, semi-automatic for now (see below) + - Check for incompatible translations - if developer, let's say removed or added new parameter to an existing string, they will need to remove this label from 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 +----------- + + +[float] +==== Implementing i18n in UI + +Kibana relies on several UI frameworks (ReactJS and AngularJS) and +requires localization in different environments (browser and NodeJS). +Internationalization engine is framework agnostic and consumable in +all parts of Kibana (ReactJS, AngularJS and NodeJS). In order to simplify +internationalization in UI frameworks, the 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. + + +[float] +==== 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 can be {repo}tree/6.7/packages/kbn-i18n#vanilla-js[found here]. + +[float] +==== 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 ( +
+ {i18n.translate('xpack.someText', { defaultMessage: 'Some text' })} + + +
+ ); +}; +----------- + +Full details can be {repo}tree/6.7/packages/kbn-i18n#react[found here]. + + + +[float] +==== i18n for Angular + +To localize strings in React, use either `FormattedMessage` or `i18n.translate`. + + +The translation directive has the following syntax: +["source","js"] +----------- + +----------- + +Full details can be {repo}tree/6.7/packages/kbn-i18n#angularjs[found here]. + + +[float] +==== Resources + +To Learn more i18n tooling, see {blob}6.7/src/dev/i18n/README.md[i18n dev tooling]. + +To Learn more about implementing i18n in UI, follow the links below: +* {blob}6.7/packages/kbn-i18n/README.md[i18n plugin] +* {blob}6.7/packages/kbn-i18n/GUIDELINE.md[i18n Guidelines] + + + + + + + + + + + + + + +[[i18n]] +=== i18n in Kibana + + + + diff --git a/docs/index.asciidoc b/docs/index.asciidoc index 4871336c147e9..e6f31111173aa 100644 --- a/docs/index.asciidoc +++ b/docs/index.asciidoc @@ -42,6 +42,8 @@ include::timelion.asciidoc[] include::canvas.asciidoc[] +include::localization.asciidoc[] + include::ml/index.asciidoc[] include::maps/index.asciidoc[] diff --git a/docs/localization.asciidoc b/docs/localization.asciidoc new file mode 100644 index 0000000000000..91718e6a13ec1 --- /dev/null +++ b/docs/localization.asciidoc @@ -0,0 +1,19 @@ +[role="xpack"] +[[localization]] += Localization + +[partintro] +-- + +Introduced in version 6.7 Localization allows you to change the language in {kib}. + +Kibana currently supports the following locales: +* English - `en` (default) +* Chinese - `zh-CN` + +We will be supporting -many- more locales in the near future! See <<>> for instructions on how to configure {kib} for setting locale. For localizing your plugin or contributing to {kib} i18n see <>. + +-- + +include::development/plugin/development-plugin-localization.asciidoc[] + diff --git a/docs/settings/localization-settings.asciidoc b/docs/settings/localization-settings.asciidoc new file mode 100644 index 0000000000000..e69de29bb2d1d From b699fc0e8b0e7c874774ef7d08ae868f6c6c293d Mon Sep 17 00:00:00 2001 From: Bamieh Date: Tue, 26 Mar 2019 16:18:40 +0300 Subject: [PATCH 3/9] localization in docs --- docs/development/plugin-development.asciidoc | 3 + .../development-plugin-localization.asciidoc | 177 ------------------ docs/index.asciidoc | 2 - docs/localization.asciidoc | 19 -- docs/settings/i18n-settings.asciidoc | 9 +- docs/settings/localization-settings.asciidoc | 0 6 files changed, 8 insertions(+), 202 deletions(-) delete mode 100644 docs/localization.asciidoc delete mode 100644 docs/settings/localization-settings.asciidoc diff --git a/docs/development/plugin-development.asciidoc b/docs/development/plugin-development.asciidoc index 6167c8a195a64..37ab6664d5fb0 100644 --- a/docs/development/plugin-development.asciidoc +++ b/docs/development/plugin-development.asciidoc @@ -9,6 +9,7 @@ The Kibana plugin interfaces are in a state of constant development. We cannot * <> * <> * <> +* <> * <> * <> @@ -19,6 +20,8 @@ include::plugin/development-uiexports.asciidoc[] include::plugin/development-plugin-functional-tests.asciidoc[] +include::plugin/development-plugin-localization.asciidoc[] + include::visualize/development-visualize-index.asciidoc[] include::add-data-guide.asciidoc[] diff --git a/docs/development/plugin/development-plugin-localization.asciidoc b/docs/development/plugin/development-plugin-localization.asciidoc index 870ca6fa39767..8292779406c8f 100644 --- a/docs/development/plugin/development-plugin-localization.asciidoc +++ b/docs/development/plugin/development-plugin-localization.asciidoc @@ -3,180 +3,3 @@ To introduce localization for your plugin. Use our i18n tool to create Ids and default messages. Then extract those Ids into localization json files to be used by kibana when running your plugin. The following guide will help you setup localization for your plugin. - -[float] -==== Adding localizations to your plugin - -To create translations add a `translations` directory at the root of your plugin. This folder will include the translations files which will be automatically parsed and used by kibana. - -["source","shell"] ------------ -. -├── translations -│ ├── en.json -│ └── zh-CN.json -└── .i18nrc.json ------------ - - -[float] -==== Using kibana i18n tooling -In order to simplify localization process, some additional tools were implemented: -- tool for verifying all translations have translatable strings and extracting default messages from templates -- tool for verifying translation files and integrating them to Kibana - -To use kibana i18n tooling, create a `.i18nrc.json` file providing the following configs: -* `paths` directory paths where i18n translation ids are to be extracted from -* `exclude` list of files to exclude while parsing paths -* `translations` list of translations where json localizations are to be found. - -["source","json"] ------------ -{ - "paths": { - "myPlugin": "src/ui", - }, - "exclude": [ - ], - "translations": [ - "translations/zh-CN.json" - ] -} ------------ - -A full example for kibana `.i18nrc.json` can be {blob}6.7/.i18nrc.json[found here]. - -Full documentation about i18n tooling can be {blob}6.7/src/dev/i18n/README.md[found here]. - -[float] -==== Extracting default messages -To extract the default messages from your plugin run the following command: - -["source","shell"] ------------ -node ../../kibana/scripts/i18n_extract --include-config ./.i18nrc.json --output-dir ./translations -node scripts/i18n_extract --output-dir ./translations --include-config ../kibana-extra/myPlugin/.i18nrc.json ------------ - -This will output a `en.json` file inside the `translations` directory. To localize other languages, clone the file and translate each string. - -[float] -==== Checking i18n messages - -Checking i18n does the following: -- Check all existing labels for violations -- Take translations from .i18nrc.json and compare them to the messages extracted and validated at the step above and: - - Check for unused translations - if developer removed a label which has corresponding translation they will need to remove this label from translations file as well, semi-automatic for now (see below) - - Check for incompatible translations - if developer, let's say removed or added new parameter to an existing string, they will need to remove this label from 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 ------------ - - -[float] -==== Implementing i18n in UI - -Kibana relies on several UI frameworks (ReactJS and AngularJS) and -requires localization in different environments (browser and NodeJS). -Internationalization engine is framework agnostic and consumable in -all parts of Kibana (ReactJS, AngularJS and NodeJS). In order to simplify -internationalization in UI frameworks, the 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. - - -[float] -==== 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 can be {repo}tree/6.7/packages/kbn-i18n#vanilla-js[found here]. - -[float] -==== 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 ( -
- {i18n.translate('xpack.someText', { defaultMessage: 'Some text' })} - - -
- ); -}; ------------ - -Full details can be {repo}tree/6.7/packages/kbn-i18n#react[found here]. - - - -[float] -==== i18n for Angular - -To localize strings in React, use either `FormattedMessage` or `i18n.translate`. - - -The translation directive has the following syntax: -["source","js"] ------------ - ------------ - -Full details can be {repo}tree/6.7/packages/kbn-i18n#angularjs[found here]. - - -[float] -==== Resources - -To Learn more i18n tooling, see {blob}6.7/src/dev/i18n/README.md[i18n dev tooling]. - -To Learn more about implementing i18n in UI, follow the links below: -* {blob}6.7/packages/kbn-i18n/README.md[i18n plugin] -* {blob}6.7/packages/kbn-i18n/GUIDELINE.md[i18n Guidelines] - - - - - - - - - - - - - - -[[i18n]] -=== i18n in Kibana - - - - diff --git a/docs/index.asciidoc b/docs/index.asciidoc index 4e53e0e39dbd6..c74b0fa8ac894 100644 --- a/docs/index.asciidoc +++ b/docs/index.asciidoc @@ -42,8 +42,6 @@ include::timelion.asciidoc[] include::canvas.asciidoc[] -include::localization.asciidoc[] - include::ml/index.asciidoc[] include::maps/index.asciidoc[] diff --git a/docs/localization.asciidoc b/docs/localization.asciidoc deleted file mode 100644 index 91718e6a13ec1..0000000000000 --- a/docs/localization.asciidoc +++ /dev/null @@ -1,19 +0,0 @@ -[role="xpack"] -[[localization]] -= Localization - -[partintro] --- - -Introduced in version 6.7 Localization allows you to change the language in {kib}. - -Kibana currently supports the following locales: -* English - `en` (default) -* Chinese - `zh-CN` - -We will be supporting -many- more locales in the near future! See <<>> for instructions on how to configure {kib} for setting locale. For localizing your plugin or contributing to {kib} i18n see <>. - --- - -include::development/plugin/development-plugin-localization.asciidoc[] - diff --git a/docs/settings/i18n-settings.asciidoc b/docs/settings/i18n-settings.asciidoc index 17dad3ead5e93..8c7f65c796d3d 100644 --- a/docs/settings/i18n-settings.asciidoc +++ b/docs/settings/i18n-settings.asciidoc @@ -1,19 +1,20 @@ [role="xpack"] [[i18n-settings-kb]] -=== Internationalization Settings in Kibana +=== i18n settings in Kibana ++++ i18n Settings ++++ -You do not need to configure any settings to have kibana in English locale. +You do not need to configure any settings to have kibana in English. [float] [[general-i18n-settings-kb]] ==== General i18n Settings `i18n.locale`:: -Set to `en` (default) for english localization. + +Kibana currently supports the following locales: + -Current available translations are `en` for English locale and `zh-CN` for Chinese locale. +- English - `en` (default) +- Chinese - `zh-CN` diff --git a/docs/settings/localization-settings.asciidoc b/docs/settings/localization-settings.asciidoc deleted file mode 100644 index e69de29bb2d1d..0000000000000 From a87db3a0dc1c429dd42954018fdcad4878f01482 Mon Sep 17 00:00:00 2001 From: Bamieh Date: Tue, 26 Mar 2019 16:22:20 +0300 Subject: [PATCH 4/9] development plugin localization --- .../development-plugin-localization.asciidoc | 157 ++++++++++++++++++ 1 file changed, 157 insertions(+) diff --git a/docs/development/plugin/development-plugin-localization.asciidoc b/docs/development/plugin/development-plugin-localization.asciidoc index 8292779406c8f..65f7e0e35d56a 100644 --- a/docs/development/plugin/development-plugin-localization.asciidoc +++ b/docs/development/plugin/development-plugin-localization.asciidoc @@ -3,3 +3,160 @@ To introduce localization for your plugin. Use our i18n tool to create Ids and default messages. Then extract those Ids into localization json files to be used by kibana when running your plugin. The following guide will help you setup localization for your plugin. + +[float] +==== Adding localizations to your plugin + +To create translations add a `translations` directory at the root of your plugin. This folder will include the translations files which will be automatically parsed and used by kibana. + +["source","shell"] +----------- +. +├── translations +│ ├── en.json +│ └── zh-CN.json +└── .i18nrc.json +----------- + + +[float] +==== Using kibana i18n tooling +In order to simplify localization process, some additional tools were implemented: +- tool for verifying all translations have translatable strings and extracting default messages from templates +- tool for verifying translation files and integrating them to Kibana + +To use kibana i18n tooling, create a `.i18nrc.json` file providing the following configs: +* `paths` directory paths where i18n translation ids are to be extracted from +* `exclude` list of files to exclude while parsing paths +* `translations` list of translations where json localizations are to be found. + +["source","json"] +----------- +{ + "paths": { + "myPlugin": "src/ui", + }, + "exclude": [ + ], + "translations": [ + "translations/zh-CN.json" + ] +} +----------- + +A full example for kibana `.i18nrc.json` can be {blob}6.7/.i18nrc.json[found here]. + +Full documentation about i18n tooling can be {blob}6.7/src/dev/i18n/README.md[found here]. + +[float] +==== Extracting default messages +To extract the default messages from your plugin run the following command: + +["source","shell"] +----------- +node ../../kibana/scripts/i18n_extract --include-config ./.i18nrc.json --output-dir ./translations +node scripts/i18n_extract --output-dir ./translations --include-config ../kibana-extra/myPlugin/.i18nrc.json +----------- + +This will output a `en.json` file inside the `translations` directory. To localize other languages, clone the file and translate each string. + +[float] +==== Checking i18n messages + +Checking i18n does the following: +- Check all existing labels for violations +- Take translations from .i18nrc.json and compare them to the messages extracted and validated at the step above and: + - Check for unused translations - if developer removed a label which has corresponding translation they will need to remove this label from translations file as well, semi-automatic for now (see below) + - Check for incompatible translations - if developer, let's say removed or added new parameter to an existing string, they will need to remove this label from 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 +----------- + + +[float] +==== Implementing i18n in UI + +Kibana relies on several UI frameworks (ReactJS and AngularJS) and +requires localization in different environments (browser and NodeJS). +Internationalization engine is framework agnostic and consumable in +all parts of Kibana (ReactJS, AngularJS and NodeJS). In order to simplify +internationalization in UI frameworks, the 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. + + +[float] +==== 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 can be {repo}tree/6.7/packages/kbn-i18n#vanilla-js[found here]. + +[float] +==== 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 ( +
+ {i18n.translate('xpack.someText', { defaultMessage: 'Some text' })} + + +
+ ); +}; +----------- + +Full details can be {repo}tree/6.7/packages/kbn-i18n#react[found here]. + + + +[float] +==== i18n for Angular + +To localize strings in React, use either `FormattedMessage` or `i18n.translate`. + + +The translation directive has the following syntax: +["source","js"] +----------- + +----------- + +Full details can be {repo}tree/6.7/packages/kbn-i18n#angularjs[found here]. + + +[float] +==== Resources + +To Learn more i18n tooling, see {blob}6.7/src/dev/i18n/README.md[i18n dev tooling]. + +To Learn more about implementing i18n in UI, follow the links below: +* {blob}6.7/packages/kbn-i18n/README.md[i18n plugin] +* {blob}6.7/packages/kbn-i18n/GUIDELINE.md[i18n Guidelines] From 1a05b2c44893de30882a904132c2eea3350f7d35 Mon Sep 17 00:00:00 2001 From: Bamieh Date: Tue, 26 Mar 2019 16:24:32 +0300 Subject: [PATCH 5/9] fix command --- docs/development/plugin/development-plugin-localization.asciidoc | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/development/plugin/development-plugin-localization.asciidoc b/docs/development/plugin/development-plugin-localization.asciidoc index 65f7e0e35d56a..ea37b797b2d7e 100644 --- a/docs/development/plugin/development-plugin-localization.asciidoc +++ b/docs/development/plugin/development-plugin-localization.asciidoc @@ -54,7 +54,6 @@ To extract the default messages from your plugin run the following command: ["source","shell"] ----------- -node ../../kibana/scripts/i18n_extract --include-config ./.i18nrc.json --output-dir ./translations node scripts/i18n_extract --output-dir ./translations --include-config ../kibana-extra/myPlugin/.i18nrc.json ----------- From e9f3629c4bef132ff67fb32d795b17ac75deb384 Mon Sep 17 00:00:00 2001 From: gchaps <33642766+gchaps@users.noreply.github.com> Date: Wed, 27 Mar 2019 16:57:30 +0300 Subject: [PATCH 6/9] Apply suggestions from code review Gail review Co-Authored-By: Bamieh --- .../development-plugin-localization.asciidoc | 56 +++++++++---------- docs/settings/i18n-settings.asciidoc | 2 +- docs/setup/settings.asciidoc | 2 +- 3 files changed, 30 insertions(+), 30 deletions(-) diff --git a/docs/development/plugin/development-plugin-localization.asciidoc b/docs/development/plugin/development-plugin-localization.asciidoc index ea37b797b2d7e..db79494e09972 100644 --- a/docs/development/plugin/development-plugin-localization.asciidoc +++ b/docs/development/plugin/development-plugin-localization.asciidoc @@ -1,13 +1,13 @@ [[development-plugin-localization]] -=== Localization for Plugins +=== Localization for plugins -To introduce localization for your plugin. Use our i18n tool to create Ids and default messages. Then extract those Ids into localization json files to be used by kibana when running your plugin. +To introduce localization for your plugin, use our i18n tool to create IDs and default messages. You can then extract these IDs into localization JSON files for Kibana to use when running your plugin. The following guide will help you setup localization for your plugin. [float] -==== Adding localizations to your plugin +==== Adding localization to your plugin -To create translations add a `translations` directory at the root of your plugin. This folder will include the translations files which will be automatically parsed and used by kibana. +You must add a `translations` directory at the root of your plugin. This directory will contain the translation files that Kibana uses. ["source","shell"] ----------- @@ -20,15 +20,15 @@ To create translations add a `translations` directory at the root of your plugin [float] -==== Using kibana i18n tooling -In order to simplify localization process, some additional tools were implemented: -- tool for verifying all translations have translatable strings and extracting default messages from templates -- tool for verifying translation files and integrating them to Kibana +==== Using Kibana i18n tooling +To simplify the localization process, Kibana 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 Kibana -To use kibana i18n tooling, create a `.i18nrc.json` file providing the following configs: -* `paths` directory paths where i18n translation ids are to be extracted from -* `exclude` list of files to exclude while parsing paths -* `translations` list of translations where json localizations are to be found. +To use Kibana 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"] ----------- @@ -44,29 +44,29 @@ To use kibana i18n tooling, create a `.i18nrc.json` file providing the following } ----------- -A full example for kibana `.i18nrc.json` can be {blob}6.7/.i18nrc.json[found here]. +An example Kibana `.i18nrc.json` is {blob}6.7/.i18nrc.json[here]. -Full documentation about i18n tooling can be {blob}6.7/src/dev/i18n/README.md[found here]. +Full documentation about i18n tooling is {blob}6.7/src/dev/i18n/README.md[here]. [float] ==== Extracting default messages -To extract the default messages from your plugin run the following command: +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 will output a `en.json` file inside the `translations` directory. To localize other languages, clone the file and translate each string. +This outputs a `en.json` file inside the `translations` directory. To localize other languages, clone the file and translate each string. [float] ==== Checking i18n messages Checking i18n does the following: -- Check all existing labels for violations -- Take translations from .i18nrc.json and compare them to the messages extracted and validated at the step above and: - - Check for unused translations - if developer removed a label which has corresponding translation they will need to remove this label from translations file as well, semi-automatic for now (see below) - - Check for incompatible translations - if developer, let's say removed or added new parameter to an existing string, they will need to remove this label from translations file. +- Checks all existing labels for violations. +- Takes translations from .i18nrc.json and compares them to the messages extracted and validated at the step above and: + - 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: @@ -81,9 +81,9 @@ node scripts/i18n_check --fix --include-config ../kibana-extra/myPlugin/.i18nrc. Kibana relies on several UI frameworks (ReactJS and AngularJS) and requires localization in different environments (browser and NodeJS). -Internationalization engine is framework agnostic and consumable in +The internationalization engine is framework agnostic and consumable in all parts of Kibana (ReactJS, AngularJS and NodeJS). In order to simplify -internationalization in UI frameworks, the additional abstractions are +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], @@ -92,7 +92,7 @@ message syntax. [float] -==== i18n for Vanilla Javascript +==== i18n for vanilla JavaScript ["source","js"] ----------- @@ -103,7 +103,7 @@ export const HELLO_WORLD = i18n.translate('hello.wonderful.world', { }); ----------- -Full details can be {repo}tree/6.7/packages/kbn-i18n#vanilla-js[found here]. +Full details are {repo}tree/6.7/packages/kbn-i18n#vanilla-js[here]. [float] ==== i18n for React @@ -127,7 +127,7 @@ export const Component = () => { }; ----------- -Full details can be {repo}tree/6.7/packages/kbn-i18n#react[found here]. +Full details are {repo}tree/6.7/packages/kbn-i18n#react[here]. @@ -148,14 +148,14 @@ The translation directive has the following syntax: > ----------- -Full details can be {repo}tree/6.7/packages/kbn-i18n#angularjs[found here]. +Full details are {repo}tree/6.7/packages/kbn-i18n#angularjs[here]. [float] ==== Resources -To Learn more i18n tooling, see {blob}6.7/src/dev/i18n/README.md[i18n dev tooling]. +To learn more about i18n tooling, see {blob}6.7/src/dev/i18n/README.md[i18n dev tooling]. -To Learn more about implementing i18n in UI, follow the links below: +To learn more about implementing i18n in the UI, follow the links below: * {blob}6.7/packages/kbn-i18n/README.md[i18n plugin] * {blob}6.7/packages/kbn-i18n/GUIDELINE.md[i18n Guidelines] diff --git a/docs/settings/i18n-settings.asciidoc b/docs/settings/i18n-settings.asciidoc index 8c7f65c796d3d..f3cf6e8a97378 100644 --- a/docs/settings/i18n-settings.asciidoc +++ b/docs/settings/i18n-settings.asciidoc @@ -5,7 +5,7 @@ i18n Settings ++++ -You do not need to configure any settings to have kibana in English. +You do not need to configure any settings to run Kibana in English. [float] [[general-i18n-settings-kb]] diff --git a/docs/setup/settings.asciidoc b/docs/setup/settings.asciidoc index 7a4fdf157bf81..a0496825dd6a5 100644 --- a/docs/setup/settings.asciidoc +++ b/docs/setup/settings.asciidoc @@ -236,4 +236,4 @@ unauthenticated users to access the Kibana server status API and status page. `license_management.enabled`:: *Default: true* Set this value to false to disable the License Management user interface. -`i18n.locale`:: *Default: en* Set this value to change Kibana interface language. Valid locales are: `en`, `zh-CN`. \ No newline at end of file +`i18n.locale`:: *Default: en* Set this value to change the Kibana interface language. Valid locales are: `en`, `zh-CN`. From 4b31a549ec9ee94f10be32c5d4353d528cbbcee7 Mon Sep 17 00:00:00 2001 From: Bamieh Date: Sun, 31 Mar 2019 15:55:22 +0300 Subject: [PATCH 7/9] fixes from code review --- .../development-plugin-localization.asciidoc | 31 ++++++++++--------- 1 file changed, 17 insertions(+), 14 deletions(-) diff --git a/docs/development/plugin/development-plugin-localization.asciidoc b/docs/development/plugin/development-plugin-localization.asciidoc index db79494e09972..2239b7f298ed1 100644 --- a/docs/development/plugin/development-plugin-localization.asciidoc +++ b/docs/development/plugin/development-plugin-localization.asciidoc @@ -1,8 +1,7 @@ [[development-plugin-localization]] === Localization for plugins -To introduce localization for your plugin, use our i18n tool to create IDs and default messages. You can then extract these IDs into localization JSON files for Kibana to use when running your plugin. -The following guide will help you setup localization for your plugin. +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. [float] ==== Adding localization to your plugin @@ -22,10 +21,12 @@ You must add a `translations` directory at the root of your plugin. This directo [float] ==== Using Kibana i18n tooling To simplify the localization process, Kibana 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 Kibana + +* Verify all translations have translatable strings and extract default messages from templates +* Verify translation files and integrate them into Kibana To use Kibana 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. @@ -44,9 +45,9 @@ To use Kibana i18n tooling, create a `.i18nrc.json` file with the following conf } ----------- -An example Kibana `.i18nrc.json` is {blob}6.7/.i18nrc.json[here]. +An example Kibana `.i18nrc.json` is {blob}.i18nrc.json[here]. -Full documentation about i18n tooling is {blob}6.7/src/dev/i18n/README.md[here]. +Full documentation about i18n tooling is {blob}src/dev/i18n/README.md[here]. [float] ==== Extracting default messages @@ -63,10 +64,11 @@ This outputs a `en.json` file inside the `translations` directory. To localize o ==== 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 at the step above and: - - 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. + +* Checks all existing labels for violations. +* Takes translations from .i18nrc.json and compares them to the messages extracted and validated at the step above and: + * 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: @@ -134,7 +136,7 @@ Full details are {repo}tree/6.7/packages/kbn-i18n#react[here]. [float] ==== i18n for Angular -To localize strings in React, use either `FormattedMessage` or `i18n.translate`. +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. The translation directive has the following syntax: @@ -154,8 +156,9 @@ Full details are {repo}tree/6.7/packages/kbn-i18n#angularjs[here]. [float] ==== Resources -To learn more about i18n tooling, see {blob}6.7/src/dev/i18n/README.md[i18n dev tooling]. +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, follow the links below: -* {blob}6.7/packages/kbn-i18n/README.md[i18n plugin] -* {blob}6.7/packages/kbn-i18n/GUIDELINE.md[i18n Guidelines] + +* {blob}packages/kbn-i18n/README.md[i18n plugin] +* {blob}packages/kbn-i18n/GUIDELINE.md[i18n Guidelines] From a5a7f0f33ad354a85fe63e6867d9cab74d9d6b3c Mon Sep 17 00:00:00 2001 From: gchaps <33642766+gchaps@users.noreply.github.com> Date: Wed, 3 Apr 2019 19:55:43 +0530 Subject: [PATCH 8/9] Update docs/development/plugin/development-plugin-localization.asciidoc Co-Authored-By: Bamieh --- .../development/plugin/development-plugin-localization.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/development/plugin/development-plugin-localization.asciidoc b/docs/development/plugin/development-plugin-localization.asciidoc index 2239b7f298ed1..eb192e0044872 100644 --- a/docs/development/plugin/development-plugin-localization.asciidoc +++ b/docs/development/plugin/development-plugin-localization.asciidoc @@ -134,7 +134,7 @@ Full details are {repo}tree/6.7/packages/kbn-i18n#react[here]. [float] -==== i18n for Angular +===== i18n for Angular 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. From 4e32345b536271df9e90f86246ef5d7ec0b7091a Mon Sep 17 00:00:00 2001 From: Ahmad Bamieh Date: Wed, 3 Apr 2019 19:57:14 +0530 Subject: [PATCH 9/9] Apply suggestions from code review Co-Authored-By: Bamieh --- .../plugin/development-plugin-localization.asciidoc | 8 ++++---- docs/settings/i18n-settings.asciidoc | 3 --- 2 files changed, 4 insertions(+), 7 deletions(-) diff --git a/docs/development/plugin/development-plugin-localization.asciidoc b/docs/development/plugin/development-plugin-localization.asciidoc index eb192e0044872..ff5f5c3f59ded 100644 --- a/docs/development/plugin/development-plugin-localization.asciidoc +++ b/docs/development/plugin/development-plugin-localization.asciidoc @@ -67,7 +67,7 @@ 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 at the step above and: - * 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 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: @@ -79,7 +79,7 @@ node scripts/i18n_check --fix --include-config ../kibana-extra/myPlugin/.i18nrc. [float] -==== Implementing i18n in UI +==== Implementing i18n in the UI Kibana relies on several UI frameworks (ReactJS and AngularJS) and requires localization in different environments (browser and NodeJS). @@ -94,7 +94,7 @@ message syntax. [float] -==== i18n for vanilla JavaScript +===== i18n for vanilla JavaScript ["source","js"] ----------- @@ -108,7 +108,7 @@ export const HELLO_WORLD = i18n.translate('hello.wonderful.world', { Full details are {repo}tree/6.7/packages/kbn-i18n#vanilla-js[here]. [float] -==== i18n for React +===== i18n for React To localize strings in React, use either `FormattedMessage` or `i18n.translate`. diff --git a/docs/settings/i18n-settings.asciidoc b/docs/settings/i18n-settings.asciidoc index f3cf6e8a97378..618ee36e5714e 100644 --- a/docs/settings/i18n-settings.asciidoc +++ b/docs/settings/i18n-settings.asciidoc @@ -1,9 +1,6 @@ [role="xpack"] [[i18n-settings-kb]] === i18n settings in Kibana -++++ -i18n Settings -++++ You do not need to configure any settings to run Kibana in English.