List of Tables[link]

1. Introduction[link]

When I’m developing a package that provides multilingual support (for example, glossaries) it’s cumbersome trying to work out if the user has requested translations for fixed text. This usually involves checking if babel or translator or polyglossia has been loaded and, if so, what language settings have been used. The result can be a tangled mass of conditional code. The alternative is to tell users to add the language as a document class option, which they may or may not want to do, or to tell them to supply the language settings to every package they load that provides multilingual support, which users are even less likely to want to do.

The tracklang package tries to neaten this up by working out as much of this information as possible for you and providing a command that iterates through the loaded languages. This way, you can just iterate through the list of tracked languages and, for each language, either define the translations or warn the user that there’s no translation for that language.

As from version 1.6.4, tracklang now checks for babel’s \LocaleForEach and, if defined, will use that command to iterate over all languages that have currently been loaded either via package option or using \babelprovide. Note that “lazy loading” a language via \selectlanguage in the document is too late for tracklang to detect.

If polyglossia is loaded, tracklang will check if \xpg@bcp@loaded is defined and, if so, will iterate over that list. Older versions of babel and polyglossia that lack these convenient commands are much harder for tracklang to work with.

The tracklang package works fairly well with translator but will additionally assume the root language was also requested when a dialect is specified. So, for example,

🖹
\usepackage[british]{translator}
\usepackage{tracklang}

\usepackage[british]{translator}
\usepackage[english,british]{tracklang}

If any document class or package options are passed to tracklang, then tracklang won’t bother checking for known language packages. So, if the above example is changed to:

🖹
\documentclass[british]{article}
\usepackage{translator}
\usepackage{tracklang}

🖹
\documentclass[british]{article}
\usepackage[french]{babel}
\usepackage{tracklang}

🖹
\documentclass[es-MX]{article}
\usepackage[spanish]{babel}
\usepackage{tracklang}

Predefined dialects are listed in Tables 1.1, 1.2 & 1.3. These may be passed in the document class options or used in \TrackPredefinedDialect, as illustrated above.

§2 provides brief examples of use for those who want a general overview before reading the more detailed sections. §3 describes generic commands for identifying the document languages. §5 is for package writers who want to add multilingual support to their package and need to know which settings the user has requested through language packages like babel. §6 is for developers of language definition packages who want to help other package writers to detect what languages have been requested.

2. Summary of Use[link]

There are three levels of use:

1. 1.document level (code used by document authors);

2. 2.locale-sensitive package level (code for package authors who need to know what languages or locale the document is using, such as glossaries to translate commands like \descriptionname or datetime2 to provide localised formats or time zone information);

3. 3.language set-up level (code for packages that set up the document languages, such as babel or polyglossia).

2.1. Document Level[link]

Document level use can be divided into generic TeX use (§2.1.1) and LaTeX-specific use (§2.1.2).

2.1.1. Generic TeX[link]

This section is for generic TeX use. The tracklang files are loaded with \input. See §2.1.2 for LaTeX use.

A Unix-like user wants the locale information picked up from the locale environment variable (the tex extension may be omitted):

🖹
\input tracklang.tex % v1.3
\TrackLangFromEnv
% load packages that use tracklang for localisation

A Windows user wants the locale information picked up from the operating system (again the tex extension may be omitted):

🖹
\input texosquery.tex
\input tracklang.tex % v1.3
\TrackLangFromEnv
% load packages that use tracklang for localisation

🖹
\input texosquery.tex % v1.2
\input tracklang.tex % v1.3

\TeXOSQueryLangTag{\langtag}
\TrackLanguageTag{\langtag}
% load packages that use tracklang for localisation

🖹
\input texosquery.tex
\input tracklang.tex % v1.3

\ifx\TeXOSQueryLangTag\undefined
 \TrackLangFromEnv
\else
 \TeXOSQueryLangTag{\langtag}
 \TrackLanguageTag{\langtag}
\fi
% load packages that use tracklang for localisation

A user is writing in Italy in Armenian with a Latin script (Latn) and the arevela variant:

🖹
\input tracklang.tex % v1.3
\TrackLanguageTag{hy-Latn-IT-arevela}
% load packages that use tracklang for localisation

A user is writing in English in the UK:

🖹
\input tracklang.tex
\TrackPredefinedDialect{british}
% load packages that use tracklang for localisation

Find out information about the current language (supplied in \languagename):

🖹
\SetCurrentTrackedDialect{\languagename}
Dialect: \CurrentTrackedDialect.
Language: \CurrentTrackedLanguage.
ISO Code: \CurrentTrackedIsoCode.
Region: \CurrentTrackedRegion.
Modifier: \CurrentTrackedDialectModifier.
Variant: \CurrentTrackedDialectVariant.
Script: \CurrentTrackedDialectScript.
Sub-Lang: \CurrentTrackedDialectSubLang.
Additional: \CurrentTrackedDialectAdditional.
Language Tag: \CurrentTrackedLanguageTag.

🖹
\input tracklang-scripts.tex

🖹
Name: \TrackLangScriptAlphaToName{\CurrentTrackedDialectScript}.
Numeric: 
\TrackLangScriptAlphaToNumeric{\CurrentTrackedDialectScript}.
Direction: 
\TrackLangScriptAlphaToDir{\CurrentTrackedDialectScript}.

🖹
Latin?
\ifx\CurrentTrackedDialectScript\TrackLangScriptLatn
 Yes
\else
 No
\fi

2.1.2. LaTeX[link]

This section is for LaTeX use. See §2.1.1 for generic TeX use.

With newer versions of polyglossia, where \xpg@bcp@loaded is defined, you just need to make sure the languages are set before tracklang is loaded:

🖹
\documentclass{article}
\usepackage{polyglossia}
\setmainlanguage[variant=uk]{english}
% load packages that use tracklang for localisation

🖹
\documentclass[en-GB]{article}
\usepackage{polyglossia}
\setmainlanguage[variant=uk]{english}
% load packages that use tracklang for localisation

