mirror of
https://github.com/elastic/kibana.git
synced 2025-06-27 18:51:07 -04:00
Improvements to our developer guide (#67764)
* contributing guide -> asciidoc * Update docs/developer/contributing/index.asciidoc Co-authored-by: Peter Schretlen <peter.schretlen@gmail.com> * Update CONTRIBUTING.md Co-authored-by: Peter Schretlen <peter.schretlen@gmail.com> * Update docs/developer/best-practices/stability.asciidoc Co-authored-by: Peter Schretlen <peter.schretlen@gmail.com> * Update docs/developer/contributing/index.asciidoc Co-authored-by: Peter Schretlen <peter.schretlen@gmail.com> * address code review comments * Update docs/developer/contributing/development-documentation.asciidoc Co-authored-by: Peter Schretlen <peter.schretlen@gmail.com> * review comment updates * fix bad ref Co-authored-by: Peter Schretlen <peter.schretlen@gmail.com>
This commit is contained in:
Stacey Gammon
GitHub
parent
ddd3a9defd
commit
0a516cfbb9
46 changed files with 1629 additions and 1285 deletions
167
docs/developer/plugin/external-plugin-localization.asciidoc
Normal file
167
docs/developer/plugin/external-plugin-localization.asciidoc
Normal file
|
|
@ -0,0 +1,167 @@
|
|||
[[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.
|
||||
|
||||
[float]
|
||||
==== 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
|
||||
-----------
|
||||
|
||||
|
||||
[float]
|
||||
==== 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].
|
||||
|
||||
[float]
|
||||
==== 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.
|
||||
|
||||
[float]
|
||||
==== 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
|
||||
-----------
|
||||
|
||||
|
||||
[float]
|
||||
==== 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.
|
||||
|
||||
|
||||
[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 are {kib-repo}tree/master/packages/kbn-i18n#vanilla-js[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 (
|
||||
<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].
|
||||
|
||||
|
||||
|
||||
[float]
|
||||
===== i18n for Angular
|
||||
|
||||
You are encouraged to use `i18n.translate()` by statically importing `i18n` from `@kbn/i18n` wherever possible in your Angular code. Angular wrappers use the translation `service` with the i18n engine under the hood.
|
||||
|
||||
The translation directive has the following syntax:
|
||||
["source","js"]
|
||||
-----------
|
||||
<ANY
|
||||
i18n-id="{string}"
|
||||
i18n-default-message="{string}"
|
||||
[i18n-values="{object}"]
|
||||
[i18n-description="{string}"]
|
||||
></ANY>
|
||||
-----------
|
||||
|
||||
Full details are {kib-repo}tree/master/packages/kbn-i18n#angularjs[here].
|
||||
|
||||
|
||||
[float]
|
||||
==== 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]
|
||||
Loading…
Add table
Add a link
Reference in a new issue