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 ofLanguage + Region
orLanguage
value. Language ID follows the two-letterISO 639-1
standard and Region ID follow the two-letterISO 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.
Note: Framework supports lang=<Language-ID>
URL query parameter or Path Variable to enable locale for the current request Out-of-the-box.
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 perRFC7231
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 localeLanguage + 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 themsg 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 byLanguage
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 themessage key
as not found.