From b4bb8f6e49c79e5e4bcf80f535e5023fb52df530 Mon Sep 17 00:00:00 2001
From: Leanid Shutau <leanidshutau@gmail.com>
Date: Wed, 5 Dec 2018 12:01:15 +0300
Subject: [PATCH] [I18n] Update I18n readme (#26631) (#26680)

---
 packages/kbn-i18n/README.md | 51 +++++++------------------------------
 1 file changed, 9 insertions(+), 42 deletions(-)

diff --git a/packages/kbn-i18n/README.md b/packages/kbn-i18n/README.md
index fa4b80d09e4b..ba8858417221 100644
--- a/packages/kbn-i18n/README.md
+++ b/packages/kbn-i18n/README.md
@@ -13,30 +13,7 @@ message syntax.
 
 ## Localization files
 
-Localization files have [JSON5](https://github.com/json5/json5) format.
-
-The main benefits of using `JSON5`:
-
-- Objects may have a single trailing comma.
-- Single and multi-line comments are allowed.
-- Strings may span multiple lines by escaping new line characters.
-
-Short example:
-
-```js
-{
-  // comments
-  unquoted: 'and you can quote me on that',
-  singleQuotes: 'I can use "double quotes" here',
-  lineBreaks: "Wow! \
-No \\n's!",
-  hexadecimal: 0xdecaf,
-  leadingDecimalPoint: .8675309, andTrailing: 8675309.,
-  positiveSign: +1,
-  trailingComma: 'in objects', andIn: ['arrays',],
-  "backwardsCompatible": "with JSON",
-}
-```
+Localization files are JSON files.
 
 Using comments can help to understand which section of the application
 the localization key is used for. Also `namespaces`
@@ -107,7 +84,7 @@ when missing translations
 For the detailed explanation, see the section below
 - `getFormats()` - returns current formats
 - `getRegisteredLocales()` - returns array of locales having translations
-- `translate(id: string, [{values: object, defaultMessage: string, description: string}])` –
+- `translate(id: string, { values: object, defaultMessage: string, description: string })` –
 translate message by id. `description` is optional context comment that will be extracted
 by i18n tools and added as a comment next to translation message at `defaultMessages.json`.
 - `init(messages: Map<string, string>)` - initializes the engine
@@ -384,13 +361,13 @@ when missing 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 }])`–
+- `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 }]}}
+{{ ::'translationId' | i18n: { values: object, defaultMessage: string, description: string } }}
 ```
 
 Where:
@@ -452,20 +429,10 @@ In order to translate attributes in AngularJS we should use `i18nFilter`:
 >
 ```
 
-## Build tools
+## I18n tools
 
-In order to simplify localization process, some build tools will be added:
-- tool for verifying all translations have translatable strings
-- tool for checking unused translation strings
-- tool for extracting default messages from templates
+In order to simplify localization process, some additional tools were implemented:
+- tool for verifying all translations have translatable strings and extracting default messages from templates
+- tool for verifying translation files and integrating them to Kibana
 
-While `react-intl` has
-[babel-plugin-react-intl](https://github.com/yahoo/babel-plugin-react-intl)
-library which extracts string messages for translation, angular wrapper requires
-own implementation of such tool. In order to extracrt translation keys from the
-template, we have to parse it and create AST object. There is a
-[babel-plugin-syntax-jsx](https://github.com/babel/babel/tree/master/packages/babel-plugin-syntax-jsx)
-plugin which helps to parse JSX syntax and then create AST object. Unfortunately,
-there are no babel plugins to parse angular templates. One of the solution can be internal
-[`$parse.$$getAst`](https://github.com/angular/angular.js/blob/master/src/ng/parse.js#L1819)
-angular method.
+[I18n tools documentation](../../src/dev/i18n/README.md)