[i18n] [docs] Update docs to encourage static i18n import (#37858)
* update documentation * Update docs/development/plugin/development-plugin-localization.asciidoc Co-Authored-By: gchaps <33642766+gchaps@users.noreply.github.com> * Update packages/kbn-i18n/GUIDELINE.md Co-Authored-By: gchaps <33642766+gchaps@users.noreply.github.com> * Update packages/kbn-i18n/GUIDELINE.md Co-Authored-By: gchaps <33642766+gchaps@users.noreply.github.com> * Update packages/kbn-i18n/GUIDELINE.md Co-Authored-By: gchaps <33642766+gchaps@users.noreply.github.com> * Update packages/kbn-i18n/GUIDELINE.md Co-Authored-By: gchaps <33642766+gchaps@users.noreply.github.com> * Update packages/kbn-i18n/GUIDELINE.md Co-Authored-By: gchaps <33642766+gchaps@users.noreply.github.com> * Update packages/kbn-i18n/GUIDELINE.md * Update packages/kbn-i18n/GUIDELINE.md Co-Authored-By: gchaps <33642766+gchaps@users.noreply.github.com> * Update packages/kbn-i18n/README.md Co-Authored-By: gchaps <33642766+gchaps@users.noreply.github.com> * Update packages/kbn-i18n/README.md Co-Authored-By: gchaps <33642766+gchaps@users.noreply.github.com>
This commit is contained in:
Ahmad Bamieh
GitHub
parent
54af64d416
commit
55e36a04aa
|
|
@ -109,7 +109,7 @@ export const HELLO_WORLD = i18n.translate('hello.wonderful.world', {
|
|||
});
|
||||
-----------
|
||||
|
||||
Full details are {repo}tree/6.7/packages/kbn-i18n#vanilla-js[here].
|
||||
Full details are {repo}tree/master/packages/kbn-i18n#vanilla-js[here].
|
||||
|
||||
[float]
|
||||
===== i18n for React
|
||||
|
|
@ -133,15 +133,14 @@ export const Component = () => {
|
|||
};
|
||||
-----------
|
||||
|
||||
Full details are {repo}tree/6.7/packages/kbn-i18n#react[here].
|
||||
Full details are {repo}tree/master/packages/kbn-i18n#react[here].
|
||||
|
||||
|
||||
|
||||
[float]
|
||||
===== 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.
|
||||
|
||||
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"]
|
||||
|
|
@ -154,7 +153,7 @@ The translation directive has the following syntax:
|
|||
></ANY>
|
||||
-----------
|
||||
|
||||
Full details are {repo}tree/6.7/packages/kbn-i18n#angularjs[here].
|
||||
Full details are {repo}tree/master/packages/kbn-i18n#angularjs[here].
|
||||
|
||||
|
||||
[float]
|
||||
|
|
|
|||
|
|
@ -84,18 +84,24 @@ In case when `indicesLength` has value 1, the result string will be "`1 index`".
|
|||
|
||||
#### In ReactJS
|
||||
|
||||
The long term plan is to rely on using `FormattedMessage` and `i18n.translate()` by statically importing `i18n` from the `@kbn/i18n` package. **Avoid using `injectI18n` and use `i18n.translate()` instead.**
|
||||
|
||||
- You should use `<FormattedMessage>` most of the time.
|
||||
- In case when the string is expected (`aria-label`, `placeholder`), use `props.intl.formatmessage()` (where `intl` is passed to `props` by `injectI18n` HOC).
|
||||
- In case if none of the above can not be applied (e.g. it's needed to translate any code that doesn't have access to the component props), you can call JS function `i18n.translate()` from `@kbn/i18n` package.
|
||||
- In the case where the string is expected (`aria-label`, `placeholder`), Call JS function `i18n.translate()` from the`@kbn/i18n` package.
|
||||
|
||||
Currently, we support the following ReactJS `i18n` tools, but they will be removed in future releases:
|
||||
- Usage of `props.intl.formatmessage()` (where `intl` is passed to `props` by `injectI18n` HOC).
|
||||
|
||||
#### In AngularJS
|
||||
|
||||
- Use `i18n` service in controllers, directives, services by injected it.
|
||||
- Use `i18nId` directive in template.
|
||||
- Use `i18n` filter in template for attribute translation.
|
||||
- In case if none of the above can not be applied, you can call JS function `i18n.translate()` from `@kbn/i18n` package.
|
||||
The long term plan is to rely on using `i18n.translate()` by statically importing `i18n` from the `@kbn/i18n` package. **Avoid using the `i18n` filter and the `i18n` service injected in controllers, directives, services.**
|
||||
|
||||
Note: Use one-time binding ("{{:: ... }}") in filters wherever it's possible to prevent unnecessary expression re-evaluation.
|
||||
- Call JS function `i18n.translate()` from the `@kbn/i18n` package.
|
||||
- Use `i18nId` directive in template.
|
||||
|
||||
Currently, we support the following AngluarJS `i18n` tools, but they will be removed in future releases:
|
||||
- Usage of `i18n` service in controllers, directives, services by injecting it.
|
||||
- Usage of `i18n` filter in template for attribute translation. Note: Use one-time binding ("{{:: ... }}") in filters wherever it's possible to prevent unnecessary expression re-evaluation.
|
||||
|
||||
#### In JavaScript
|
||||
|
||||
|
|
|
|||
|
|
@ -283,6 +283,8 @@ Initial result: `1 minute ago`
|
|||
|
||||
### Attributes translation in React
|
||||
|
||||
The long term plan is to rely on using `FormattedMessage` and `i18n.translate()` by statically importing `i18n` from the `@kbn/i18n` package. **Avoid using `injectI18n` and rely on `i18n.translate()` instead.**
|
||||
|
||||
React wrapper provides an ability to inject the imperative formatting API into a React component via its props using `injectI18n` Higher-Order Component. This should be used when your React component needs to format data to a string value where a React element is not suitable; e.g., a `title` or `aria` attribute. In order to use it you should wrap your component with `injectI18n` Higher-Order Component. The formatting API will be provided to the wrapped component via `props.intl`.
|
||||
|
||||
React component as a pure function:
|
||||
|
|
@ -342,6 +344,8 @@ export const MyComponent = injectI18n(
|
|||
|
||||
## AngularJS
|
||||
|
||||
The long term plan is to rely on using `i18n.translate()` by statically importing `i18n` from the `@kbn/i18n` package. **Avoid using the `i18n` filter and the `i18n` service injected in controllers, directives, services.**
|
||||
|
||||
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.
|
||||
|
|
|
|||
Loading…
Reference in a new issue