Localization

Search
Feedback

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 localization
  • domain
    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 the localize() function in case of a match.
Matching Requested with Stored Parameters

The following rules determine the return value of the localize() function:

  1. Exact match
    The requested locale String, the name and the domain attributes match exactly.

  2. No requested domain
    The requested locale and name match exactly, but there is no requested domain. In this case, only localizations without domain are taken into account. If more than one localization item is found, the first one is returned.

  3. With requested domain, but only non-domain localizations are stored
    Given exactly matching locale and name attribute, if a domain is requested, but there are no localization items stored with a matching domain attribute, the first localization without a domain, but matching locale and name 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 localization
  • domain
    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

  • 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

  1. Simple example without domain

    |name|domain|locale|localizedName|
    |-|-|-|-|
    |helloWorld||en|Hello world|
    |helloWorld||de|Hallo Welt|
    |helloWorld||fr|Bonjour monde|
    |helloWorld||es|Hola mundo|

  2. 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|€|

  3. Simple example with country code

    |name|domain|locale|localizedName|
    |-|-|-|-|
    |hello||de_DE|Hallo|
    |hello||de_AT|Servus|
    |hello||de_CH|Grüezi|

Graph-Browser

Related Articles
About this article
Last change 2017-05-04
Topics Structr 2.0