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 ofLanguage + Region
orLanguage
value.- Language ID follows the two-letter
ISO 639-1
standard - Region ID follow the two-letter
ISO 3166-1
standard
- Language ID follows the two-letter
- 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
- On-Demand Translation
- i18n Methods
- i18n Locale Param Processing Order
- i18n Message Lookup strategy by key
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>
- This involves the route path definition e.g.
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 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.