i18n - Internationalization & Localization

i18n library provides internationalization and localization feature for aah application.

  • Message file format is forge config syntax which is very similar to HOCON syntax.
  • Message filename format is message.<Language-ID>. Language ID is combination of Language + Region or Language value. Language ID follows the two-letter ISO 639-1 standard and Region ID follow the two-letter ISO 3166-1 standard.
  • Zero coding effect on localizing your application via Path Variable or URL Query String. Refer to respective tutorials.
Supported message file extension formats are (in-casesensitive)
  1) Language + Region => en-us | en-US
  2) Language          => en

For Example:
  message.en-US or message.en-us
  message.en-GB or message.en-gb
  message.en-CA or message.en-ca
  message.en
  message.es
  message.zh
  message.nl
  etc.


Framework supports sub-directories under <app-base-dir>/i18n/..., so organize your message files as you need.

Table of Contents

Default Behavior

aah automatically does translation based incoming Request Context i.e. HTTP header Accept-Language, parsed per RFC7231.

For example:

When user visits http://example.com/home; all the i18n keys in the view file is processed and presented based on request user locale.

On-Demand Translation

aah provides out-of-the-box ways to override Request Context user locale. Refer to locale param processing order.

  • Override via URL Query parameter, e.g. http://example.com/home?lang=de, tutorial
  • Override via URL Path parameter, e.g. http://example.com/de/home, tutorial
    • This involves the route path definition e.g. /:lang/home
    • On view file, to generate link URL using func rurl - <a href="{{ rurl . "home" "de" }}">Deutsch</a>

i18n Methods

At Controller

  • Msg(key)
  • Msg(key, arguments)
  • Msgl(locale, key)
  • Msgl(locale, key, arguments)

Anywhere

  • aah.AppI18n().Lookup(locale, key)
  • aah.AppI18n().Lookup(locale, key, arguments)

i18n Locale Value Processing Order

  • Framework parses the Accept-Language header value per RFC7231 to enable User Locale for the request.
  • If Path Variable /:lang/ present in the route configuration, it overrides the locale value of Accept-Language header. Refer to i18n-path-param tutorial
  • If URL query parameter lang=<Language-ID> present, it overrides the locale value of Accept-Language header and Path Variable value. Refer to i18n-url-query-param tutorial

Default key name is lang, if you would like to override the key name; use following configuration:

i18n {
  # It is used as fallback if framework is unable to determine the
  # locale from HTTP Request.
  # Default value is `en`.
  #default = "en"

  # Overriding Request Locale via URL Path or URL Query Param
  param_name {
    # Specify URL Path Param name i.e. `/:lang/home.html`, `/:lang/aboutus.html`, etc.
    # For e.g.: `/en/home.html`, `/en/aboutus.html`, `/zh-CN/home.html`, `/zh-CN/aboutus.html` etc.
    # Default value is `lang`
    path = "locale"

    # Specify URL Query Param name i.e `?lang=en`, `?lang=zh-CN`, etc.
    # Default value is `lang`
    query = "locale"
  }
}

i18n Message Lookup strategy by key as follows

Scenario 1

Input Locale is en-US and message key is label.page.index.title.

  • First it does looks up i18n store by given locale Language + Region value if found then returns it
  • Second if not found then it does looks up by Language only if found then return it.
  • Third if not found then it does looks up by i18n.default config value if found then return it.
  • Otherwise it returns empty string and logs the msg key as not found.

Scenario 2

Input Locale is en and message key is label.page.index.title.

  • First it does looks up i18n store by Language value if found then return it.
  • Second if not found then it does looks up by i18n.default config value if found then return it.
  • Otherwise it returns empty string and logs the message key as not found.