i18n.md

Atlas localization

Backend

Localization files directory: src/main/resources/i18n

Localization file naming convention: messages_{lang}.json, where {lang} is two-letters (ISO 639-1) language code.

List of supported localizations is presented in locales.json file in the same directory:

[
  {
    "code": "en",
    "name": "English",
    "default": true
  },
  {
    "code": "ru",
    "name": "Русский"
  },
  {
    "code": "ko",
    "name": "한국어"
  },
  {
    "code": "zh",
    "name": "中文"
  }
]

Messages file is in JSON format and contains localized messages organized as a tree:

{
  "section1": {
    "subsection1": {
      "message": "Localized message1"
    },
    "subsection2": {
      "message": "Localized message2"
    },
  },  
  "section2": {
    "subsection1": {
      "message": "Localized message3 <%=param%>"      
    }
  }
}

so each localized message has a unique path. For example: section1.subsection2.message points to "Localized message1".

Frontend

Languages listed in locales.json are shown in the selector on the upper part of the page.

When choosing a language, all text on the page changes dynamically without the need to reload the page.

Reference to localized message can be placed whereever ko object is available.

There are two methods in ko for localized messages (see js/extensions/bindings/i18nBinding.js):

• ko.i18n(path, defaultMessage) where path is a path to the message in the localization file messages_{lang}.json and defaultMessage is a text, that will be used if there is no such path in localization file.

• ko.i18nformat(path, defaultMessage, parameters) - same as above, but with parameters.
  For example:
  message (in localization file and/or default): Localized message3 <%=param%>
  parameters object: {"param": "some text"}
  result: Localized message3 some text
  Parameter values can be localized as well with any nesting level.

Both methods return ko.pureComputed() function, that can be unwrapped or called to receive a localized message (see examples below).

Examples:

1. In HTML files through data-bind="text: ..."

<span data-bind="text: ko.i18n('section1.subsection2.message', 'Localized message1')"></span>

2. Passed as parameter, provided that it will be used as it is in data-bind attribute, or unwrapped in any other way:

<atlas-modal params="
  showModal: $component.isExecutionDesignShown,
  title: ko.i18n('components.analysisExecution.designModal.title', 'Design'),
  ...

3. In .js:

alert(
  ko.i18n('cohortDefinitions.cohortDefinitionManager.confirms.save',
  'Cohort definition cannot be deleted because it is referenced in some analysis.')()
)

or

alert(
  ko.unwrap(
    ko.i18n('cohortDefinitions.cohortDefinitionManager.confirms.save',
      'Cohort definition cannot be deleted because it is referenced in some analysis.')
  )
)