Localization
Any output in Structr can be localized by using the built-in function localize()
. Using localize()
tells Structr to display a localized value of the text in name
, if a matching localization is found in the database, or the text itself, if no matching localization was found.
Requested Parameters
There are two parameters to define the requested localization: name
and the optional domain
.
The requested locale is determined from different potential sources, see locale. It’s basically a String value consisting of a mandatory language part and an optional country part, separated by an underscore (_).
Stored Parameters
The built-in type Localization
serves as source for the localize()
function. There are four attributes which define a stored localization element:
name
The key which is used to look up the localizationdomain
The localization domain. This serves as a means of distinguishing between otherwise duplicate names.
Because of the way localize() returns localizations the domain-less localization can be used as a default localization for a certain name.locale
The locale for which the localization applies.localizedName
The localized string. This is the return value of thelocalize()
function in case of a match.
Matching Requested with Stored Parameters
The following rules determine the return value of the localize()
function:
-
Exact match
The requested locale String, thename
and thedomain
attributes match exactly. -
No requested domain
The requested locale andname
match exactly, but there is no requesteddomain
. In this case, only localizations without domain are taken into account. If more than one localization item is found, the first one is returned. -
With requested domain, but only non-domain localizations are stored
Given exactly matching locale andname
attribute, if a domain is requested, but there are no localization items stored with a matchingdomain
attribute, the first localization without a domain, but matching locale andname
is returned.
If the localization items are stored with a locale String that has the country part only, the only the language part of any requested locale is taken into account.
Structr has a concept of localized strings. The built-in type Localization
serves as source for the localize()
function.
An object of type localization has four defining attributes:
name
The key which is used to look up the localizationdomain
The localization domain. This serves as a means of distinguishing between otherwise duplicatename
s.
Because of the waylocalize()
returns localizations the domain-less localization can be used as a default localization for a certainname
.locale
The locale for which the localization applies.localizedName
The localized string
imported
- This flag has no effect on the localization itself. It merely serves as an indicator wether or not the localization entry has been imported. This can happen when Structr is used to replace an existing system.
Examples
-
Simple example without domain
name domain locale localizedName helloWorld en Hello world helloWorld de Hallo Welt helloWorld fr Bonjour monde helloWorld es Hola mundo -
Example where a domain is used (but the locale is rather meaningless)
name domain locale localizedName USD en_EN Dollar USD symbol en_EN $ GBP en_EN Pound GBP symbol en_EN £ EUR en_EN Euro EUR symbol en_EN € -
Simple example with country code
name domain locale localizedName hello de_DE Hallo hello de_AT Servus hello de_CH Grüezi