# Using goog.getMsg() for translation

### Localizing dashboard
* The translatable text messages are specified as MSG_<something> attributes of all the controller classes, using goog.getMsg().
* Each variable has a @desc annotation which describes the logical meaning of the text to be translated.
* The supported languages are listed in a separate json file, which is imported into `./build/conf.js` during the build process.
* When doing production builds (e.g. `gulp build-frontend` task), all of the messages are extracted (via XtbGenerator) into the mentioned XTB translation bundles (under the directory `./i18n`, one per language) automatically (`extract-translations` task). Already existing translations are of course not overwritten. Newly found messages are added to the translation bundles. NOTE: AFAICS, old obsolete messages are not automatically removed from the existing bundles => the translators will need to clean them manually, it's the behavior of XtbGenerator. That's the only flaw I've seen so far.
* When building the sources we have the following steps in the build chain:
  * Google Closure compiler builds one app.js file for each language, in a separate directory in .tmp, using the respective .xtb translation bundle in the process and injecting the messages.
  * Through an intermediate step, the "production-ready" code is prepared in .tmp, ready to be localized and revisioned.
  * Then the localization is done by replacing the app.js files for each locale.
  * Finally, throught the `build-frontend` gulp task, the final "compiled" code is moved into `./dist`, keeping the per-language folder structure and is revisioned in the process. The dist folder looks like this:
  ```
  dist/
  +-- amd64/
  |   +-- en/
  |   |   +-- public/
  |   |       +-- index.html <-- uses the assets from static
  |   |       +-- static/
  |   |           +-- vendor.js <--- the packed library deps
  |   |           +-- app.js <--- the localized code (*en* in this case)
  |   |           +-- vendor.css <-- packed vendor .css
  |   |           +-- app.css <-- packed application .css
  |   +-- ja
  |   |   +-- public/
  |   |       +-- ... same as above...
  |   |
  +-- <other archs> ...
  |   +-- <locales per arch> ...
  |
  +-- locale_conf.json
  ```
* the `locale_conf.json` file is for the dashboard backend. It is used by the backend to determine the right localized version of the `index.html` that should be served.
* The human translators can now easily translate messages in the XTB bundles, and those changes will be picked up by the closure compiler (via our build pipeline) during each production build.

### Serving the localized index.html
* In production, we use our GOLANG backend as a webserver (serves the pages). In development we do not (we serve via browsersync). We do not have internationalization when serving in development mode.
* In production, the GO backend's server component intercepts all requests and checks their "Accept-Language" header, to determine the locale of the user. Based on the locale, the server chooses from which of the `./dist/<locale>` directories to serve. To avoid caching issues in browsers, the "index.html" pages are never cached (header `Cahce-Controle: no-cache` in the requests).