Localization Keys: Controlling Language In Biblatex Styles

BibLaTeX allows for powerful localization of bibliographies through the use of localization keys. These keys enable style developers to control language-specific formatting issues that may arise when citing sources in different languages and regions.

The Problem of Language-Specific Formatting

A major challenge when working with bibliographies is handling the language-specific requirements for formatting names, dates, locations, and other metadata. For example, author names may need to be ordered differently depending on the language context, while dates and times can vary enormously based on the locale. Bibliography styles that make assumptions about formatting conventions may not be suitable for some languages and regions.

If the language-specific requirements are hard-coded into styles, it makes properly localizing the styles difficult. Every language and region combination would need its own custom style. Instead, BibLaTeX uses localization keys to abstract out the language-specific components and facilitate flexible localization of styles.

Table of Contents

Using Localization Keys

At the core of BibLaTeX's localization capabilities is the use of keys that label parts of the bibliography that may need to adapt based on linguistic or regional contexts. For example, the date key handles the representation of dates, while name keys control the rendering of author names.

Style authors can tie language-specific macros to these localization keys when defining bibliography drivers and formatting directives. For example:

\DeclareLocalizedFormat{date}{\mydateformat{#1}}

Here the \mydateformat macro would reformat the date #1 as needed for the target language or region. The date key automatically passes the date to this macro whenever a date field needs to be printed in a bibliography entry. No further coding is needed to make dates localize properly.

Some commonly used localization keys in BibLaTeX styles include:

date: Formats dates and date ranges
name: Governs representation of author/editor names
location: Controls printing of locations like cities and countries
punctuation: Handles localization-specific punctuation
captions: Labels for textual elements like "edited by", "translator", etc.
ordinals: Localized ordinal numbers like 1st, 2nd, 3rd formats

By providing localization keys for both major structuring elements like dates and names, as well as finer details like punctuation and captions, BibLaTeX makes completely adapting styles to new languages and regions possible.

Localizing Name Formats

One of the most important areas where localization is necessary is the formatting of author and editor names in bibliography entries. Name order, abbreviations, and representations can vary enormously between languages.

BibLaTeX provides granular name localization keys to address this need. The name keys govern how name parts like surnames and given names are rendered and ordered, while name:first-last and name:last-first explicitly control name output order. For example:

\DeclareLocalizedNameFormat{labelname}{%
  \ifcase\value{uniquename}%
    \usebibmacro{name:last-first}{#1}{#3}{#5}{#7}%
  \or
    \ifuseprefix
      {\usebibmacro{name:first-last-prefix}{#1}{#4}{#5}{#8}}
      {\usebibmacro{name:first-last}{#1}{#4}{#5}{#8}}%
  \fi
\fi}

This flexible name system also supports localization keys for formatting specific name parts like name:given and name:prefix. Styles can use these granular keys to adapt naming conventions as needed.

Example Localizations

To transform name formatting to Hungarian conventions, which reverse name order and abbreviate given names, a style could use:

\DeclareLocalizedNameFormat{labelname}{% 
  \usebibmacro{name:last-first}{#1}{#3}{#5}{#7}% Reverse order
  \usebibmacro{name:given-limit}{#3}{#5}{\bibnamedelimh}}% Limit given names

Similar modifications using name keys enables full transformation of name handling for other languages and regions as well.

Formatting Dates and Times

In addition to names, dates and times also frequently need localization. The requirements can be as simple as changing the date delimiter from "/" to "." for European vs. American date styles. But custom date formats may also be needed in some language contexts.

The date localization key handles date formatting:

\DeclareLocalizedFormat{date}{\mydateformat{#1}}

\newrobustcmd{\mydateformat}[1]{%
  \iffieldundef{#1year}
    {\mkbibnodate{}}
    {\mkdayzeros{\thefield{#1year}}-\mkmonthzeros{\thefield{#1month}}-\mkdayzeros{\thefield{#1day}}}%
  \iffieldundef{#1endyear}{}{\bibrangedash\thinspace\mydateformat{#1end}}}

Here \mydateformat localizes the date fields passed in parameter #1 by transforming them to a particular numeric format with leading zeros. Additional keys like dateera, dateuncertain, and datelabel can also be used to localize other aspects of date handling.

More Examples

For Russian date order (year first), the macro could be adapted:

\newrobustcmd{\mydateformat}[1]{%
  \iffieldundef{#1year}
    {\mkbibnodate{}}
    {\mkyearzeros{\thefield{#1year}}\mkmonthzeros{\thefield{#1month}}\mkdayzeros{\thefield{#1day}}}%
}

And for Chinese date writing a custom numeric format could be introduced:

\newrobustcmd{\mydateformat}[1]{%
  \iffieldundef{#1year}
    {\mkbibnodate{}} 
    {\thefield{#1year}年\thefield{#1month}月\thefield{#1day}日}%  
}

This demonstrates the flexibility enabled by the date localization key and its relatives.

Location-Based Localizations

Printing location information like cities, regions, and countries in ways that conform to local conventions is another important localization task enabled by BibLaTeX keys.

The main entry point here is the location key. It handles printing and formatting locations passed to it:

\DeclareLocalizedFormat{location}{%
  \iffieldundef{location}{}{%
    \bibstring{in}%
    \printtext[location]{#1}}}

\DeclareStyleSourcemap{
  \maps[datatype=bibtex]{
    \map{
      \step[fieldsource=address, match=\regexp{$}, final]
      \step[fieldset=location, origfieldval]
    }
  }
}

The style source mapping here automatically copies the address field to a location field. Then the location format macro can format this location data, while also adding localized strings like "in" before the location.

Additional keys like locationlabel, pageref, bookpagination help localize other location and pagination related formatting.

Location Examples

For abbreviation of US state names, the following could be used:

\DeclareLocalizedFormat{location}{%
  \citylocation{#1}% Print city
  \iflistundef{state}
    {}
    {\addcomma\addspace
     \printtext[state]{#1}}% Print abbreviated state
}

And for generic continental localizations, a mapping like this can help:

\DeclareStyleSourcemap{
  \maps[datatype=bibtex]{
    \map{
      \pertype{book}
      \step[fieldsource=address, match=\regexp{Asia}, replace=\regexp{Asia}]
      \step[fieldset=loccontinent, fieldvalue = Asia]
    }
  }  
}

Which then allows formatting like:

\printtext[loccontinent]{#1}\addcolon\addspace\printtext[location]{#1}

To generate outputs like "Asia: Tokyo"

Extending Localization Capabilities

A key benefit of BibLaTeX's localization keys is that they provide predefined control points for language and region customization. However, unusual use cases may require adjustments beyond what the stock localization keys offer.

Fortunately, the localization system is also extensible to handle more exotic localization requirements. The \verb|\DeclareLocalizedFormat| command can set up new localization keys as needed:

\DeclareLocalizedFormat{mycustomkey}{#1}

These custom keys can then be tailored to a particular localization goal:

\DeclareLocalizedFormat[variant=american]{mycustomkey}{%
  \someamericanformatting{#1}
}

\DeclareLocalizedFormat[variant=french]{mycustomkey}{% 
  \somefrenchformatting{#1}
}

With this approach, essentially any localization feature can be added by the style developer or user. When combined with the \verb|localecode| package option to switch language contexts, even the most complex multilingual publishing workflows can be supported.

Strategies for Rare Localizations

For extremely rare languages or regional formats, creating an entirely custom localization may be overkill. In these cases, fallback strategies can enable partial localization:

Use the "base" localization keys for primary structural elements like dates and names
Add custom keys only for elements requiring localization, not the entire style
Map fields to custom keys, transform contents, and pass back to base keys for printing
Combine locale inheritance in \verb|polyglossia| or \verb|babel| with BibLaTeX localization where possible

With this kind of minimal approach, rare corner cases can still leverage the extensive base support for major languages that BibLaTeX provides.

Localization for Multi-Language Documents

In many document contexts, especially in the humanities and social sciences, citing sources in multiple languages is common. This brings an added complexity for localization.

Fortunately, BibLaTeX provides robust multi-language support through its localization architecture. The language toggling abilities of packages like \verb|polyglossia| can be fully leveraged, allowing mixing citations in English, French, German and more as needed, with style localization happening automatically.

Per-Entry Local Overrides

Even more powerful is the ability to override the localization language on a per-entry basis. For example:

\autocite[french]{frenchreference} \autocite[english]{englishreference}

Will cite the "frenchreference" bibliography entry using French localization conventions, while the "englishreference" will follow English rules. This fine-grained control allows managing complex multilingual documents with ease.

Multiple Language Bibliographies

For documents citing many foreign language sources, grouping entries by language in the bibliography may be desirable. BibLaTeX's filtering and segmentation capabilities support this workflow:

\printbibliography[keyword=french,title={French References}]
\printbibliography[keyword=english,title={English References}]

Assigning languages keywords like "french" on a per-entry basis and then filtering \verb|\printbibliography| by these keywords provides language-specific bibliographies, with localization handled automatically for each subset.

Troubleshooting Localization Errors

In more complex documents, localization inconsistencies can sometimes occur. However, BibLaTeX provides tools to catch and correct many common issues.

Common Problems

Some typical localization failures include:

Name order mixing across languages
Punctuation varying incorrectly
Date formats changing mid-document
Captions not translating

These can arise from language toggle mismatches, incorrectly labeled entries, bugs in style source mappings, or missing locale support in the bibliography style among other factors.

Tools for Diagnosis

To identify localization defects, enabling BibLaTeX's debug mode can help:

\usepackage[debug]{biblatex}

This will trace all localization lookups, helping pinpoint errant keys, missing mappings, or other anomalies.

Additionally, validating localization keys via:

biber --validate_datamodel entrykey

Can check for missing or improper bibliographic data that may trigger localization failures.

Achieving Consistency

Combined with language tagging conventions for entries, selective use of per-entry overrides, and proper localized bibliography printing, most complex multilingual bibliographic workflows can be accommodated and debugged via BibLaTeX's robust localization capabilities.