i18n - Internationalization

aah provides internationalization and localization feature for aah application.

  • i18n Message file format is forge config syntax. Same as aah.conf syntax.
  • i18n 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
    • Region ID follow the two-letter ISO 3166-1 standard
  • Zero coding effect on localizing your application via URL Path Variable or URL Query String

aah supports sub-directories under <app-base-dir>/i18n/..., so customized organization of message per use case is feasible.

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.

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 https://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 OOTB ways to override Request Context user locale. Refer to locale param processing order.

  • Override via URL Query parameter, e.g. https://example.com/home?lang=de, example app
  • Override via URL Path parameter, e.g. https://example.com/de/home, example app
    • 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>

Methods

At View file

  • {{ i18n . "message.key" }}
  • {{ i18n . "message.key" arguments }}

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 Param Processing Order

  • First URL Query parameter if present
  • Next is URL Path parameter if present
  • Next is HTTP Header Accept-Language parsed per RFC 7231

Default key name is lang, if you would like to override the key name; refer app config: section i18n

i18n Message Lookup strategy by key

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.