For babel users where the supplied babel dialect label is sufficient, and is passed either through the document class or package options, there’s no need to do anything special:

🖹
\documentclass[british,canadien]{article}
\usepackage[T1]{fontenc}
\usepackage{babel}
% load packages that use tracklang for localisation

🖹
\documentclass{article}
\usepackage[T1]{fontenc}
\usepackage[british]{babel}
\babelprovide{canadianfrench}
% load packages that use tracklang for localisation

If the region is important but there’s no babel dialect that represents it, there are several options. The first method is to use the class options recognised by tracklang and the root language labels when loading babel:

🖹
\documentclass[en-IE,ga-IE]{article}
\usepackage[english,irish]{babel}
% load packages that use tracklang for localisation

Another method with babel is to use \TrackLanguageTag and map the new dialect label to the nearest matching \captions〈dialect〉:

🖹
\documentclass{article}

\usepackage{tracklang}% v1.3
\TrackLanguageTag{en-MT}
\SetTrackedDialectLabelMap
 {\TrackLangLastTrackedDialect}{UKenglish}

\usepackage[UKenglish]{babel}
% load packages that use tracklang for localisation

2.2. Locale-Sensitive Packages[link]

Let’s suppose you are developing a package called mypackage.sty or mypackage.tex and you want to find out what languages the document author has requested. (See also: Using tracklang.tex in Packages with Localisation Features.)

Generic TeX use (the tex extension may be omitted):

🖹
\input tracklang.tex

LaTeX use:

🖹
\RequirePackage{tracklang}[2019/11/30]% at least v1.4

(LaTeX) If you want to allow the user to set the locale in the package options:

🖹
\DeclareOption*{\TrackLanguageTag{\CurrentOption}}

🖹
\usepackage[hy-Latn-IT-arevela]{mypackage}

