# I18n Guideline ## All Localizers need to know ### Message types The message ids chosen for message keys are descriptive of the string, and its role in the interface (button, label, header, etc.). Each message id ends with a descriptive type. Types are defined at the end of message id by combining to the last segment using camel case. Ids should end with: - Description (in most cases if it's `

` tag), - Title (if it's `

`, `

`, etc. tags), - Label (if it's `` tag), - ButtonLabel (if it's ` ``` - for errorMessage: ```js errors.push( intl.formatMessage( { id: 'kbn.management.createIndexPattern.step.invalidCharactersErrorMessage', defaultMessage: 'An index pattern cannot contain spaces or the characters: {characterList}' }, { characterList } )); ``` - for toggleSwitch ```js } /> ``` ### Variety of `values` - Variables ```html ``` ```html ``` - Labels and variables in tag ```html ``` ----------------------------------------------------------- BUT we can not use tags that should be compiled: ```html ``` To void injections vulnerability, `i18nId` directive doesn't compile its values. ----------------------------------------------------------- ```html {characterList} }} /> ``` ```html ), }} /> ``` - Non-translatable text such as property name. ```html ``` ### Text with plurals The numeric input is mapped to a plural category, some subset of "zero", "one", "two", "few", "many", and "other" depending on the locale and the type of plural. There are languages with multiple plural forms [Language Plural Rules](http://www.unicode.org/cldr/charts/latest/supplemental/language_plural_rules.html). Here is an example of message translation depending on a plural category: ```html ``` 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."`. ### Splitting Splitting sentences into several keys often inadvertently presumes a grammar, a sentence structure, and such composite strings are often very difficult to translate. - Do not divide a single sentence into different labels unless you have absolutely no other choice. - Do not divide sentences that belong together into separate labels. For example: `The following dialogue box indicates progress. You can close it and the process will continue to run in the background.` If this group of sentences is separated it’s possible that the context of the `'it'` in `'close it'` will be lost. ### Unit tests #### How to test `FormattedMessage` and `i18n.translate()` components. To make `FormattedMessage` component work properly, wrapping it with `I18nProvider` is required. In development/production app, this is done in the ancestor components and developers don't have to worry about that. But when unit-testing them, no other component provides that wrapping. That's why `shallowWithI18nProvider` and `mountWithI18nProvider` helpers are created. For example, there is a component that has `FormattedMessage` inside, like `SaveModal` component: ```js // ... export const SaveModal = (props) => { return (
{/* Other things. /} {/ More other things. /}
) } ``` To test `SaveModal` component, it should be wrapped with `I18nProvider` by using `shallowWithI18nProvider`: ```js // ... it('should render normally', async () => { const component = shallowWithI18nProvider( ); expect(component).toMatchSnapshot(); }); // ... ``` If a component uses only `i18n.translate()`, it doesn't need `I18nProvider`. In that case, you can test them with `shallow` and `mount` functions that `enzyme` providers out of the box. #### How to test `injectI18n` HOC components. Testing React component that uses the `injectI18n` higher-order component is more complicated because `injectI18n()` creates a wrapper component around the original component. With shallow rendering only top level component is rendered, that is a wrapper itself, not the original component. Since we want to test the rendering of the original component, we need to access it via the wrapper's `WrappedComponent` property. Its value will be the component we passed into `injectI18n()`. When testing such component, use the `shallowWithIntl` helper function defined in `@kbn/test/jest` and pass the component's `WrappedComponent` property to render the wrapped component. This will shallow render the component with Enzyme and inject the necessary context and props to use the `intl` mock defined in `test_utils/mocks/intl`. Use the `mountWithIntl` helper function to mount render the component. For example, there is a component that is wrapped by `injectI18n`, like in the `AddFilter` component: ```js // ... export const AddFilter = injectI18n( class AddFilterUi extends Component { // ... render() { const { filter } = this.state; return ( this.setState({ filter: e.target.value.trim() })} placeholder={this.props.intl.formatMessage({ id: 'kbn.management.indexPattern.edit.source.placeholder', defaultMessage: 'source filter, accepts wildcards (e.g., `user` to filter fields starting with \'user\')' })} /> ); } } ); ``` To test the `AddFilter` component it is needed to render its `WrappedComponent` property using `shallowWithIntl` function to pass `intl` object into the `props`. ```js // ... it('should render normally', async () => { const component = shallowWithIntl( {}}/> ); expect(component).toMatchSnapshot(); }); // ... ``` ## Development steps 1. Localize label with the suitable i18n component. 2. Make sure that UI still looks correct and is functioning properly (e.g. click handler is processed, checkbox is checked/unchecked, etc.). 3. Check functionality of an element (button is clicked, checkbox is checked/unchecked, etc.). 4. Run i18n validation/extraction tools and skim through created `en.json`: ```bash $ node scripts/i18n_check --ignore-missing $ node scripts/i18n_extract --output-dir ./ ``` 5. Run linters and type checker as you normally do. 6. Run tests. 7. Run Kibana with enabled pseudo-locale (either pass `--i18n.locale=en-xa` as a command-line argument or add it to the `kibana.yml`) and observe the text you've just localized. If you did everything correctly, it should turn into something like this `Ĥéļļļô ŴŴôŕļļð!` assuming your text was `Hello World!`. 8. Check that CI is green.