From 55e36a04aabd98c14e8149df2357f659ac14558b Mon Sep 17 00:00:00 2001 From: Ahmad Bamieh Date: Tue, 4 Jun 2019 15:01:11 +0300 Subject: [PATCH] [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> --- .../development-plugin-localization.asciidoc | 9 ++++----- packages/kbn-i18n/GUIDELINE.md | 20 ++++++++++++------- packages/kbn-i18n/README.md | 4 ++++ 3 files changed, 21 insertions(+), 12 deletions(-) diff --git a/docs/development/plugin/development-plugin-localization.asciidoc b/docs/development/plugin/development-plugin-localization.asciidoc index 4d196c8aaba1..ff497ec40e30 100644 --- a/docs/development/plugin/development-plugin-localization.asciidoc +++ b/docs/development/plugin/development-plugin-localization.asciidoc @@ -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: > ----------- -Full details are {repo}tree/6.7/packages/kbn-i18n#angularjs[here]. +Full details are {repo}tree/master/packages/kbn-i18n#angularjs[here]. [float] diff --git a/packages/kbn-i18n/GUIDELINE.md b/packages/kbn-i18n/GUIDELINE.md index e33af4b7c35f..45408dc6582b 100644 --- a/packages/kbn-i18n/GUIDELINE.md +++ b/packages/kbn-i18n/GUIDELINE.md @@ -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 `` 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 diff --git a/packages/kbn-i18n/README.md b/packages/kbn-i18n/README.md index c4f9f05837a5..04456bf630e9 100644 --- a/packages/kbn-i18n/README.md +++ b/packages/kbn-i18n/README.md @@ -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.