🖹
\DeclareOption*{% 
 \TrackIfKnownLanguage{\CurrentOption}% 
 {% successful
  \PackageInfo{mypackage}{Tracking language `\CurrentOption'}% 
 }% 
 {% failed
  \PackageError{mypackage}% 
  {Unknown language specification `\CurrentOption'}% 
  {You need to supply either a known dialect label 
   or a valid language tag}% 
 }% 
}

If you want to fetch the locale information from the operating system when the user hasn’t requested a language:

🖹
\AnyTrackedLanguages
{}
{% fetch locale information from the operating system
  \ifx\TeXOSQueryLangTag\undefined
    % texosquery v1.2 not available
    \TrackLangFromEnv
  \else
    % texosquery v1.2 available
    \TeXOSQueryLangTag{\langtag}
    \TrackLanguageTag{\langtag}
  \fi
}

Set up the defaults if necessary:

🖹
\def\fooname{Foo}
\def\barname{Bar}

Now load the resource files:

🖹
\AnyTrackedLanguages
{% 
  \ForEachTrackedDialect{\thisdialect}{% 
    \TrackLangRequireDialect{mypackage}{\thisdialect}% 
  }% 
}
{}% no tracked languages, default already set up

Each resource file has the naming scheme 〈prefix〉-〈localeid〉.ldf. In this example, the 〈prefix〉 is mypackage. The 〈localeid〉 part may be the language or dialect label (for example, english or british) or a combination of the ISO language and region codes (for example, en-GB or en or GB). As from version 1.4, 〈localeid〉 may also include the script or variant. (See the definition of \IfTrackedLanguageFileExists below for further details.)

The simplest scheme is to use the root language label (not the dialect label) for the base language settings and use the ISO codes for regional support.

For example, the file mypackage-english.ldf:

🖹
% identify this file:
\TrackLangProvidesResource{english}[2016/10/06 v1.0]

\TrackLangAddToCaptions{% 
  \def\fooname{Foo}% 
  \def\barname{Bar}% 
}

With pre-v1.4 versions of tracklang, the script isn’t included in the file search. If it’s needed then either require at least v1.4 or have a base ldf file that tries to load a version for the particular script (which can be accessed with \CurrentTrackedDialectScript). Here’s an example for a language with different writing systems. The resource file for Serbian mypackage-serbian.ldf:

🖹
% identify file:
\TrackLangProvidesResource{serbian}[2016/10/06 v1.0]

\TrackLangRequestResource{serbian-\CurrentTrackedDialectScript}
{}% file not found, do something sensible here

🖹
\TrackLangProvidesResource{serbian-Latn}[2016/10/06 v1.0]

\TrackLangAddToCaptions{% 
  \def\fooname{...}% provide appropriate Latin translations
  \def\barname{...}% 
}

🖹
\TrackLangProvidesResource{serbian-Cyrl}[2016/10/06 v1.0]

\TrackLangAddToCaptions{% 
  \def\fooname{...}% provide appropriate Cyrillic translations
  \def\barname{...}% 
}

2.3. Language Packages[link]

Let’s suppose now you’re the developer of a package that sets up the language, hyphenation patterns and so on. It would be really helpful to the locale-sensitive packages in §2.2 to know what languages the document author has requested. You can use the tracklang package to identify this information by tracking the requested localisation, so that other packages can have a consistent way of querying it. (See also: Integrating tracklang.tex into Language Packages.)

Generic use:

🖹
\input tracklang

🖹
\RequirePackage{tracklang}[2019/11/30]% v1.4

When a user requests a particular language through your package, the simplest way of letting tracklang know about it is to use \TrackPredefinedDialect or \TrackLanguageTag. For example, if the user requests british, that’s a predefined dialect so you can just do:

🖹
\TrackPredefinedDialect{british}

🖹
\TrackLanguageTag{en-GB}

🖹
\TrackLanguageTag{en-MT}
\SetTrackedDialectLabelMap{\TrackLangLastTrackedDialect}{UKenglish}
\def\captionsUKenglish{% 
  \def\contentsname{Contents}% 
  % ...
}

This now means that \TrackLangAddToHook and \TrackLangRedefHook commands can find your language hooks. You don’t need the map if your dialect label is the same as tracklang’s root language label for that locale. For example:

🖹
\TrackLanguageTag{en-MT}
\def\captionsenglish{% 
  \def\contentsname{Contents}% 
  % ...
}

When the user switches language through commands like \selectlanguage it would be useful to also use \SetCurrentTrackedDialect{〈dialect〉} to make it easier for the document author or locale-sensitive packages to pick up the current locale. The 〈dialect〉 argument may be tracklang’s internal dialect label or the dialect label you assigned with \SetTrackedDialectLabelMap. It may also be the root language label, in which case tracklang will search for the last dialect to be tracked with that language. For example:

🖹
\def\selectlanguage#1{% 
  \SetCurrentTrackedDialect{#1}% 
  % set up hyphenation patterns etc
}

3. Generic Use[link]

For plain TeX you can input tracklang.tex:

🖹
\input tracklang

🖹
\input{tracklang}

The LaTeX package tracklang.sty inputs the generic TeX code in tracklang.tex, but before it does so it defines

\DeclareOption{〈dialect〉}{\TrackPredefinedDialect{〈dialect〉}}

This means that all the predefined languages and dialects (Tables 1.1, 1.2 & 1.3) automatically become package options, so the tracklang.sty package can pick up document class options and add them to tracklang’s internal list of tracked document languages.

As from version 1.6.3, the LaTeX package also has options verbose and noverbose to switch on and off verbose mode. As from version 1.6.5, there are also warn and nowarn settings to switch on (default) and off warnings. This means that these options can be picked up if they are used as document class options or passed to tracklang before it’s first loaded.

If you’re not using LaTeX, package options aren’t available although you can redefine \@tracklang@declareoption to use something analogous to \DeclareOption, if appropriate. Otherwise, the document languages need to be explicitly identified (using any of the following commands) so that tracklang knows about them.

For example:

🖹
\input tracklang
\TrackPredefinedDialect{british}

🖹
\documentclass[british]{article}
\usepackage{tracklang}

Note that it’s impractical to define every possible language and region combination as it would significantly slow the time taken to load tracklang so, after version 1.3, I don’t intend adding any new predefined dialects. As from version 1.3, if you want to track a dialect that’s not predefined by tracklang, then you can use:

• •〈ISO lang〉
• •〈ISO lang〉@〈modifier〉
• •〈ISO lang〉-〈ISO country〉
• •〈ISO lang〉-〈ISO country〉@〈modifier〉

For example:

🖹
\TrackLocale{de-NA@new}

Alternatively, you can use

If you want to first check that 〈tag〉 includes a valid language code, then you can instead use:

For example:

🖹
\TrackLanguageTag{hy-Latn-IT-arevela}
Latn-ME: \TrackIfKnownLanguage{Latn-ME}{success}{fail}.
brazilian: \TrackIfKnownLanguage{brazilian}{success}{fail}.

The datetime2 package assumes that any unknown package option is a language identifier. It could simply do:

\TrackLanguageTag{\CurrentOption}

\TrackIfKnownLanguage{\CurrentOption}
{...}% known language
{\PackageError{...}{...}{...}}

If 〈tag〉 contains a sub-language tag, this will be set as the 639-3 code for the dialect label. Note that this is different to the root language codes which are set using the language label. For example:

🖹
\TrackLanguageTag{zh-cmn-Hans-CN}

🖹
ISO 639-1: \TrackedIsoCodeFromLanguage{639-1}{chinese}.
ISO 639-3: \TrackedIsoCodeFromLanguage{639-3}{zhcmnHansCN}.

Version 1.2 of texosquery provides the command \TeXOSQueryLangTag, which may be used to fetch the operating system’s regional information as a language tag. These commands can be used as follows:

🖹
\input tracklang % v1.3
\input texosquery % v1.2

\TeXOSQueryLangTag{\langtag}
\TrackLanguageTag{\langtag}

Some of the predefined root language options listed in Table 1.2 have an associated region (denoted by ^†). If \TrackLocale is used with just the language ISO code, no region is tracked for that language. For example

🖹
\TrackLocale{manx}

🖹
\TrackLocale{gv}

(New to version 1.3.) There’s a similar command to \TrackLocale that doesn’t take an argument:

Since tracklang is neither able to look up the POSIX locale tables nor interpret file locales, if the result is C or POSIX or starts with a forward slash / then the locale value is treated as empty.

If the operating system locale can’t be obtained from environment variables, then tracklang will use \TeXOSQueryLocale as a fallback if texosquery has been loaded. Since texosquery requires both the shell escape and the Java runtime environment, tracklang doesn’t automatically load it.

Plain TeX example:

🖹
\input texosquery
\input tracklang
\TrackLangFromEnv

〉_
etex --shell-escape 〈filename〉

LaTeX example:

🖹
\usepackage{texosquery}
\usepackage{tracklang}
\TrackLangFromEnv

〉_
pdflatex --shell-escape 〈filename〉

If the locale can’t be determined, there will be warning messages. These can be suppressed using

For example, I have the environment variable LANG set to en_GB.utf8 on my Linux system so instead of

🖹
\TrackPredefinedDialect{british}

🖹
\TrackLangFromEnv

With LaTeX documents I can do

🖹
\documentclass{article}
\usepackage{tracklang}
\TrackLangFromEnv

🖹
\documentclass{article}
\usepackage{tracklang}
\TrackLangFromEnv
\usepackage[useregional]{datetime2}

The \TrackLangFromEnv command also incidentally sets \TrackLangEnv to the value of the environment variable or empty if the query was unsuccessful (for example, the shell escape is unavailable).

If the command:

For example:

🖹
\def\TrackLangEnv{en-GB}
\TrackLangFromEnv

🖹
\TrackLocale{en-GB}

If the shell escape is unavailable (for example, your TeX installation prohibits it), you can set this value when you invoke TeX. For example, if the document file is called myDoc.tex (and it’s in Plain TeX):

〉_
tex "\\def\\TrackLangEnv{$LANG}\\input myDoc"

The \TrackLangFromEnv command also happens to store the component parts of the environment variable value in the following commands. (These aren’t provided by \TrackLocale.) If the information is unavailable, the relevant commands will be set to empty.

The language code is stored in:

The territory (if present) is stored in:

The code-set (if present) is stored in:

The modifier (if present) is stored in:

If you want to query the language environment, but don’t want to track the result, you can just use:

The above queries LC_ALL and, if that is unsuccessful, then queries LANG (before optionally falling back on texosquery). If you want another environment variable tried after LC_ALL and before LANG, you can instead use:

🖹
\TrackLangQueryOtherEnv{LC_MONETARY}

Since this sets \TrackLangEnv, you can use it before \TrackLangFromEnv. For example:

🖹
\TrackLangQueryOtherEnv{LC_MONETARY}
\TrackLangFromEnv

🖹
\ifx\TrackLangEnv\undefined
  \TrackLangQueryOtherEnv{LC_MONETARY}
\fi
\TrackLangFromEnv

It’s also possible to just parse the value of \TrackLangEnv without tracking the result using:

Example (Plain TeX):

🖹
\input tracklang

\def\TrackLangEnv{fr-BE.utf8@euro}

\TrackLangParseFromEnv

Language: \TrackLangEnvLang.
Territory: \TrackLangEnvTerritory.
Codeset: \TrackLangEnvCodeSet.
Modifier: \TrackLangEnvModifier.
Any tracked languages? \AnyTrackedLanguages{Yes}{No}.

Compare this with:

🖹
\input tracklang

\def\TrackLangEnv{fr-BE.utf8@euro}

\TrackLangFromEnv

Language: \TrackLangEnvLang.
Territory: \TrackLangEnvTerritory.
Codeset: \TrackLangEnvCodeSet.
Modifier: \TrackLangEnvModifier.
Any tracked languages? \AnyTrackedLanguages{Yes}{No}.
Tracked dialect(s):% 
\ForEachTrackedDialect{\thisdialect}{\space\thisdialect}.

If \TrackLangFromEnv doesn’t recognise the given language and territory combination, it will define a new dialect and add that.

For example, tracklang doesn’t recognise en-BE, so the sample document below defines a new dialect labelled enBEeuro:

🖹
\input tracklang

\def\TrackLangEnv{en-BE.utf8@euro}

\TrackLangFromEnv

Language: \TrackLangEnvLang.
Territory: \TrackLangEnvTerritory.
Codeset: \TrackLangEnvCodeSet.
Modifier: \TrackLangEnvModifier.
Any tracked languages? \AnyTrackedLanguages{Yes}{No}.
Tracked dialect(s):% 
\ForEachTrackedDialect{\thisdialect}{\space\thisdialect}.

4. Supplementary Packages[link]

In addition to the main tracklang.tex file and tracklang.sty LaTeX wrapper, the tracklang package also provides supplementary files for region and script mappings.

Mappings are established with:

When tracklang-region-codes.tex is input, it can load additional files that provide supplementary mappings.

Plain TeX:

🖹
\input tracklang-scripts

🖹
\usepackage{tracklang-scripts}

This command defines:

See Table A.2 for a summary of all the mappings that are provided by the file tracklang-scripts.tex.

5. Detecting the User’s Requested Languages[link]

The tracklang package tries to track the loaded languages and the option names used to identify those languages. For want of a better term, the language option names are referred to as dialects even if they’re only a synonym for the language rather than an actual dialect. For example, if the user has requested british, the root language label is english and the dialect is british, whereas if the user requested UKenglish, the root language label is english and the dialect is UKenglish. The exceptions to this are the tracklang package options that have been specified in the form 〈iso lang〉-〈iso country〉 (listed in Table 1.2). For example, the package option en-GB behaves as though the user requested the package option british.

If \TrackLocale or \TrackLangFromEnv are used and the locale isn’t recognised a new dialect is created with the label formed from the ISO codes (and modifier, if present). Similarly for \TrackLanguageTag a new dialect is created with a label that’s essentially the language tag without the hyphen separators. For example,

🖹
\TrackLocale{xx-YY}

🖹
\TrackLocale{xx-YY@mod}

🖹
\TrackLanguageTag{xx-Latn-YY}

In addition to the root language label and the dialect identifier, many of the language options also have corresponding ISO codes. In most cases there is an ISO 639-1 or an ISO 639-2 code (or both), and in some cases there is an ISO 3166-1 code identifying the dialect region. Where a language has different ISO 639-2 (T) and 639-2 (B) codes, the “T” version is assumed.

When the tracklang.sty LaTeX package is loaded, it first attempts to find the language options through the package options supplied to tracklang. This means that any languages that have been supplied in the document class options should get identified (provided that the document class has used the standard option declaration mechanism). If no languages have been supplied in this way, tracklang.sty then attempts to identify language settings in the following order:

1. 1.if \LocaleForEach is defined (babel), tracklang will use it to iterate over each dialect label and fetch the associated BCP 47 tag;

2. 2.if \bbl@loaded is defined (babel), tracklang will iterate over each label in that command definition;

3. 3.if \trans@languages is defined (translator), tracklang will iterate over each label in that command definition;

4. 4.if ngerman has been loaded, the ngerman dialect will be tracked;

5. 5.if german has been loaded, the german root language will be tracked;

6. 6.if polyglossia has been loaded:
   1. (a)if \xpg@bcp@loaded has been defined, tracklang will iterate over the BCP 47 tags in that command definition;

   2. (b)if \xpg@loaded has been defined, tracklang will iterate over each language label in that command definition;

   3. (c)tracklang will iterate over all tracklang options and test if the root language has been loaded.

Each identified language and dialect is added to the tracked language and tracked dialect lists. Note that the tracked language and tracked dialect are labels rather than proper nouns. If a dialect label is identical to its root language label, the label will appear in both lists.

You can check whether or not any languages have been detected using:

You can check whether or not any regions have been detected using:

If you want to find out if any of the tracked dialects matches a particular language tag, you can use:

For example (Plain TeX):

🖹
\input tracklang
\TrackLanguageTag{en-826}
Has en-Latn-GB been tracked?
\GetTrackedDialectFromLanguageTag{en-Latn-GB}{\thisdialect}% 
\ifx\thisdialect\empty
 No!
\else
 Yes! Dialect label: \thisdialect.
\fi
\bye

Here’s an example that doesn’t have an exact match, but does have a partial match:

🖹
\input tracklang
\TrackLanguageTag{de-CH-1996}
Has de-DE-1996 been tracked?
\GetTrackedDialectFromLanguageTag{de-DE-1996}{\thisdialect}% 
\ifx\thisdialect\empty
 No!
  \ifx\TrackedDialectClosestSubMatch\empty
    No match on root language.
  \else
    Closest match: \TrackedDialectClosestSubMatch.
  \fi
\else
 Yes! Dialect label: \thisdialect.
\fi
\bye

You can iterate through each tracked dialect using:

You can iterate through each tracked language using:

You can iterate through each tracked region using:

The above for-loops use the same internal mechanism as LaTeX’s \@for loop. Since this isn’t defined by TeX, a similar command (\@tracklang@for) will be defined that works in the same way.

The provided control sequence 〈cs〉 is updated at the start of each iteration to the current element. The loop is terminated when this control sequence is set to \@nil. This special control sequence should never been used as it’s just a marker and isn’t actually defined. If you get an error message stating that \@nil is undefined, then it’s most likely due to a loop control sequence being used outside the loop. This can occur if the loop contains code that isn’t expanded until later. For example, if the loop code includes \AtBeginDocument, you need to ensure that the loop control sequence is expanded before being added to the hook.

You can test if a root language has been detected using:

You can test if a particular dialect has been detected using:

For example:

🖹
\documentclass[british,dutch]{article}

\usepackage{tracklang}

\begin{document}
``english'' \IfTrackedDialect{english}{has}{hasn't} been specified.

``british'' \IfTrackedDialect{british}{has}{hasn't} been specified.

``flemish'' \IfTrackedDialect{flemish}{has}{hasn't} been specified.

``dutch'' \IfTrackedDialect{dutch}{has}{hasn't} been specified.

``english'' or an English variant 
\IfTrackedLanguage{english}{has}{hasn't} been specified.
\end{document}

You can find the root language label for a given tracked dialect using:

You can find the tracked dialects from a given root language using:

You can test if a language or dialect has a corresponding ISO code using:

Alternatively, you can test if a particular ISO code has been defined using:

You can fetch the language (or dialect) label associated with a given ISO code using:

You can fetch the ISO code for a given code type using:

The above commands do nothing in the event of an unknown code or code type, so if you accidentally get the wrong code type, you won’t get an error. If you’re unsure of the code type, you can use the following commands:

The \Get… commands below are designed to be expandable. If the supplied 〈dialect〉 is unrecognised they expand to empty. Remember that the dialect must first be identified as a tracked language for it to be recognised.

As from v1.3, the language tag for a given dialect can be obtained using:

As from v1.3, each tracked dialect may also have an associated modifier, which can be fetched using:

You can test if a dialect has an associated modifier using:

For example:

🖹
\documentclass[british,francais,american,canadian,canadien,dutch]{article}

\usepackage{tracklang}

\begin{document}
Languages:
\ForEachTrackedLanguage{\ThisLanguage}{\ThisLanguage\space
(ISO \TwoLetterIsoLanguageCode: 
``\TrackedIsoCodeFromLanguage
    {\TwoLetterIsoLanguageCode}{\ThisLanguage}''). }

Dialects:
\ForEachTrackedDialect{\ThisDialect}{\ThisDialect\space 
(\IfTrackedLanguageHasIsoCode
  {\TwoLetterIsoCountryCode}{\ThisDialect}% 
 {ISO \TwoLetterIsoCountryCode: 
  ``\TrackedIsoCodeFromLanguage
      {\TwoLetterIsoCountryCode}{\ThisDialect}''} {no specific region};
root: \TrackedLanguageFromDialect{\ThisDialect}). }

Language for ISO \TwoLetterIsoCountryCode\ ``GB'':
\TrackedLanguageFromIsoCode
  {\TwoLetterIsoCountryCode}{GB}.

Language for ISO \TwoLetterIsoCountryCode\ ``CA'': 
\TrackedLanguageFromIsoCode
  {\TwoLetterIsoCountryCode}{CA}.

Country ISO \TwoLetterIsoCountryCode\ code for ``canadian'':
\TrackedIsoCodeFromLanguage
  {\TwoLetterIsoCountryCode}{canadian}.
\end{document}

As from v1.3, each tracked dialect may also have an associated variant, which can be fetched using:

You can test if a dialect has an associated variant using:

As from v1.3, each tracked dialect may also have an associated script, which can be fetched using:

You can test if a dialect has an associated script using:

Note that the script should be a recognised four-letter ISO 15924 code, such as Latn or Cyrl. If a dialect doesn’t have an associated script then the default for the root language should be assumed. For example, Latn for English dialects or Cyrl for Russian dialects. The default script for known languages can be obtained using:

There’s a convenient expandable command for testing the script:

The supplementary package tracklang-scripts provides some additional commands relating to writing systems, including commands in the form \TrackLangScript〈Code〉 where 〈Code〉 is the ISO 15924 four-letter code. If the dialect doesn’t have an associated script, 〈false〉 is done. This package isn’t loaded automatically, so you’ll need to explicitly load it. The generic code is in tracklang-scripts.tex:

🖹
\input tracklang-scripts

🖹
\usepackage{tracklang-scripts}

For example, the following defines a command to check if the given dialect should use a Latin script:

🖹
\input tracklang-scripts
\def\islatin#1#2#3{% 
  \IfTrackedDialectIsScriptCs{#1}{\TrackLangScriptLatn}{#2}{#3}% 
}

As from v1.3, each tracked dialect may also have a sub-language identifier (for example, arevela), which can be fetched using:

You can test if a dialect has an associated sub-tag using:

As from v1.3, each tracked dialect may also have additional information, which can be fetched using:

You can test if a dialect has additional information using:

Most packages that implement multilingual support have a set of language definition files for each supported language or dialect. It may be that only the root language is needed, if there are no variations between that language’s dialect (for the purposes of that package), or it may be that separate definition files are required for each dialect. However it can be awkward trying to map the requested dialect or language label to the file name. Should, say, the file containing the French code be called 〈prefix〉-french-〈suffix〉 or 〈prefix〉-frenchb-〈suffix〉 or 〈prefix〉-francais-〈suffix〉? Should, say, the file containing the British English code be called 〈prefix〉-british-〈suffix〉 or 〈prefix〉-UKenglish-〈suffix〉? If you want to modularise the language support for your package so that each language module has a different maintainer will the maintainers know what tag to use for their language?

To help with this, tracklang provides:

Sometimes the dialect label can cause a problem, especially if it happens to be identical to the root label. The solo region code check may also be problematic, so the following analoguous commands are also provided.

There’s a convenient shortcut command new to version 1.3:

There are analogous commands

The optional argument 〈load code〉 is the code that actually inputs the required file. This defaults to

🖹
\TrackLangRequireResource{\CurrentTrackedTag}

The \IfTrackedLanguageFileExists command sets up the current tracked dialect with:

\SetCurrentTrackedDialect{〈dialect〉}

\IfTrackedLanguageFileExists behaves as follows:

• •If no dialect with the given label has been detected, the condition evaluates to false and \CurrentTrackedTag is empty.

• •If a dialect with the given label has been detected, then:
  • –For each possible 〈localeid〉 in an ordered set of tags determined by the dialect label (see below), the first file matching 〈prefix〉〈localeid〉〈suffix〉 that’s found on TeX’s path results in the condition evaluating to true and \CurrentTrackedTag is set to the current 〈localeid〉 in the set. The rest of the set of possible values of 〈localeid〉 is skipped.

  • –If no file matching 〈prefix〉〈localeid〉〈suffix〉 is found on TeX’s path, then the condition evaluates to false and \CurrentTrackedTag is set to the final 〈localeid〉 in the set (the language label).

The ordered set of possible values of 〈localeid〉 is determined from the given dialect.

1. 1.〈localeid〉 is just the value of \CurrentTrackedLanguageTag.

2. 2.〈localeid〉 is just the dialect label. This step is omitted with \IfTrackedLanguageFileExistsOmitDialectLabel and \IfTrackedLanguageFileExistsOmitDialectLabelOmitOnlyRegion.

3. 3.〈localeid〉 is 〈ISO 639-1〉-〈sublang〉-〈script〉-〈region〉.

4. 4.〈localeid〉 is 〈ISO 639-1〉-〈script〉-〈region〉.

5. 5.〈localeid〉 is 〈ISO 639-1〉-〈sublang〉-〈region〉 (if there’s no script or if the script is the default for the given language). 〈ISO 639-1〉-〈region〉 (if there’s no script or if the script is the default for the given language).

6. 6.〈localeid〉 is 〈ISO 639-1〉-〈sublang〉-〈script〉.

7. 7.〈localeid〉 is 〈ISO 639-1〉-〈script〉.

8. 8.〈localeid〉 is 〈ISO 639-1〉-〈sublang〉.

9. 9.〈localeid〉 is just 〈ISO 639-1〉.

10. 10.〈localeid〉 is 〈ISO 639-2〉-〈sublang〉-〈script〉-〈region〉.

11. 11.〈localeid〉 is 〈ISO 639-2〉-〈script〉-〈region〉.

12. 12.〈localeid〉 is 〈ISO 639-2〉-〈sublang〉-region (if there’s no script or if the script is the default for the given language). 〈ISO 639-2〉-〈region〉 (if there’s no script or if the script is the default for the given language).

13. 13.〈localeid〉 is 〈ISO 639-2〉-〈sublang〉-〈script〉.

14. 14.〈localeid〉 is 〈ISO 639-2〉-〈script〉.

15. 15.〈localeid〉 is 〈ISO 639-2〉-〈sublang〉.
16. 16.〈localeid〉 is just 〈ISO 639-2〉.

17. 17.〈localeid〉 is 〈ISO 639-3〉-〈sublang〉-〈script〉-〈region〉.

18. 18.〈localeid〉 is 〈ISO 639-3〉-〈script〉-〈region〉.

19. 19.〈localeid〉 is 〈ISO 639-3〉-〈sublang〉-〈region〉 (if there’s no script or if the script is the default for the given language). 〈ISO 639-3〉-〈region〉 (if there’s no script or if the script is the default for the given language).

20. 20.〈localeid〉 is 〈ISO 639-3〉-〈sublang〉-〈script〉.

21. 21.〈localeid〉 is 〈ISO 639-3〉-〈script〉.

22. 22.〈localeid〉 is 〈ISO 639-3〉-〈sublang〉.

23. 23.〈localeid〉 is just 〈ISO 639-3〉.

24. 24.〈localeid〉 is just 〈region〉. This step is omitted with \IfTrackedLanguageFileExistsOmitOnlyRegion and \IfTrackedLanguageFileExistsOmitDialectLabelOmitOnlyRegion.

25. 25.〈localeid〉 is 〈ISO 639-1〉-〈sublang〉-〈variant〉 or 〈ISO 639-1〉-〈variant〉 if 〈sublang〉 is missing.

26. 26.〈localeid〉 is 〈ISO 639-2〉-〈sublang〉-〈variant〉 or 〈ISO 639-2〉-〈variant〉 if 〈sublang〉 is missing.

27. 27.〈localeid〉 is 〈ISO 639-3〉-〈sublang〉-〈variant〉 or 〈ISO 639-3〉-〈variant〉 if 〈sublang〉 is missing.

28. 28.〈localeid〉 is just the value of \CurrentTrackedLanguage (the root language label).

For example (pre v1.3):

🖹
\AnyTrackedLanguages
{% 
 \ForEachTrackedDialect{\ThisDialect}% 
 {% 
  % try to load the language file for this dialect
  \IfTrackedLanguageFileExists{\ThisDialect}% 
  {mypackage-}% file prefix
  {.ldf}% file suffix
  {\input mypackage-\CurrentTrackedTag.ldf}% file found
  {% file not found
    \PackageWarning{mypackage}
      {No support for language `\ThisDialect'}% 
  }% 
 }% 
}
{% no languages detected so use defaults
}

🖹
\AnyTrackedLanguages
{% 
 \ForEachTrackedDialect{\ThisDialect}% 
 {% 
  % try to load the language file for this dialect
  \TrackLangRequireDialect{mypackage}{\ThisDialect}% 
 }% 
}
{% no languages detected so use defaults
}

If, for example, \ThisDialect is british, then the file search will be in the order:

1. 1.mypackage-en-GB.ldf (language tag)
2. 2.mypackage-british.ldf (dialect label)

3. 3.mypackage-en-Latn-GB.ldf (639-1 language code, script, region)
4. 4.mypackage-en-GB.ldf (639-1 language code, region)
5. 5.mypackage-en-Latn.ldf (639-1 language code, script)
6. 6.mypackage-en.ldf (639-1 language code)

7. 7.mypackage-eng-Latn-GB.ldf (639-2 language code, script, region)
8. 8.mypackage-eng-GB.ldf (639-2 language code, region)
9. 9.mypackage-eng-Latn.ldf (639-2 language code, script)
10. 10.mypackage-eng.ldf (639-2 language code)

11. 11.mypackage-GB.ldf (region)
12. 12.mypackage-english.ldf (language label)

If, for example, \ThisDialect is naustrian, then the file search will be in the order:

1. 1.mypackage-de-AT-1996.ldf (language tag)
2. 2.mypackage-naustrian.ldf (dialect label)

3. 3.mypackage-de-Latn-AT.ldf (639-1 language code, script, region)
4. 4.mypackage-de-AT.ldf (639-1 language code, region)
5. 5.mypackage-de-Latn.ldf (639-1 language code, script)
6. 6.mypackage-de.ldf (639-1 language code)

7. 7.mypackage-deu-Latn-AT.ldf (639-2 language code, script, region)
8. 8.mypackage-deu-AT.ldf (639-2 language code, region)
9. 9.mypackage-deu-Latn.ldf (639-2 language code, script)
10. 10.mypackage-deu.ldf (639-2 language code)

11. 11.mypackage-AT.ldf (region)

12. 12.mypackage-de-1996.ldf (639-1 language code, variant)
13. 13.mypackage-deu-1996.ldf (639-2 language code, variant)

14. 14.mypackage-german.ldf (language label)

If, for example, \ThisDialect is francais, then the file search will be in the order:

1. 1.mypackage-fr.ldf (language tag)
2. 2.mypackage-francais.ldf (dialect label)
3. 3.mypackage-fr-Latn.ldf (639-1 language code, script)
4. 4.mypackage-fr.ldf (639-1 language code)
5. 5.mypackage-fra-Latn.ldf (639-2 language code, script)
6. 6.mypackage-fra.ldf (639-2 language code)
7. 7.mypackage-french.ldf (language)

1. 1.mypackage-fr.ldf (language tag)
2. 2.mypackage-french.ldf (dialect label)
3. 3.mypackage-fr-Latn.ldf (639-1 language code, script)
4. 4.mypackage-fr.ldf (639-1 language code)
5. 5.mypackage-fra-Latn.ldf (639-2 language code, script)
6. 6.mypackage-fra.ldf (639-2 language code)
7. 7.mypackage-french.ldf (language)

If the dialect label is identical to the root language label then it means that all associated information is the default for that language. For example, in the above case of french, the script is Latn and the region is unspecified. The root language label can therefore be used as the fallback in the event of no other match but for the specific case where the dialect is identical to the root language then all unnecessary file name checks can be skipped.

If you’re only providing support for the root languages (pre v1.3):

🖹
\AnyTrackedLanguages
{% 
 \ForEachTrackedLanguage{\ThisLanguage}% 
 {% try to load the language file for this root language
   \IfTrackedLanguageFileExists{\ThisLanguage}% 
   {mypackage-}% file prefix
   {.ldf}% file suffix
   {\input mypackage-\CurrentTrackedTag.ldf}% file found
   {% file not found
     \PackageWarning{mypackage}{No support for language
      `\ThisLanguage'}% 
   }% 
 }% 
}
{% no languages detected so use defaults
}

🖹
\AnyTrackedLanguages
{% 
 \ForEachTrackedLanguage{\ThisLanguage}% 
 {% try to load the language file for this root language
   \TrackLangRequireDialect{mypackage}{\ThisLanguage}% 
 }% 
}
{% no languages detected so use defaults
}

The following \TrackLang…Resource… commands may only be used in resource files that are loaded using \TrackLangRequireDialect. An error will occur if the file is input through some other method.

Within the resource file 〈pkgname〉-〈localeid〉.ldf, you can identify the file using (new to version 1.3):

If \ProvidesFile is defined (through the LaTeX kernel) this is used, otherwise a simplified generic alternative is used that’s suitable for other TeX formats.

The resource file can load another resource file 〈pkgname〉-〈tag〉.ldf, using (new to version 1.3):

🖹
% (In file foo-en-GB.ldf)
% Declare this regional file:
\TrackLangProvidesResource{en-GB}
% load root language file foo-english.ldf:
\TrackLangRequireResource{english}

It may be that you want to load a file depending on the input encoding. The inputenc package defines \inputencodingname, but this is only used with pdfLaTeX. To avoid repeated tests to determine whether or not \inputencodingname has been defined, you can use:

🖹
\InputIfFileExists{foo-\TrackLangEncodingName.ldf}
{% support available for the document encoding
}
{% no support for the document encoding
}

If you require the resource file and want to perform 〈code1〉 if it’s loaded at this point or 〈code2〉 if it’s already been loaded then you can use:

If you want to load a resource file if it exists (without an error if it doesn’t exist), then you can use

The above restriction on the resource files loaded through \TrackLangRequireDialect, and the fact that it internally uses \IfTrackedLanguageFileExists, means that commands like \CurrentTrackedLanguage or \CurrentTrackedDialect may be used in those files. This means that the name of the captions hook can be obtained through them. (Remember that the file foo-en-GB.ldf might have been loaded with, say, the british dialect or with the synonymous UKenglish dialect or with a dialect label that doesn’t have a corresponding caption hook, such as enGBLatn.)

The polyglossia package has language caption hooks in the form \captions〈language〉 (where 〈language〉 is the root language label) whereas babel has dialect captions hooks in the form \captions〈dialect〉 (where 〈dialect〉 is the dialect label). This leads to a rather cumbersome set of conditionals:

\ifcsundef{captions\CurrentTrackedLanguage}
{% 
  \ifcsundef{captions\CurrentTrackedDialect}% 
  {}% 
  {% 
    \csgappto{captions\CurrentTrackedDialect}{% 
      % code to append to hook
    }% 
  }% 
}% 
{% 
  \csgappto{captions\CurrentTrackedLanguage}{% 
    % code to append to hook
  }% 
}
% do code now to initialise

Instead, tracklang provides a command to perform this set of conditionals using generic code:

Note that this command is enabled through \TrackLangRequireDialect so should only be used inside resource files.

Since captions is a commonly used hook type, there’s a shortcut command provided:

\TrackLangAddToHook{〈code〉}{captions}

There may be some hooks, such as \date〈dialect〉, that need redefining rather than appending to, so there’s an analogous command:

Note that no expansion is performed on 〈code〉 when appending or redefining a hook.

5.1. Examples[link]

The examples in this section illustrate the above commands.

5.1.1. animals.sty[link]

This example is for a trivial package called animals.sty that defines three textual commands: \catname, \dogname and \ladybirdname. The default values are: “cat”, “dog” and “bishy-barney-bee”.¹ The supported languages are defined in files animals-〈localeid〉.ldf.

Here’s the code for animals.sty:

🖹
% Example package animals.sty
\NeedsTeXFormat{LaTeX2e}
\ProvidesPackage{animals}

\RequirePackage{tracklang}[2019/11/30]% v1.4

% Any undeclared options are language settings:

\DeclareOption*{% 
 \TrackIfKnownLanguage{\CurrentOption}% 
 {% successful
  \PackageInfo{animals}{Tracking language `\CurrentOption'}% 
 }% 
 {% failed
   \PackageError{animals}% 
   {Unknown language specification `\CurrentOption'}% 
   {You need to supply either a known dialect label 
    or a valid language tag}% 
 }% 
}

\ProcessOptions

% Default definitions
\newcommand\catname{cat}
\newcommand\dogname{dog}
\newcommand\ladybirdname{bishy-barney-bee}

\AnyTrackedLanguages
{% 
  \ForEachTrackedDialect{\this@dialect}{% 
    \TrackLangRequireDialect{animals}{\this@dialect}% 
  }% 
}
{% no tracked languages, default already set up
}

\endinput

🖹
\input tracklang

\TrackLangFromEnv

% Default definitions
\def\catname{cat}
\def\dogname{dog}
\def\ladybirdname{bishy-barney-bee}

\AnyTrackedLanguages
{% 
  \ForEachTrackedDialect{\thisdialect}{% 
    \TrackLangRequireDialect{animals}{\thisdialect}% 
  }% 
}
{% no tracked languages, default already set up
}

🖹
\newcommand*{\RequireAnimalsDialect}[1]{% 
  \TrackLangRequireDialect{animals}{#1}% 
}

🖹
\ForEachTrackedDialect{\this@dialect}{% 
  \RequireAnimalsDialect\this@dialect
}% 

The animals-english.ldf file valid for both the Plain TeX and LaTeX formats contains:

🖹
\TrackLangProvidesResource{english}

\def\englishanimals{% 
  \def\catname{cat}% 
  \def\dogname{dog}% 
  \def\ladybirdname{bishy-barney-bee}% 
}

\TrackLangAddToCaptions{\englishanimals}

🖹
\TrackLangProvidesResource{en-GB}
\TrackLangRequireResource{english}

\def\enGBanimals{% 
  \englishanimals
  \def\ladybirdname{ladybird}% 
}
\TrackLangAddToCaptions{\enGBanimals}

🖹
\TrackLangProvidesResource{en-US}
\TrackLangRequireResource{english}

\def\enUSanimals{% 
  \englishanimals
  \def\ladybirdname{ladybug}% 
}
\TrackLangAddToCaptions{\enUSanimals}

🖹
\TrackLangProvidesResource{german}

\def\germananimals{% 
  \def\catname{Katze}% 
  \def\dogname{Hund}% 
  \def\ladybirdname{Marienk\"afer}% 
}

\TrackLangAddToCaptions{\germananimals}

This means that if babel or polyglossia are loaded, the redefinitions are automatically performed whenever the language is changed, but if there’s no caption mechanism the user can switch the fixed names using the \…animals commands.

Here’s an example LaTeX document that doesn’t have any caption hooks:

🖹
\documentclass[english,german]{article}

\usepackage{animals}

\begin{document}
\englishanimals

\catname.
\dogname.
\ladybirdname.

\germananimals

\catname.
\dogname.
\ladybirdname.
\end{document}

🖹
\documentclass[american,german,british]{article}

\usepackage{babel}
\usepackage{animals}

\begin{document}
\selectlanguage{american}

\catname.
\dogname.
\ladybirdname.

\selectlanguage{german}

\catname.
\dogname.
\ladybirdname.

\selectlanguage{british}

\catname.
\dogname.
\ladybirdname.
\end{document}

There is some redundancy with the above resource files. Consider the babel example above. The american dialect is the first option, so in that case animals-en-US.ldf is loaded followed by animals-english.ldf. This means that the \captionsamerican hook now includes