Skip to content

Commit

Permalink
[i18n] remove angular i18n and move the remains to monitoring plugin (e…
Browse files Browse the repository at this point in the history
…lastic#115003) (elastic#115156)

Co-authored-by: Ahmad Bamieh <ahmadbamieh@gmail.com>
  • Loading branch information
kibanamachine and Bamieh authored Oct 18, 2021
1 parent 0300daf commit 289ab75
Show file tree
Hide file tree
Showing 20 changed files with 23 additions and 538 deletions.
21 changes: 0 additions & 21 deletions docs/developer/plugin/external-plugin-localization.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -135,27 +135,6 @@ export const Component = () => {

Full details are {kib-repo}tree/master/packages/kbn-i18n#react[here].



[discrete]
==== 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].


[discrete]
=== Resources

Expand Down
2 changes: 0 additions & 2 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -496,7 +496,6 @@
"@testing-library/react-hooks": "^5.1.1",
"@testing-library/user-event": "^13.1.1",
"@types/angular": "^1.6.56",
"@types/angular-mocks": "^1.7.0",
"@types/apidoc": "^0.22.3",
"@types/archiver": "^5.1.0",
"@types/babel__core": "^7.1.16",
Expand Down Expand Up @@ -651,7 +650,6 @@
"@yarnpkg/lockfile": "^1.1.0",
"abab": "^2.0.4",
"aggregate-error": "^3.1.0",
"angular-mocks": "^1.7.9",
"antlr4ts-cli": "^0.5.0-alpha.3",
"apidoc": "^0.29.0",
"apidoc-markdown": "^6.0.0",
Expand Down
2 changes: 0 additions & 2 deletions packages/kbn-i18n/BUILD.bazel
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,6 @@ filegroup(
)

NPM_MODULE_EXTRA_FILES = [
"angular/package.json",
"react/package.json",
"package.json",
"GUIDELINE.md",
Expand All @@ -47,7 +46,6 @@ TYPES_DEPS = [
"//packages/kbn-babel-preset",
"@npm//intl-messageformat",
"@npm//tslib",
"@npm//@types/angular",
"@npm//@types/intl-relativeformat",
"@npm//@types/jest",
"@npm//@types/node",
Expand Down
57 changes: 11 additions & 46 deletions packages/kbn-i18n/GUIDELINE.md
Original file line number Diff line number Diff line change
Expand Up @@ -93,17 +93,6 @@ The long term plan is to rely on using `FormattedMessage` and `i18n.translate()`
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

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.**

- 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

- Use `i18n.translate()` in NodeJS or any other framework agnostic code, where `i18n` is the I18n engine from `@kbn/i18n` package.
Expand Down Expand Up @@ -223,7 +212,6 @@ For example:
- for button:

```js

<EuiButton data-test-subj="addScriptedFieldLink" href={addScriptedFieldUrl}>
<FormattedMessage id="kbn.management.editIndexPattern.scripted.addFieldButtonLabel" defaultMessage="Add scripted field"/>
</EuiButton>
Expand All @@ -232,11 +220,11 @@ For example:
- for dropDown:

```js
<select ng-model="indexedFieldTypeFilter" ng-options="o for o in indexedFieldTypes">
<option value=""
i18n-id="kbn.management.editIndexPattern.fields.allTypesDropDown"
i18n-default-message="All field types"></option>
</select>
<option value={
i18n.translate('kbn.management.editIndexPattern.fields.allTypesDropDown', {
defaultMessage: 'All field types',
})
}
```

- for placeholder:
Expand Down Expand Up @@ -309,12 +297,6 @@ For example:

- Variables

```html
<span i18n-id="kbn.management.editIndexPattern.timeFilterHeader"
i18n-default-message="Time Filter field name: {timeFieldName}"
i18n-values="{ timeFieldName: indexPattern.timeFieldName }"></span>
```

```html
<FormattedMessage
id="kbn.management.createIndexPatternHeader"
Expand All @@ -327,25 +309,6 @@ For example:

- Labels and variables in tag

```html
<span i18n-id="kbn.management.editIndexPattern.timeFilterLabel.timeFilterDetail"
i18n-default-message="This page lists every field in the {indexPatternTitle} index"
i18n-values="{ indexPatternTitle: '<strong>' + indexPattern.title + '</strong>' }"></span>
```

-----------------------------------------------------------
**BUT** we can not use tags that should be compiled:

```html
<span i18n-id="kbn.management.editIndexPattern.timeFilterLabel.timeFilterDetail"
i18n-default-message="This page lists every field in the {indexPatternTitle} index"
i18n-values="{ indexPatternTitle: '<div my-directive>' + indexPattern.title + '</div>' }"></span>
```

To void injections vulnerability, `i18nId` directive doesn't compile its values.

-----------------------------------------------------------

```html
<FormattedMessage
id="kbn.management.createIndexPattern.step.indexPattern.disallowLabel"
Expand Down Expand Up @@ -388,10 +351,12 @@ The numeric input is mapped to a plural category, some subset of "zero", "one",

Here is an example of message translation depending on a plural category:

```html
<span i18n-id="kbn.management.editIndexPattern.mappingConflictLabel"
i18n-default-message="{conflictFieldsLength, plural, one {A field is} other {# fields are}} defined as several types (string, integer, etc) across the indices that match this pattern."
i18n-values="{ conflictFieldsLength: conflictFields.length }"></span>
```jsx
<FormattedMessage
id="kbn.management.editIndexPattern.mappingConflictLabel"
defaultMessage="{conflictFieldsLength, plural, one {A field is} other {# fields are}} defined as several types (string, integer, etc) across the indices that match this pattern."
values={{ conflictFieldsLength: conflictFields.length }}
/>
```

When `conflictFieldsLength` equals 1, the result string will be `"A field is defined as several types (string, integer, etc) across the indices that match this pattern."`. In cases when `conflictFieldsLength` has value of 2 or more, the result string - `"2 fields are defined as several types (string, integer, etc) across the indices that match this pattern."`.
Expand Down
92 changes: 0 additions & 92 deletions packages/kbn-i18n/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -343,98 +343,6 @@ 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.

The translation `provider` is used for `service` configuration and
has the following methods:
- `addMessages(messages: Map<string, string>, [locale: string])` - provides a way to register
translations with the library
- `setLocale(locale: string)` - tells the library which language to use by given
language key
- `getLocale()` - returns the current locale
- `setDefaultLocale(locale: string)` - tells the library which language to fallback
when missing translations
- `getDefaultLocale()` - returns the default locale
- `setFormats(formats: object)` - supplies a set of options to the underlying formatter
- `getFormats()` - returns current formats
- `getRegisteredLocales()` - returns array of locales having translations
- `init(messages: Map<string, string>)` - initializes the engine

The translation `service` provides only one method:
- `i18n(id: string, { values: object, defaultMessage: string, description: string })`
translate message by id

The translation `filter` is used for attributes translation and has
the following syntax:
```
{{ ::'translationId' | i18n: { values: object, defaultMessage: string, description: string } }}
```

Where:
- `translationId` - translation id to be translated
- `values` - values to pass into translation
- `defaultMessage` - will be used unless translation was successful (the final
fallback in english, will be used for generating `en.json`)
- `description` - optional context comment that will be extracted by i18n tools
and added as a comment next to translation message at `defaultMessages.json`

The translation `directive` has the following syntax:
```html
<ANY
i18n-id="{string}"
i18n-default-message="{string}"
[i18n-values="{object}"]
[i18n-description="{string}"]
></ANY>
```

Where:
- `i18n-id` - translation id to be translated
- `i18n-default-message` - will be used unless translation was successful
- `i18n-values` - values to pass into translation
- `i18n-description` - optional context comment that will be extracted by i18n tools
and added as a comment next to translation message at `defaultMessages.json`

If HTML rendering in `i18n-values` is required then value key in `i18n-values` object
should have `html_` prefix. Otherwise the value will be inserted to the message without
HTML rendering.\
Example:
```html
<p
i18n-id="namespace.id"
i18n-default-message="Text with an emphasized {text}."
i18n-values="{
html_text: '<em>text</em>',
}"
></p>
```

Angular `I18n` module is placed into `autoload` module, so it will be
loaded automatically. After that we can use i18n directive in Angular templates:
```html
<span
i18n-id="welcome"
i18n-default-message="Hello!"
></span>
```

In order to translate attributes in AngularJS we should use `i18nFilter`:
```html
<input
type="text"
placeholder="{{ ::'kbn.management.objects.searchAriaLabel' | i18n: {
defaultMessage: 'Search { title } Object',
values: { title }
} }}"
>
```

## I18n tools

In order to simplify localization process, some additional tools were implemented:
Expand Down
5 changes: 0 additions & 5 deletions packages/kbn-i18n/angular/package.json

This file was deleted.

69 changes: 0 additions & 69 deletions packages/kbn-i18n/src/angular/__snapshots__/directive.test.ts.snap

This file was deleted.

Loading

0 comments on commit 289ab75

Please sign in to comment.