i18n - Internationalization

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
• On-Demand Translation
• i18n Methods
• i18n Locale Value Processing Order
• i18n Message Lookup strategy by key as follows

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.