.\" Automatically generated by Pod::Man version 1.15
.\" Wed May  5 11:41:32 2004
.\"
.\" Standard preamble:
.\" ======================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Ip \" List item
.br
.ie \\n(.$>=3 .ne \\$3
.el .ne 3
.IP "\\$1" \\$2
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R

.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used
.\" to do unbreakable dashes and therefore won't be available.  \*(C` and
.\" \*(C' expand to `' in nroff, nothing in troff, for use with C<>
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr
.\" for titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and
.\" index entries marked with X<> in POD.  Of course, you'll have to process
.\" the output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it
.\" makes way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.bd B 3
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ======================================================================
.\"
.IX Title "ic_i18n 8"
.TH ic_i18n 8 "Interchange 5.2.0" "2004-05-05" "Interchange"
.UC
.SH "NAME"
ic_i18n \- Interchange I18N Features
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
.SH "Internationalization"
.IX Header "Internationalization"
Interchange has a rich set of internationalization (I18N) features
that allow conditional message display, differing price formats,
different currency definitions, price factoring, sorting, and other
settings. The definitions are maintained in the catalog.cfg file
through the use of built-in \s-1POSIX\s0 support and Interchange's Locale
directive. All settings are independent for each catalog and each user
visiting that catalog, since customers can access the same catalog in
an unlimited number of languages and currencies.
.Sh "Configuring the Locale"
.IX Subsection "Configuring the Locale"
It is recommended to use the ScratchDefault directive for setting
the catalog's default locale:
.PP
.Vb 1
\&   ScratchDefault mv_locale de_DE
.Ve
.Sh "Setting the Locale"
.IX Subsection "Setting the Locale"
The locale could be set to fr_FR (French for France) in one of two
ways:
.Ip "[setlocale locale=locale* currency=locale* persist=1*]" 4
.IX Item "[setlocale locale=locale* currency=locale* persist=1*]"
Immediately sets the locale to locale, and will cause it to persist
in future user pages if the persist is set to a non-zero, non-blank
value. If the currency attribute is set, the pricing and
currency-specific locale keys and Interchange configuration directives
are modified to that locale. If there are no arguments, it sets it
back to the user's default locale as defined in the scratch variables
mv_locale and mv_currency.
.Sp
This allows:
.Sp
.Vb 5
\&    Dollar Pr
\&    [setlocale en_US]
\&    [item-list]
\&    [item-code]: [item-price]<BR>
\&    [/item-list]
.Ve
.Vb 1
\&    Franc Pricing:
.Ve
.Vb 4
\&    [setlocale fr_FR]
\&    [item-list]
\&    [item-code]: [item-price]<BR>
\&    [/item-list]
.Ve
.Vb 2
\&    [comment] Return to the user's default locale [/comment]
\&    [setlocale]
.Ve
cing:
.Ip "[page process/locale/fr_FR/page/catalog]" 4
.IX Item "[page process/locale/fr_FR/page/catalog]"
This is the same as [page catalog], except when the link is
followed it will set the locale to fr_FR before displaying the
page. This is persistent.
.Ip "[page process/locale/fr_FR/currency/en_US/page/catalog]" 4
.IX Item "[page process/locale/fr_FR/currency/en_US/page/catalog]"
This is the same as [page catalog], except when the link is
followed it will set the locale to fr_FR and the pricing/number
display to the locale en_US before displaying the page. This is
persistent.
.PP
Once the locale is persistently set for a user, it is in effect for
the duration of their session.
.Sh "Interchange Locale Settings"
.IX Subsection "Interchange Locale Settings"
The Locale directive has many possible settings that allow complete
internationalization of page sets and currencies. The Locale
directive is defined in a series of key/value pairs with a key that
contains word characters only being followed by a value. The value
must be enclosed in double quotes if it contains whitespace. In this
example, the key is Value setting.
.PP
.Vb 2
\&   Locale fr_FR "Value setting" "Configuration de valeur"
\&   Locale de_DE "Value setting" Werteinstellung
.Ve
When accessed using the special tag [L]Value setting[/L], the value
Configuration de valeur will be displayed \fBonly\fR if the locale is
set to fr_FR. If the locale is set to de_DE, the string
Werteinstellung will be displayed. If it is neither, the default
value of Value setting will be displayed.
.PP
The [L] and [/L] must be capitalized. This is done for speed of
processing as well as easy differentiation in text.
.PP
Another, way to do this is right in the page. The [\s-1LC\s0] ... [/LC]
pragma pair permits specification of locale-dependent text.
.PP
.Vb 5
\& [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]
.Ve
You can also place an entirely new page in place of the default one if
the locale key is defined. When a locale is in force, and a key named
HTMLsuffix is set to that locale, Interchange first looks for a
page with a suffix corresponding to the locale. For example:
.PP
<A HREF=\*(L"[area index]\*(R">Catalog home page</A>
.PP
If a page index.html exists, it will be the default. If the current
locale is fr_FR, a page \*(L"index.fr_FR\*(R" exists, and Locale looks
like this:
.PP
.Vb 1
\&   Locale fr_FR HTMLsuffix  .fr_FR
.Ve
Then, the .fr_FR page will be used instead of the .html page.
For a longer series of strings, the configuration file recognizes:
.PP
.Vb 4
\&   Locale fr_FR <<EOF
\&   {
\&       "Value setting",
\&       "Configuration de valeur",
.Ve
.Vb 4
\&       "Search",
\&       "Recherche"
\&   }
\&   EOF
.Ve
This example sets two string substitutions. As long as this is a valid
Perl syntax describing a series of settings, the text will be matched.
It can contain any arbitrary set of characters that don't contain
[L] and [/L]. If using double quotes, string literals like \en
and \et are recognized.
.PP
A database can also be used to set locale information. Locale
information can be added to any database in the catalog.cfg file,
and the values in it will overwrite previous settings. For more
information, see LocaleDatabase. The [L]default text[/L] is set
before any other page processing takes place. It is equivalent to the
characters \*(L"default text\*(R" or the appropriate Locale translation for
all intents and purposes. Interchange tags and Variable values can be
embedded.
.PP
Because the [L] message [/L] substitution is done before any tag
processing, the command [L][item-data table field][/L] will fail.
There is an additional [loc] message [/loc] \fIUserTag\fR supplied
with the distribution. It does the same thing as [L] [/L] except it
is programmed after all tag substitution is done. See the
interchange.cfg.dist file for the definition.
.PP
\&\fBNote: \fRBe careful when editing pages containing localization
information. Even changing one character of the message can  change
the key value and invalidate the message for other languages. To
prevent this, use:
.PP
.Vb 1
\&   [L key]The default.[/L]
.Ve
The key msg_key will then be used to index the message. This may be
preferable for many applications.
.PP
A localize script is included with Interchange. It will parse files
included on the command line and produce output that can be easily
edited to produce localized information. Given an existing file, it
will merge new information where appropriate.
.Sh "Special Locale Keys for Price Representation"
.IX Subsection "Special Locale Keys for Price Representation"
Interchange honors the standard \s-1POSIX\s0 keys:
.PP
.Vb 4
\&   mon_decimal_point    or      decimal_point
\&   mon_thousands_sep    or      thousands_sep
\&   currency_symbol      or      int_currency_symbol
\&   frac_digits  or      p_cs_precedes
.Ve
See the \s-1POSIX\s0 \fIsetlocale\fR\|(3) man page for more information. These keys
will be used for formatting prices and approximates the number format
used in most countries. To set a custom price format, use these
special keys:
.Ip "price_picture" 4
.IX Item "price_picture"
Interchange will format a currency number based on a \*(L"picture\*(R" given
to it. The basic form is:
.Sp
.Vb 1
\&    Locale en_US price_picture "$ ###,###,###.##"
.Ve
The en_US locale, for the United States, would display 4452.3 as
$ 4,452.30. The same display can be achieved with:
.Sp
.Vb 3
\&     Locale en_US mon_thousands     Locale en_US mon_decimal_point .
\&     Locale en_US p_cs_precedes     1
\&     Locale en_US currency_symbol   $
.Ve
sep ,
.Sp
A common price_picture for European countries would be
###.###.###,##, which would display that same number as
4.452,30. To add a franc notation at the end for the locale
fr_FR, use the setting:
.Sp
.Vb 1
\&    Locale fr_FR price_picture "##.###,## fr"
.Ve
.PP
\&\fB\s-1IMPORTANT\s0 \s-1NOTE:\s0 \fRThe decimal point in use, set by
mon_decimal_point, and the thousands separator, set by
mon_thousands_sep must match the settings in the price_picture. The
frac_digits setting is not used in this case. It is derived from
the location of the decimal (if any).
.Ip "" 4
The same setting for fr_FR above can be achieved with:
.Sp
.Vb 3
\&     Locale fr_FR mon_thousands     Locale fr_FR mon_decimal_point ,
\&     Locale fr_FR p_cs_precedes     0
\&     Locale fr_FR currency_symbol   fr
.Ve
sep .
.Sp
If the number of digits is greater than the # locations in the
price_picture, the digits will be changed to asterisks. An overflow
number above would show as **.***,** fr.
.Ip "picture" 4
.IX Item "picture"
Same as price_picture, but sets the value returned if the
[currency] tag is not used. If the number of digits is greater than
the # locations in the picture, the digits will be changed to
asterisks, displaying something like **,***.**.
.Sh "Dynamic Locale Directive Changes"
.IX Subsection "Dynamic Locale Directive Changes"
If a Locale key is set to correspond to an Interchange catalog.cfg
directive, that value will be set when the locale is set.
.Ip "PageDir" 4
.IX Item "PageDir"
To use a different page directory for different locales, set the
PageDir key. For example, to have two separate language page sets,
French and English, set:
.Sp
.Vb 3
\&    # Establish the default at s    PageDir   english
\&    Locale fr_FR  PageDir  francais
\&    Locale en_US  PageDir  english
.Ve
artup
.Ip "ImageDir" 4
.IX Item "ImageDir"
To use a different image directory for different locales, set the
ImageDir key. To have two separate language button sets, French and
English, set:
.Sp
.Vb 3
\&    # Establish the default at s    ImageDir   /images/english/
\&    Locale fr_FR  ImageDir   /images/francais/
\&    Locale en_US  ImageDir   /images/english/
.Ve
artup
.Ip "ImageDirSecure" 4
.IX Item "ImageDirSecure"
See ImageDir.
.Ip "PriceField" 4
.IX Item "PriceField"
To use a different field in the products database for pricing based on
locale, set the PriceField locale setting. For example:
.Sp
.Vb 2
\&    # Establish the default at s    PriceField    price
\&    Locale fr_FR  PriceField  prix
.Ve
artup
.Sp
The default will always be price, but if the locale fr_FR is
set, the PriceField directive will change to prix to give prices
in francs instead of dollars.
.Sp
If PriceBreaks is enabled, the prix field from the pricing
database will be used to develop the quantity pricing.
.PP
\&\fBNote: \fRIf no Locale settings are present, the display will always
be price, regardless of what was set in PriceField. Otherwise,
it will match PriceField.
.Ip "PriceDivide" 4
.IX Item "PriceDivide"
Normally used to enable penny pricing with a setting of 100,
PriceField can be used to do an automatic conversion calculation
factor based on locale.
.Sp
.Vb 2
\&    # Default at startup is 1 if n    # Franc is strong these days!
\&    Locale fr_FR  PriceDivide  .20
.Ve
t set
.Sp
The price will now be divided by .20, making the franc price five
times higher than the dollar.
.Ip "PriceCommas" 4
.IX Item "PriceCommas"
This controls whether the mon_thousands_sep will be used for
standard currency formatting. This setting will be ignored if you are
using price_picture. Set the value to 1 or 0, to enable or disable
it. Do not use yes or no.
.Sp
.Vb 3
\&    # Default at startup is Yes if n    PriceCommas  Yes
\&    Locale fr_FR  PriceCommas  0
\&    Locale en_US  PriceCommas  1
.Ve
t set
.Ip "UseModifier" 4
.IX Item "UseModifier"
Changes the fields from the set shopping cart options.
.Sp
.Vb 3
\&    # Default at startup is 1 if n    # Franc is strong these days!
\&    UseModifier format
\&    Locale fr_FR  UseModifier formats
.Ve
t set
.Sp
If a previous setting was made for an item based on another locale, it
will be maintained.
.Ip "PriceAdjustment" 4
.IX Item "PriceAdjustment"
Changes the fields set by UseModifier that will be used to adjust
pricing for an automatic conversion factor based on locale. For
example:
.Sp
.Vb 2
\&    # Default at s    PriceAdjustment  format
\&    Locale fr_FR  PriceAdjustment  formats
.Ve
artup
.Ip "TaxShipping,SalesTax" 4
.IX Item "TaxShipping,SalesTax"
Same as the standard directives.
.Ip "DescriptionField" 4
.IX Item "DescriptionField"
This changes the field accessed by default with the
[item-description] and [description code] tags. For example
.Sp
.Vb 2
\&    # Establish the default at s    DescriptionField    description
\&    Locale fr_FR  DescriptionField desc_fr
.Ve
artup
.Ip "The [locale] tag" 4
.IX Item "The [locale] tag"
Standard error messages can be set based on Locale settings. Make sure
not to use any of the predefined keys. It is safest to begin a key
with msg_ . The default message is set between the [locale key] and
[/locale] tags. See the example above.
.Sh "Sorting Based on Locale"
.IX Subsection "Sorting Based on Locale"
The Interchange [sort database:field] keys will use the \s-1LC_COLLATE\s0
setting for a locale provided that:
.Ip "\(bu" 4
The operating system and C compiler support locales for \s-1POSIX\s0, and
have the locale definitions set.
.Ip "\(bu" 4
The locale setting matches any configured locales.
.PP
If this arbitrary database named letters:
.PP
.Vb 4
\&   code        letter
\&   00-0011     f
\&   99-102      é
\&   19-202      a
.Ve
and this loop:
.PP
.Vb 4
\&   [loop 19-202 00-0011 99-102]
\&   [sort letters:letter]
\&   [loop-data letters letter]   [loop-code]
\&   [/loop]
.Ve
used the default C setting for \s-1LC_COLLATE\s0, the following would be
displayed:
.PP
.Vb 3
\&   a  19-202
\&   f  00-0011
\&   é  99-102
.Ve
If the proper \s-1LC_COLLATE\s0 settings for locale fr_FR were in effect,
then the above would become:
.PP
.Vb 3
\&   a  19-202
\&   é  99-102
\&   f  00-0011
.Ve
.Sh "Placing Locale Information in a Database"
.IX Subsection "Placing Locale Information in a Database"
Interchange has the capability to read its locale information from a
database, named with the LocaleDatabase directive. The database can
be of any valid Interchange type. The locales are in columns, and the
keys are in rows. For example, to set up price information:
.PP
.Vb 6
\&   key                 en_US   fr_FR   de_DE
\&   PriceDivide         1       .1590   .58
\&   mon_decimal_point   .       ,       ,
\&   mon_thousands_sep   ,       .
\&   currency_symbol     $        frs    DM
\&   ps_cs_precedes      1       0       0
.Ve
This would translate to the following:
.PP
.Vb 5
\&   Locale en_US PriceDivide         1
\&   Locale en_US mon_decimal_point   .
\&   Locale en_US mon_thousands_sep   ,
\&   Locale en_US currency_symbol     $
\&   Locale en_US ps_cs_precedes      1
.Ve
.Vb 5
\&   Locale fr_FR PriceDivide         .1590
\&   Locale fr_FR mon_decimal_point   ,
\&   Locale fr_FR mon_thousands_sep   .
\&   Locale fr_FR currency_symbol     " frs"
\&   Locale fr_FR ps_cs_precedes      0
.Ve
.Vb 5
\&   Locale de_DE PriceDivide         .58
\&   Locale de_DE mon_decimal_point   ,
\&   Locale de_DE mon_thousands_sep   " "
\&   Locale de_DE currency_symbol     "DM "
\&   Locale de_DE ps_cs_precedes      1
.Ve
These settings append and overwrite any that are set in the catalog
configuration files, including any include files.
.PP
Important note: This information is only read during catalog
configuration. It is not reasonable to access a database for
translation or currency conversion in the normal course of events.
.PP
.Vb 1
\& ________________________________________
.Ve
Copyright 2002\-2004 Interchange Development Group. Copyright 2001\-2002
Red Hat, Inc. Freely redistributable under terms of the \s-1GNU\s0 General
Public License.