Document scripts/i18n_check. (#32209)

CONTRIBUTING.md

@@ -21,6 +21,7 @@ A high level overview of our contributing guidelines.
     - [Customizing `config/kibana.dev.yml`](#customizing-configkibanadevyml)
     - [Setting Up SSL](#setting-up-ssl)
   - [Linting](#linting)
+  - [Internationalization](#internationalization)
   - [Testing and Building](#testing-and-building)
   - [Debugging Unit Tests](#debugging-unit-tests)
   - [Unit Testing Plugins](#unit-testing-plugins)
@@ -249,6 +250,25 @@ IntelliJ   | Settings » Languages & Frameworks » JavaScript » Code Quality To
 
 Another tool we use for enforcing consistent coding style is EditorConfig, which can be set up by installing a plugin in your editor that dynamically updates its configuration. Take a look at the [EditorConfig](http://editorconfig.org/#download) site to find a plugin for your editor, and browse our [`.editorconfig`](https://github.com/elastic/kibana/blob/master/.editorconfig) file to see what config rules we set up.
 
+### Internationalization
+
+All user-facing labels and info texts in Kibana should be internationalized. Please take a look at the [readme](packages/kbn-i18n/README.md) and the [guideline](packages/kbn-i18n/GUIDELINE.md) of the i18n package on how to do so.
+
+In order to enable translations in the React parts of the application, the top most component of every `ReactDOM.render` call should be an `I18nContext`:
+```jsx
+import { I18nContext } from 'ui/i18n';
+
+ReactDOM.render(
+  <I18nContext>
+      {myComponentTree}
+  </I18nContext>,
+  container
+);
+```
+
+There is a number of tools was created to support internationalization in Kibana that would allow one to validate internationalized labels, 
+extract them to a `JSON` file or integrate translations back to Kibana. To know more, please read corresponding [readme](src/dev/i18n/README.md) file.
+
 ### Testing and Building
 
 To ensure that your changes will not break other functionality, please run the test suite and build process before submitting your Pull Request.

src/dev/i18n/README.md

@@ -203,3 +203,36 @@ integrating translations to has changed and some translations are not needed any
 ### Output
 
 Unless `--target` is specified, the tool generates locale files in plugin folders and few other special locations based on namespaces and corresponding mappings defined in [.i18nrc.json](../../../.i18nrc.json).
+
+
+## Validation tool
+
+### Description
+
+The tool performs a number of checks on internationalized labels and verifies whether they don't conflict with the existing translations.
+
+### Notes
+
+We don't catch every possible misuse of i18n framework, but only the most common and critical ones.
+
+To perform translations compatibility checks tool relies on existing translations referenced in `translations` section of [.i18nrc.json](../../../.i18nrc.json).
+
+Currently auto-fixer (`--fix`) can only automatically fix two types of errors, and for both of them the fix is just removing of conflicting translation entries from JSON files:
+
+* incompatible translation - this error means that the value references in internationalized label differ from the ones
+in the existing translation
+
+* unused translation - this error means that the translations file includes label that doesn't exist anymore.
+
+### Usage
+
+```bash
+node scripts/i18n_check --fix
+```
+
+* `--fix` tells the tool to try to fix as much violations as possible. All errors that tool won't be able to fix will be reported.
+* `--ignore-incompatible` specifies whether tool should ignore incompatible translations.
+* `--ignore-missing` specifies whether tool should ignore missing translations.
+* `--ignore-unused` specifies whether tool should ignore unused translations.
+* `--include-config` specifies additional paths to `.i18nrc.json` files (may be useful for 3rd-party plugins)
+