locale

See internationalization (I18N) glossary entry for a general introduction.

Localization (or "I10N") is a process of making an I18N-enabled application to use specific locale definition (messages, currency format, etc.).

Localized Catalogs

The important thing to have in mind is that Interchange allows customers to access the same catalog in an unlimited number of languages, currencies and regional settings. What's more, you can switch locales at will, at any time!

The simplest and recommended way to set the default catalog locale is to define a starting value for mv_locale in catalog.cfg:

ScratchDefault mv_locale de_DE

The per-user locale change can be made permanent (for the duration of the user session, of course), or temporary (if you're, say, displaying pricing information in multiple currencies). See [setlocale] for more discussion and examples.

Besides using actual "programmatic" methods to set locales, you can achieve the same effect by using one terrific feature of the process ActionMap; to display page named "pricelist" in locale fr_FR and currency en_US, simply call ITL tag [page process/locale/fr_FR/currency/en_US/page/pricelist].

Locale-specific Messages and Locale Database

The localized messages you want to display must previously be defined, of course. The simplest way to define localized messages is to use the Locale directive in any of the ways shown:

Locale de_DE "Value setting" Werteinstellung
Locale de_DE "Search"        Suchen

Locale fr_FR <<EOF
{
  "Value setting",
  "Configuration de valeur",
  
  "Search",
  "Recherche"
}
EOF

This method, however, is not practical when you have a lot of messages; for robust setups use LocaleDatabase.

With the above, to display an appropriate translation of "Value setting", you would call "[L]Value setting[/L]", which would display as "Configuration de valeur" in locale fr_FR, "Werteinstellung" in locale de_DE, and as a fallback, it would be displayed unmodified as "Value setting" — if the locale is neither fr_FR not de_DE, or no localized string for the message was found at all. Keep in mind that the "[L]" tags must be capitalized — this is done for both processing speed and easy visual distinction within pages.

[Note]A word on localization tag [L]

Interchange tries to substitute text for its localized variant very early in the page serving process — even before variables are expanded or tags interpolated.

On one hand, this means you can use variables and tags in localized strings as they will be handled properly.

On the other hand, it means code constructs like [L][item-data table field][/L] will fail, as Interchange would try to translate "[item-data table field]" literally. There's a [loc] tag available which is functionally identical to L, but is parsed in normal order and therefore solves the problem.

Another way to display localized messages is to supply localization text directly within Interchange pages, inside LC tag; have a look at this intuitive example:

[LC]
  This is the default text.
  [fr_FR] Text for the fr_FR locale. [/fr_FR]
  [de_DE] Text for the de_DE locale. [/de_DE]
[/LC]

It's also possible to display completely different pages, based on the locale in effect. You probably know the default HTMLsuffix in Interchange is ".html", but you probably do not know it is locale-sensitive. With a request for page named "index" ([page index]), fr_FR locale in effect, and a catalog.cfg directive of

Locale fr_FR HTMLsuffix .fr_FR

Interchange would first look for pages/index.fr_FR, and only if it's not found go to the usual pages/index.html.

[Note]A general note on locale-sensitivity of config directives

We've said HTMLsuffix is locale-sensitive, but the story gets much better. In reality, any Locale key that matches the name of a config directive, causes the directive to be re-set on locale change — in other words, all config directives are locale-sensitive!

Effect of Locales on Sorting

Interchange sorting features (such as — but not only — the sort tag) will honor a setting of LC_COLLATE, provided that the operating system and C compiler support locales for POSIX, have the locale definitions set, and the locale chosen matches one of locales available.

Suppose we have a letters database, containing some of the letters of the alphabet. A code of:

[loop 19-202 00-0011 99-102]
  [sort letters:letter]
  [loop-data letters letter]   [loop-code] <br/>
[/loop]

would provide different order for locale C than fr_FR.

DocBook! Interchange!