# Multi-Lingual Support in citeproc-js

## Virtual fields

The title and name entries will have special markup for testing purposes.
For title entries, tags are used as delimiters.  The first content in the
entry is the default.  Subsequent tags indicate the language or script
of subsequent content until the next tag or the end of the entry, whichever
comes first.

For creator entries, tags are used as prefix on the literal or the family
name element.  The first set of names has no tag, and serves as the
default.  In subsequent tagged entries, the tag indicates the language or 
script of the entry, to be used as a replacement for the nearest preceding
untagged entry.

## Language tag

For compatibility with other multi-lingual stores, please refer to
RFC 4646, and the IANA registry of language names when setting
the tag for a translation, transliteration, or alternate form.

## Default locale string

The default-locale attribute of CSL styles validates successfully with
roman letters and hyphens.  Rendering options are fashioned out of
this limited set of characters.  Elements in the default-locale may
consist of several elements, each (except the first) beginning with one
of the reserved words "x-primary", "x-secondary", "x-sort".  For setting
discrete content locale values for the creator elements, overriding the
default, use "-name" as an extension (as, for example, "x-primary-name").
The special value "none" may be used to indicate that a default
value should be ignored for names.

### Global default locale 

The first element in the default-locale string must begin with a
language specifier.  This may be followed optionally by a variant.
The following two default-locale specifiers are valid:

    en
    en-US

The following specifier is *not* valid:

    en_US

### Subsidiary default locales

Subsidiary default locales can be used to set preferences for the
sub-field to be used for primary content.  Each subsidiary default
locale specifier consists of a key label, followed by a hyphen,
followed by the specifier string.  As stated above, a reserved word,
or "key label", is the first word in a subsidiary default locale.

#### The `primary` key label

The primary content preference is set using the "primary" key label.
For example:

    en-US-primary-eng

The above string would declare English as the language of the style,
and use entries with the :eng: tag as the primary content sub-field,
where that tag is available.  Where the tag is not available, the
processor will fall back to the default content.

For names, the primary content sub-field provides the field's sole
content in the citation.  For titles, the primary content sub-field is
rendered as the title (possibly followed by a single translation or
transliteration in braces, as discussed below).  For example, consider
the following entry:

    日本語の見出し
    :jpn-katakana: ニホンゴノミダシ
    :eng-hepburn: Nihongo no Midashi
    :eng: Japanese Title

With a setting of `en-US--primary-eng`, this would render the title as
"Japanese Title".  The other sub-fields would be ignored.

#### The `secondary` key label

The secondary key label provides either a translation or a transliteration
of the content.  This additional content is supplied in title fields
and literal name fields only, immediately after the primary content, in
braces.  For example, if we have the following entry:

    日本語の見出し
    :jpn-katakana: ニホンゴノミダシ
    :eng-hepburn: Nihongo no Midashi
    :eng: Japanese Title

With a default-locale setting of `en-US-secondary-eng`, the title
field would appear as: "日本語の見出し [Japanese Title]".

#### The `sort` key label

The `sort` key label provides a string to be used in sorting the
entry.  The language of the style will determine the locale to be used in
sorting the string.  For example, if we have the following entry:

    日本語の見出し
    :jpn-katakana: ニホンゴノミダシ
    :eng-hepburn: Nihongo no Midashi
    :eng: Japanese Title

With a default-locale setting of `ja-JP-sort-jpn-katakana`, the entries
would be sorted using the jpn-katakana sub-field, if available, falling
back to the default field content otherwise.