Write translation guide (#2103)

* Write translation guide

* Add links to other guides
Fix typo

* Add word of warning to localization guide

* Minor change

docs/devel/README.md

 # Dashboard Developer Guide
 
-The developer guide is for anyone wanting to contribute code to Dashboard
+The developer guide is for anyone wanting to contribute to Dashboard
 
 ## Index
 * [Getting started guide](getting-started.md)
+* [Roadmap](roadmap.md)
 * [Release process](release.md)
+* [Development releases](head-releases.md)
 * [Issue and pull request labels](labels.md)
+* [Text conventions](text-conventions.md)
+* [Localization guide](localization.md)
+* [Providing new translations](translations.md)
+* [Updating code dependencies](updating-deps.md)

docs/devel/localization.md

@@ -8,7 +8,7 @@ Dashboard is currently localized through the Google Closure Compiler's `goog.get
 
 The localization process itself is integrated into the build pipeline and back-end component of Dashboard and happens automatically. Apart from placing new text into `MSG_` variables and using those in the angular templates, the developer is not required to do anything else.
 
-## The MSG variables
+## Localization with `MSG_` variables
 
 Here is an example of a single `MSG_` variable definition:
 
@@ -26,7 +26,7 @@ Guidelines:
 
 For a quick reference please see [this cheat sheet](http://www.closurecheatsheet.com/i18n).
 
-## Organizing the text variables
+#### Organizing the text variables
 
 Currently, the `MSG` variables are stored in a constant dictionary at the bottom of the controller, which scopes the place (template) where they are used. The variables can then be referenced directly in the respective template's HTML code.
 
@@ -47,7 +47,7 @@ class exampleController {
 }
 
 const i18n = {
-  /** @export {string} @desc a simple example */
+  /** @export {string} @desc a simple description for the translator */
   MSG_EXAMPLE_TEXT: goog.getMsg('This is an example'),
   ... // other variables
 }
@@ -61,6 +61,32 @@ const i18n = {
 
 In the HTML code, use one-time bindings like `{{::ctrl.i18n.MSG_EXAMPLE_TEXT}}` for efficiency.
 
+## Localization with `[[Message|]]` pattern
+
+Usage of `MSG_` variables in JavaScript and HTML files is not the only way to localize messages. The second option
+is to use specific pattern directly in HTML messages:
+
+```
+[[This is an example|a simple description for the translator]]
+```
+
+As you can see it is the same definition as in above section, but it is a lot easier to use. There is sample usage:
+
+```html
+<div>
+    [[This is an example|a simple description for the translator]]
+</div>
+```
+
+#### Warning
+
+This is a quick way of using multiple localized messages without changes in JavaScript files, but it does have few
+drawbacks. Please keep in mind this method requires some automated work and following rules apply:
+
+ * Message variables are generated automatically during build process. Their names depend on file name and message
+ position within a file. It means, that if message will be moved to another file, all it's translations will be lost.
+ * It is not possible to reference variables from `[[|]]` pattern.
+
 ## Naming conventions and guidelines
 * Consistently name the object containing the variables for a given controller `i18n`.
 * In the variable's name, after `MSG_`, try to write down the name of the controller (or part of Dashboard) to indicate where the variable is being used.

docs/devel/translations.md

+# Translations
+
+The document describes the proper way to introduce new translations to the project.
+
+## Overview
+
+All translation data is stored in `i18n` directory in project's root. It includes configuration file
+(`locale_conf.json`) and translation files for each language (`messages-en.xtb`, `messages-ja.xtb` and other).
+
+## Providing translations for a new language
+
+To provide translations for a new language following steps have to be followed.
+
+#### Update configuration file
+
+Update `locale_conf.json` file to add new entry. Assuming following configuration:
+
+```json
+{
+  "translations": [
+    {"file": "messages-en.xtb", "key": "en"},
+    {"file": "messages-zh.xtb", "key": "zh"},
+    {"file": "messages-ja.xtb", "key": "ja"}
+  ]
+}
+```
+
+Following entry should be added:
+
+
+```json
+{"file": "messages-es.xtb", "key": "es"}
+```
+
+So configuration should look like this:
+
+```json
+{
+  "translations": [
+    {"file": "messages-en.xtb", "key": "en"},
+    {"file": "messages-zh.xtb", "key": "zh"},
+    {"file": "messages-ja.xtb", "key": "ja"},
+    {"file": "messages-es.xtb", "key": "es"}
+  ]
+}
+```
+
+#### Generate translation file
+
+To generate translation file run:
+
+```sh
+gulp generate-xtbs
+```
+
+As a result new translation file should appear in `i18n` directory.
+
+## Providing translations
+
+To provide translations for specific language you should open one of the translation files and replace its English
+content in `<translation>` markup elements. Assuming file is being translated to Spanish following element in
+translation file:
+
+```xml
+<translation id="0" key="MSG_WELCOME" desc="Welcome message.">Welcome</translation>
+```
+
+Should be updated to:
+
+```xml
+<translation id="0" key="MSG_WELCOME" desc="Welcome message.">Bienvenido</translation>
+```
\ No newline at end of file