% arara: lualatex
% arara: bib2gls: { group: on, options: [ "--replace-quotes" ] }
% arara: lualatex
% arara: bib2gls: { group: on, options: [ "--replace-quotes" ] } if found ("log", "Glossary entry `sym.")
% arara: lualatex
% arara: lualatex if found ("log", "Rerun to")

\documentclass[titlepage=false,oneside,
 fontsize=12pt,captions=tableheading]{scrbook}

\usepackage
 [
  floats,
  %debug=showwrgloss
 ]
 {nlctuserguide}

\usepackage{glossary-table}

\glsxtrnewgls{opt.envvar.}{\envvar}
\defsemanticcmd[style2]{\envvarfmt}{\texttt}{}
\defsemanticcmd[style1]{\langtagfmt}{\texttt}{}

\glsaddstoragekey{dialect}{}{\dialect}
\glsaddstoragekey{isotag}{}{\isotag}
\glsaddstoragekey{langtag}{}{\langtag}
\glsxtrprovidestoragekey{tags}{}{}
\glsxtrprovidestoragekey{region}{}{}
\glsaddstoragekey{numeric}{}{\numerictag}
\glsxtrprovidestoragekey{alpha3}{}{}

\newcommand{\optisotag}[1]{\isotag{opt.#1}}
\newcommand{\iso}[1]{\glslink{opt.#1}{\optfmt{\optisotag{#1}}}}
\newcommand{\numericcode}[1]{\glslink{opt.#1}{\glsxtrusefield{opt.#1}{numeric}}}

\newcommand{\tklscript}[1]{\glslink{TrackLangScriptCode}{\csfmt{TrackLangScript#1}}}
\newcommand{\tklcaptions}[1]{\glslink{captionsdialect}{\csfmt{captions#1}}}
\newcommand{\tkldate}[1]{\glslink{datedialect}{\csfmt{date#1}}}

\newcommand{\ldf}[2]{%
 \glslink{file.prefix-localeid.ldf}{\filefmt{#1\dhyphen #2.ldf}}}
\newcommand{\localefile}[1]{%
 \glslink{file.prefix-localeid.ldf}{\metafilefmt{#1\dhyphen}{localeid}{.ldf}}}
\newcommand{\localemetafile}[1]{%
 \glslink{file.prefix-localeid.ldf}{\metametafilefmt{}{#1}{\dhyphen}{localeid}{.ldf}}}
\newcommand{\localemetametafile}[2]{%
 \glslink{file.prefix-localeid.ldf}{\metametafilefmt{}{#1}{\dhyphen}{#2}{.ldf}}}

\newcommand{\fnregion}{\fnsym*{2}}

\renewcommand{\filetag}[1]{}

\renewcommand{\nlctuserguidecustomentryaliases}{%
  isolangregion=index,
  rootlang=index,
  noniso=index,
  isocode=index,
  region=index,
  script=index
}

\nlctuserguidegls[selection=all]
{
  \def\genvvar#1#2{%
   \glsbibwriteentry{option}{opt.envvar.#1}{%
    \field{name}{\envvarfmt{#1}}\parent{idx.envvar}#2}}%
  \gidxpl{envvar}{\field{text}{environment variable}}
  % predefined ISO language-region tags
  % \gisolangtag{xx}{XX}{dialect}{options}
  \def\gisolangtag#1#2#3#4{%  
   \glsbibwriteentry{isolangregion}{opt.#1-#2}{%
    \name{\optfmt{#1-#2}}%
    \field{langtag}{#1}\field{region}{#2}%
    \field{isotag}{#1-#2}%
    \field{dialect}{#3}#4}%
  }%
  % \gisolangtagwithvar{xx}{XX}{variant}{dialect}{options}
  \def\gisolangtagwithvar#1#2#3#4#5{%  
   \glsbibwriteentry{isolangregion}{opt.#1-#2-#3}{%
    \name{\optfmt{#1-#2-#3}}%
    \field{langtag}{#1}\field{region}{#2}%
    \field{isotag}{#1-#2-#3}%
    \field{dialect}{#4}#5}%
  }%
  % predefined root language labels
  % \grootlangtag{language}{iso tag}{options}
  \def\grootlangtag#1#2#3{%  
   \glsbibwriteentry{rootlang}{opt.#1}{%
    \name{\optfmt{#1}}%
    \field{dialect}{#1}%
    \field{langtag}{#2}%
    \field{isotag}{#2}#3}%
   \glsbibwriteentry{isocode}{opt.#2}{\name{\optfmt{#2}}\field{alias}{opt.#1}}%
  }%
  % \grootlangsametag{language}{options}
  \def\grootlangsametag#1#2{%  
   \glsbibwriteentry{rootlang}{opt.#1}{%
    \name{\optfmt{#1}}%
    \field{dialect}{#1}%
    \field{langtag}{#1}%
    \field{isotag}{#1}#2}%
  }%
  % \grootlangtagwithreg{language}{lang}{region}{options}
  \def\grootlangtagwithreg#1#2#3#4{%  
   \glsbibwriteentry{rootlang}{opt.#1}{%
    \field{name}{\optfmt{#1}\fnregion}
    \field{text}{\optfmt{#1}}
    \field{region}{#3}
    \field{dialect}{#1}%
    \field{langtag}{#2}
    \field{isotag}{#2-#3}#4}%
   \glsbibwriteentry{isocode}{opt.#2}{\name{\optfmt{#2}}\field{alias}{opt.#1}}%
  }
  % predefined non-iso dialects
  % \gdialecttag{dialect}{tag}{options}
  \def\gdialecttag#1#2#3{%  
   \glsbibwriteentry{noniso}{opt.#1}{%
    \name{\optfmt{#1}}%
    \field{dialect}{#1}%
    \field{isotag}{\optisotag{#2}}%
    \field{tags}{\optfmt{\optisotag{#2}}}#3}%
  }%
  % \gdialecttagsuppl{dialect}{tag}{suppl}{options}
  \def\gdialecttagsuppl#1#2#3#4{%  
   \glsbibwriteentry{noniso}{opt.#1}{%
    \name{\optfmt{#1}}%
    \field{dialect}{#1}%
    \field{isotag}{\optisotag{#2}-#3}%
    \field{tags}{\optfmt{\optisotag{#2}-#3}}#4}%
  }%
  % \gdialecttagwithmap{dialect}{tag}{mapped}{options}
  \def\gdialecttagwithmap#1#2#3#4{%  
   \glsbibwriteentry{noniso}{opt.#1}{%
    \field{dialect}{#1}%
    \field{isotag}{\optisotag{#2}}%
    \field{tags}{\optfmt{\optisotag{#2}} / \optfmt{#3}}#4}%
  }%
  % \gdialecttagsupplwithmap{dialect}{tag}{suppl}{mapped}{options}
  \def\gdialecttagsupplwithmap#1#2#3#4#5{%  
   \glsbibwriteentry{noniso}{opt.#1}{%
    \name{\optfmt{#1}}%
    \field{dialect}{#1}%
    \field{isotag}{\optisotag{#2}-#3}%
    \field{tags}{\optfmt{\optisotag{#2}-#3} / \opt{#4}}#5}%
  }%
  % \gdialecttagwithreg{dialect}{lang}{region}{options}
  \def\gdialecttagwithreg#1#2#3#4{%  
   \glsbibwriteentry{noniso}{opt.#1}{%
    \field{name}{\optfmt{#1}\fnregion }
    \field{text}{\optfmt{#1}}
    \field{region}{#3}
    \field{dialect}{#1}%
    \field{isotag}{\langtag{opt.#2}-#3}%
    \field{tags}{\optfmt{\langtag{opt.#2}-#3}}#4
   }%
  }%
  % \gdialecttagwithmapandreg{dialect}{tag}{region}{mapped}{options}
  \def\gdialecttagwithmapandreg#1#2#3#4#5{%  
   \glsbibwriteentry{noniso}{opt.#1}{%
    \field{name}{\optfmt{#1}\fnregion }
    \field{text}{\optfmt{#1}}
    \field{region}{#3}
    \field{dialect}{#1}%
    \field{isotag}{\optisotag{#2}-#3}%
    \field{tags}{\optfmt{\langtag{opt.#2}-#3} / \opt{#4}}#5}%
  }%
  % \gregion{numeric}{2-alpha}{3-alpha}{options}
  \def\gregion#1#2#3#4{%
   \glsbibwriteentry{region}{opt.#2}{%
     \field{name}{\optfmt{#2}}
     \field{numeric}{#1}\field{alpha3}{#3}
     #4}%
  }%
  % \gscript{alpha}{numeric}{name}{direction}{parent}{options}
  \def\gscript#1#2#3#4#5#6{%
   \glsbibwriteentry{script}{opt.#1}{%
     \field{name}{\optfmt{#1}}
     \field{numeric}{#2}\field{user2}{#4}\field{description}{#3}
     #6}%
  }%
  % COMMANDS
  % \AnyTrackedLanguages
  \gcmd{Any\-Track\-ed\-Lan\-guages}
  {
    \providedby{\file{tracklang.tex} v1.0+}
    \syntax{\margm{true}\margm{false}}
    \desc{expands to \meta{true} if there are any tracked languages,
    otherwise expands to \meta{false}}
  }
  % \IfTrackedLanguage
  \gcmd{If\-Track\-ed\-Lan\-guage}
  {
    \providedby{\file{tracklang.tex} v1.0+}
    \syntax{\margm{language-label}\margm{true}\margm{false}}
    \desc{does \meta{true} if the language identified by
    \meta{language-label} has been tracked,
     otherwise does \meta{false}}
  }
  % \IfTrackedDialect
  \gcmd{If\-Track\-ed\-Di\-alect}
  {
    \providedby{\file{tracklang.tex} v1.0+}
    \syntax{\margm{dialect-label}\margm{true}\margm{false}}
    \desc{does \meta{true} if the dialect identified by
    \meta{dialect-label} has been tracked,
     otherwise does \meta{false}}
  }
  % \AnyTrackedRegions
  \gcmd{Any\-Track\-ed\-Regions}
  {
    \providedby{\file{tracklang.tex} v1.6.3+}
    \syntax{\margm{true}\margm{false}}
    \desc{expands to \meta{true} if there are any tracked regions,
    otherwise expands to \meta{false}}
  }
  % \IfTrackedLanguageFileExists
  \gcmd{If\-Track\-ed\-Lan\-guage\-File\-Exists}
  {
    \providedby{\file{tracklang.tex} v1.0+}
    \syntax{\margm{dialect}\margm{prefix}\margm{suffix}\margm{true
code}\margm{false code}}
    \desc{does \code{\gls{SetCurrentTrackedDialect}\margm{dialect}} 
    and if the dialect is recognised, then determines if the file
    \filefmt{\meta{prefix}\meta{tag}\meta{suffix}} exists. If it does,
    \gls{CurrentTrackedTag} is set to \meta{tag} and \meta{true} is
    done, otherwise \meta{false} is done}
  }
  % \IfTrackedLanguageFileExistsOmitDialectLabel
  \gcmd{If\-Track\-ed\-Lan\-guage\-File\-Exists\-Omit\-Dialect\-Label}
  {
    \providedby{\file{tracklang.tex} v1.6.3+}
    \syntax{\margm{dialect}\margm{prefix}\margm{suffix}\margm{true
code}\margm{false code}}
    \desc{as \gls{IfTrackedLanguageFileExists} but skips the dialect
label check. Note that if the dialect label happens to be the same
as the root label, it will still be checked but at the end instead
of near the start}
  }
  % \IfTrackedLanguageFileExistsOmitDialectLabelOmitOnlyRegion
  \gcmd{If\-Track\-ed\-Lan\-guage\-File\-Exists\-Omit\-Dialect\-Label\-Omit\-Only\-Region}
  {
    \providedby{\file{tracklang.tex} v1.6.3+}
    \syntax{\margm{dialect}\margm{prefix}\margm{suffix}\margm{true
code}\margm{false code}}
    \desc{as \gls{IfTrackedLanguageFileExists} but skips the dialect
label check and just the region code check. Note that if the 
dialect label happens to be the same as the root label, it will 
still be checked but at the end instead of near the start}
  }
  % \IfTrackedLanguageFileExistsOmitOnlyRegion
  \gcmd{If\-Track\-ed\-Lan\-guage\-File\-Exists\-Omit\-Only\-Region}
  {
    \providedby{\file{tracklang.tex} v1.6.3+}
    \syntax{\margm{dialect}\margm{prefix}\margm{suffix}\margm{true
code}\margm{false code}}
    \desc{as \gls{IfTrackedLanguageFileExists} but skips the solo 
    region code check}
  }
  % \CurrentTrackedTag
  \gcmd{Current\-Track\-ed\-Tag}
  {
    \providedby{\file{tracklang.tex} v1.0+}
    \desc{expands to the current tracked tag}
  }
  % \ifTrackLangShowWarnings
  \gcond{if\-Track\-Lang\-Show\-Warnings}
  {
    \initval{\cmd{iftrue}}
    \providedby{\file{tracklang.tex} v1.3+}
    \desc{conditional that indicates whether or not to show warnings}
  }
  % \TrackLangShowWarningsfalse
  \gcmd{Track\-Lang\-Show\-Warnings\-false}
  {
    \providedby{\file{tracklang.tex} v1.3+}
    \desc{sets \gls{ifTrackLangShowWarnings} to false}
  }
  % \TrackLangShowWarningstrue
  \gcmd{Track\-Lang\-Show\-Warnings\-true}
  {
    \providedby{\file{tracklang.tex} v1.3+}
    \desc{sets \gls{ifTrackLangShowWarnings} to true}
  }
  % \ifTrackLangShowInfo
  \gcond{if\-Track\-Lang\-Show\-Info}
  {
    \initval{\cmd{iftrue}}
    \providedby{\file{tracklang.tex} v1.3+}
    \desc{conditional that indicates whether or not to show
information messages}
  }
  % \ifTrackLangShowVerbose
  \gcond{if\-Track\-Lang\-Show\-Verbose}
  {
    \initval{\cmd{iffalse}}
    \providedby{\file{tracklang.tex} v1.4+}
    \desc{conditional that indicates whether or not to show
verbose messages}
  }
  % \TrackLangQueryEnv
  \gcmd{Track\-Lang\-Query\-Env}
  {
    \providedby{\file{tracklang.tex} v1.3+}
    \desc{attempts to obtain locale information from the
    \envvar{LCALL} environment variable via the \idx{shellescape}
    or, with \LuaTeX, \gls{directlua}}
  }
  % \TrackLangQueryOtherEnv
  \gcmd{Track\-Lang\-Query\-Other\-Env}
  {
    \providedby{\file{tracklang.tex} v1.3+}
    \syntax{\margm{env-name}}
    \desc{attempts to obtain locale information from the
    \envvar{LCALL} environment variable and then by the
    \meta{env-name} environment variable via the \idx{shellescape}
    or, with \LuaTeX, \gls{directlua}}
  }
  % \TrackLangParseFromEnv
  \gcmd{Track\-Lang\-Parse\-From\-Env}
  {
    \providedby{\file{tracklang.tex} v1.3+}
    \desc{attempts to obtain locale information from the
    expansion of \gls{TrackLangEnv}}
  }
  % \TrackLangEnv
  \gcmd{Track\-Lang\-Env}
  {
    \note{user defined}
    \desc{may be defined using the same format as \envvar{LCALL}
    before using \gls{TrackLangParseFromEnv} to skip the environment
    variable query}
  }
  % \TrackLangEnvLang
  \gcmd{Track\-Lang\-Env\-Lang}
  {
    \providedby{\file{tracklang.tex} v1.3+}
    \desc{set by \gls{TrackLangParseFromEnv} to the language code}
  }
  % \TrackLangEnvTerritory
  \gcmd{Track\-Lang\-Env\-Territory}
  {
    \providedby{\file{tracklang.tex} v1.3+}
    \desc{set by \gls{TrackLangParseFromEnv} to the \idx{territory}}
  }
  % \TrackLangEnvCodeSet
  \gcmd{Track\-Lang\-Env\-Code\-Set}
  {
    \providedby{\file{tracklang.tex} v1.3+}
    \desc{set by \gls{TrackLangParseFromEnv} to the \idx{code-set}}
  }
  % \TrackLangEnvModifier
  \gcmd{Track\-Lang\-Env\-Modifier}
  {
    \providedby{\file{tracklang.tex} v1.3+}
    \desc{set by \gls{TrackLangParseFromEnv} to the \idx{modifier}}
  }
  % \ForEachTrackedLanguage
  \gcmd{For\-Each\-Track\-ed\-Lan\-guage}
  {
    \providedby{\file{tracklang.tex} v1.0+}
    \syntax{\margm{cs}\margm{body}}
    \desc{iterates through the list of tracked languages. On each
    iteration \meta{cs} is set to the language tag and \meta{body} is
    performed}
  }
  % \ForEachTrackedDialect
  \gcmd{For\-Each\-Track\-ed\-Di\-alect}
  {
    \providedby{\file{tracklang.tex} v1.0+}
    \syntax{\margm{cs}\margm{body}}
    \desc{iterates through the list of tracked dialects. On each
    iteration \meta{cs} is set to the dialect tag and \meta{body} is
    performed}
  }
  % \ForEachTrackedRegion
  \gcmd{For\-Each\-Track\-ed\-Region}
  {
    \providedby{\file{tracklang.tex} v1.0+}
    \syntax{\margm{cs}\margm{body}}
    \desc{iterates through the list of tracked regions. On each
    iteration \meta{cs} is set to the region code and \meta{body} is
    performed}
  }
  % \TrackLangNewLanguage
  \gcmd{Track\-Lang\-New\-Lan\-guage}
  {
    \providedby{\file{tracklang.tex} v1.3+}
    \syntax{\margm{language label}\margm{639-1 code}\margm{639-2 (T)}%
    \margm{639-2 (B)}\margm{639-3}\margm{3166-1}\margm{default script}}
    \desc{identifies a new language that may be tracked. Apart from
    \meta{language label}, the other arguments may be empty if
    the information is unavailable}
  }
  % \TrackLangIfKnownLang
  \gcmd{Track\-Lang\-If\-Known\-Lang}
  {
    \providedby{\file{tracklang.tex} v1.3+}
    \syntax{\margm{language}\margm{true}\margm{false}}
    \desc{does \meta{true} if \meta{language} is known 
    (but not necessarily tracked), otherwise does \meta{false}}
  }
  % \TrackLangIfKnownIsoTwoLetterLang
  \gcmd{Track\-Lang\-If\-Known\-Iso\-Two\-Letter\-Lang}
  {
    \providedby{\file{tracklang.tex} v1.3+}
    \syntax{\margm{language}\margm{true}\margm{false}}
    \desc{does \meta{true} if \meta{language} has an \idxn{639-1} code 
    (but is not necessarily tracked), otherwise does \meta{false}}
  }
  % \TrackLangGetKnownIsoTwoLetterLang
  \gcmd{Track\-Lang\-Get\-Known\-Iso\-Two\-Letter\-Lang}
  {
    \providedby{\file{tracklang.tex} v1.3+}
    \syntax{\margm{language}}
    \desc{expands to the \idxn{639-1} language code associated with
    \meta{language}}
  }
  % \TrackLangIfKnownIsoThreeLetterLang
  \gcmd{Track\-Lang\-If\-Known\-Iso\-Three\-Letter\-Lang}
  {
    \providedby{\file{tracklang.tex} v1.3+}
    \syntax{\margm{language}\margm{true}\margm{false}}
    \desc{does \meta{true} if \meta{language} has an \idxn{639-2} code 
    (but is not necessarily tracked), otherwise does \meta{false}}
  }
  % \TrackLangGetKnownIsoThreeLetterLang
  \gcmd{Track\-Lang\-Get\-Known\-Iso\-Three\-Letter\-Lang}
  {
    \providedby{\file{tracklang.tex} v1.3+}
    \syntax{\margm{language}}
    \desc{expands to the \idxn{639-2} language code associated with
    \meta{language}}
  }
  % \TrackLangIfKnownIsoThreeLetterLangB
  \gcmd{Track\-Lang\-If\-Known\-Iso\-Three\-Letter\-LangB}
  {
    \providedby{\file{tracklang.tex} v1.3+}
    \syntax{\margm{language}\margm{true}\margm{false}}
    \desc{does \meta{true} if \meta{language} has an \idxn{639-2B} code 
    (but is not necessarily tracked), otherwise does \meta{false}}
  }
  % \TrackLangGetKnownIsoThreeLetterLangB
  \gcmd{Track\-Lang\-Get\-Known\-Iso\-Three\-Letter\-LangB}
  {
    \providedby{\file{tracklang.tex} v1.3+}
    \syntax{\margm{language}}
    \desc{expands to the \idxn{639-2B} language code associated with
    \meta{language}}
  }
  % \IfTrackedLanguageHasIsoCode
  \gcmd{If\-Track\-ed\-Lan\-guage\-Has\-Iso\-Code}
  {
    \providedby{\file{tracklang.tex} v1.0+}
    \syntax{\margm{code type}\margm{label}\margm{true}\margm{false}}
    \desc{does \meta{true} if the given language or dialect has a
    corresponding \idx{ISO} code of the given type, otherwise does
    \meta{false}}
  }
  % \IfTrackedIsoCode
  \gcmd{If\-Track\-ed\-Iso\-Code}
  {
    \providedby{\file{tracklang.tex} v1.0+}
    \syntax{\margm{code type}\margm{code}\margm{true}\margm{false}}
    \desc{does \meta{true} if the given \idx{ISO} code has been defined
    otherwise does \meta{false}}
  }
  % \TrackLangIfKnownLangFromIso
  \gcmd{Track\-Lang\-If\-Known\-Lang\-From\-Iso}
  {
    \providedby{\file{tracklang.tex} v1.3+}
    \syntax{\margm{ISO code}\margm{true}\margm{false}}
    \desc{does \meta{true} if the given language code (\idx{639-1} or 
    \idx{639-2} or \idx{639-3}) is
    recognised (but not necessarily tracked), otherwise does \meta{false}}
  }
  % \TrackLangGetKnownLangFromIso
  \gcmd{Track\-Lang\-Get\-Known\-Lang\-From\-Iso}
  {
    \providedby{\file{tracklang.tex} v1.3+}
    \syntax{\margm{ISO code}}
    \desc{expands to the root language label from the 
    given \idx{ISO} code (\idx{639-1} or \idx{639-2} or \idx{639-3})}
  }
  % \TrackLangIfHasKnownCountry
  \gcmd{Track\-Lang\-If\-Has\-Known\-Coun\-try}
  {
    \providedby{\file{tracklang.tex} v1.3+}
    \syntax{\margm{language}\margm{true}\margm{false}}
    \desc{does \meta{true} if the given language has an \idxn{3166-1}
    country code (but is not necessarily tracked), otherwise does \meta{false}}
  }
  % \TrackLangGetKnownCountry
  \gcmd{Track\-Lang\-Get\-Known\-Coun\-try}
  {
    \providedby{\file{tracklang.tex} v1.3+}
    \syntax{\margm{language}}
    \desc{expands to the \idxn{3166-1} country code for the given language}
  }
  % \TrackLangGetDefaultScript
  \gcmd{Track\-Lang\-Get\-Default\-Script}
  {
    \providedby{\file{tracklang.tex} v1.3+}
    \syntax{\margm{language}}
    \desc{expands to the default script for the given language}
  }
  % \TrackLangIfHasDefaultScript
  \gcmd{Track\-Lang\-If\-Has\-Default\-Script}
  {
    \providedby{\file{tracklang.tex} v1.3+}
    \syntax{\margm{language}\margm{true}\margm{false}}
    \desc{does \meta{true} if the given language has a default
    script (but is not necessarily tracked), otherwise does \meta{false}}
  }
  % \AddTrackedDialect
  \gcmd{Add\-Track\-ed\-Di\-alect}
  {
    \providedby{\file{tracklang.tex} v1.0+}
    \syntax{\margm{dialect label}\margm{root language label}}
    \desc{tracks a dialect. This command defines
\gls{TrackLangLastTrackedDialect} to provide a convenient way to
reference the last dialect to be tracked}
  }
  % \AddTrackedLanguage
  \gcmd{Add\-Track\-ed\-Lan\-guage}
  {
    \providedby{\file{tracklang.tex} v1.0+}
    \syntax{\margm{root language label}}
    \desc{shortcut for \code{\gls{AddTrackedDialect}\margm{root language
label}\margm{root language label}}}
  }
  % \AddTrackedIsoLanguage
  \gcmd{Add\-Track\-ed\-Iso\-Lan\-guage}
  {
    \providedby{\file{tracklang.tex} v1.0+}
    \syntax{\margm{code type}\margm{code}\margm{language}}
    \desc{adds a mapping between the given \idx{ISO} code and language name}
  }
  % \TrackedLanguageFromIsoCode
  \gcmd{Tracked\-Lan\-guage\-From\-Iso\-Code}
  {
    \providedby{\file{tracklang.tex} v1.0+}
    \syntax{\margm{code type}\margm{code}}
    \desc{expands to a comma-separated list of language or 
    dialect labels associated with the given code}
  }
  % \TrackedIsoCodeFromLanguage
  \gcmd{Track\-ed\-Iso\-Code\-From\-Lan\-guage}
  {
    \providedby{\file{tracklang.tex} v1.0+}
    \syntax{\margm{code type}\margm{label}}
    \desc{expands to the code associated with the given language or
dialect identified by \meta{label}}
  }
  % \TrackedLanguageFromDialect
  \gcmd{Track\-ed\-Lan\-guage\-From\-Di\-alect}
  {
    \providedby{\file{tracklang.tex} v1.0+}
    \syntax{\margm{dialect}}
    \desc{expands to the language from the given dialect}
  }
  % \TrackedDialectsFromLanguage
  \gcmd{Tracked\-Di\-alects\-From\-Lan\-guage}
  {
    \providedby{\file{tracklang.tex} v1.0+}
    \syntax{\margm{root language label}}
    \desc{expands to a comma-separated list of the tracked dialects with the given language}
  }
  % \TwoLetterIsoCountryCode
  \gcmd{Two\-Letter\-Iso\-Coun\-try\-Code}
  {
    \providedby{\file{tracklang.tex} v1.0+}
    \desc{expands to \idx{3166-1} (should not be redefined)}
  }
  % \TwoLetterIsoLanguageCode
  \gcmd{Two\-Letter\-Iso\-Lan\-guage\-Code}
  {
    \providedby{\file{tracklang.tex} v1.0+}
    \desc{expands to \idx{639-1} (should not be redefined)}
  }
  % \ThreeLetterIsoLanguageCode
  \gcmd{Three\-Letter\-Iso\-Lan\-guage\-Code}
  {
    \providedby{\file{tracklang.tex} v1.0+}
    \desc{expands to \idx{639-2} (should not be redefined)}
  }
  % \ThreeLetterExtIsoLanguageCode
  \gcmd{Three\-Letter\-Ext\-Iso\-Lan\-guage\-Code}
  {
    \providedby{\file{tracklang.tex} v1.3+}
    \desc{expands to \idx{639-3} (should not be redefined)}
  }
  % \SetTrackedDialectModifier
  \gcmd{Set\-Track\-ed\-Di\-alect\-Mod\-i\-fier}
  {
    \providedby{\file{tracklang.tex} v1.3+}
    \syntax{\margm{dialect}\margm{value}}
    \desc{sets the modifier for the given \meta{dialect} to
\meta{value}}
  }
  % \GetTrackedDialectModifier
  \gcmd{Get\-Track\-ed\-Di\-alect\-Mod\-i\-fier}
  {
    \providedby{\file{tracklang.tex} v1.3+}
    \syntax{\margm{dialect}}
    \desc{expands to the modifier for the given dialect}
  }
  % \IfHasTrackedDialectModifier
  \gcmd{If\-Has\-Track\-ed\-Di\-alect\-Mod\-i\-fier}
  {
    \providedby{\file{tracklang.tex} v1.3+}
    \syntax{\margm{dialect}\margm{true}\margm{false}}
    \desc{expands to \meta{true} if there's a modifier for the given
dialect, otherwise expands to \meta{false}}
  }
  % \SetTrackedDialectScript
  \gcmd{Set\-Track\-ed\-Di\-alect\-Script}
  {
    \providedby{\file{tracklang.tex} v1.3+}
    \syntax{\margm{dialect}\margm{value}}
    \desc{sets the script for \meta{dialect} to \meta{value}}
  }
  % \GetTrackedDialectScript
  \gcmd{Get\-Track\-ed\-Di\-alect\-Script}
  {
    \providedby{\file{tracklang.tex} v1.3+}
    \syntax{\margm{dialect}}
    \desc{expands to the script for \meta{dialect}}
  }
  % \IfHasTrackedDialectScript
  \gcmd{If\-Has\-Track\-ed\-Di\-alect\-Script}
  {
    \providedby{\file{tracklang.tex} v1.3+}
    \syntax{\margm{dialect}\margm{true}\margm{false}}
    \desc{expands to \meta{true} if there's a script for
    \meta{dialect},  otherwise expands to \meta{false}}
  }
  % \IfTrackedDialectIsScriptCs
  \gcmd{If\-Track\-ed\-Di\-alect\-Is\-Script\-Cs}
  {
    \providedby{\file{tracklang.tex} v1.3+}
    \syntax{\margm{dialect}\margm{cs}\margm{true}\margm{false}}
    \desc{if the given tracked dialect has an associated script and that
     script code matches the replacement text for the control sequence
     \meta{cs} then do \meta{true} otherwise to \meta{false}. If the
     tracked dialect doesn't have an associated script then the default
     script for the root language is tested}
  }
  % \SetTrackedDialectVariant
  \gcmd{Set\-Track\-ed\-Di\-alect\-Vari\-ant}
  {
    \providedby{\file{tracklang.tex} v1.3+}
    \syntax{\margm{dialect}\margm{value}}
    \desc{sets the modifier for \meta{dialect} to \meta{value}}
  }
  % \GetTrackedDialectVariant
  \gcmd{Get\-Track\-ed\-Di\-alect\-Vari\-ant}
  {
    \providedby{\file{tracklang.tex} v1.3+}
    \syntax{\margm{dialect}}
    \desc{expands to the modifier for \meta{dialect}}
  }
  % \IfHasTrackedDialectVariant
  \gcmd{If\-Has\-Track\-ed\-Di\-alect\-Vari\-ant}
  {
    \providedby{\file{tracklang.tex} v1.3+}
    \syntax{\margm{dialect}\margm{true}\margm{false}}
    \desc{expands to \meta{true} if there's a modifier for
    \meta{dialect},  otherwise expands to \meta{false}}
  }
  % \SetTrackedDialectSubLang
  \gcmd{Set\-Track\-ed\-Di\-alect\-Sub\-Lang}
  {
    \providedby{\file{tracklang.tex} v1.3+}
    \syntax{\margm{dialect}\margm{value}}
    \desc{sets the sub-language for \meta{dialect} to \meta{value}}
  }
  % \GetTrackedDialectSubLang
  \gcmd{Get\-Track\-ed\-Di\-alect\-Sub\-Lang}
  {
    \providedby{\file{tracklang.tex} v1.3+}
    \syntax{\margm{dialect}}
    \desc{expands to the sub-language for \meta{dialect}}
  }
  % \IfHasTrackedDialectSubLang
  \gcmd{If\-Has\-Track\-ed\-Di\-alect\-Sub\-Lang}
  {
    \providedby{\file{tracklang.tex} v1.3+}
    \syntax{\margm{dialect}\margm{true}\margm{false}}
    \desc{expands to \meta{true} if there's a sub-language for
    \meta{dialect},  otherwise expands to \meta{false}}
  }
  % \SetTrackedDialectAdditional
  \gcmd{Set\-Track\-ed\-Di\-alect\-Ad\-di\-tional}
  {
    \providedby{\file{tracklang.tex} v1.3+}
    \syntax{\margm{dialect}\margm{value}}
    \desc{sets the extra information for \meta{dialect} to \meta{value}}
  }
  % \GetTrackedDialectAdditional
  \gcmd{Get\-Track\-ed\-Di\-alect\-Ad\-di\-tional}
  {
    \providedby{\file{tracklang.tex} v1.3+}
    \syntax{\margm{dialect}}
    \desc{expands to the extra information for \meta{dialect}}
  }
  % \IfHasTrackedDialectAdditional
  \gcmd{If\-Has\-Track\-ed\-Di\-alect\-Ad\-di\-tional}
  {
    \providedby{\file{tracklang.tex} v1.3+}
    \syntax{\margm{dialect}\margm{true}\margm{false}}
    \desc{expands to \meta{true} if there's extra information for
    \meta{dialect},  otherwise expands to \meta{false}}
  }
  % \GetTrackedLanguageTag
  \gcmd{Get\-Track\-ed\-Lan\-guage\-Tag}
  {
    \providedby{\file{tracklang.tex} v1.3+}
    \syntax{\margm{dialect}}
    \desc{gets the language tag for \meta{dialect}}
  }
  % \SetCurrentTrackedDialect
  \gcmd{Set\-Current\-Track\-ed\-Di\-alect}
  {
    \providedby{\file{tracklang.tex} v1.3+}
    \syntax{\margm{dialect}}
    \desc{sets the current tracked dialect}
  }
  % \CurrentTrackedDialect
  \gcmd{Current\-Track\-ed\-Dialect}
  {
    \providedby{\file{tracklang.tex} v1.3+}
    \desc{defined by \gls{SetCurrentTrackedDialect} to the
      dialect label, which may be the supplied \meta{dialect} label
      or the mapped label or, if \meta{dialect} is a root language label, 
      the last tracked dialect for the given root language}
  }
  % \CurrentTrackedLanguage
  \gcmd{Current\-Track\-ed\-Language}
  {
    \providedby{\file{tracklang.tex} v1.3+}
    \desc{defined by \gls{SetCurrentTrackedDialect} to the
     associated root language label}
  }
  % \CurrentTrackedDialectModifier
  \gcmd{Current\-Track\-ed\-Di\-alect\-Modifier}
  {
    \providedby{\file{tracklang.tex} v1.3+}
    \desc{defined by \gls{SetCurrentTrackedDialect} to the
     associated modifier (may be empty)}
  }
  % \CurrentTrackedDialectVariant
  \gcmd{Current\-Track\-ed\-Di\-alect\-Variant}
  {
    \providedby{\file{tracklang.tex} v1.3+}
    \desc{defined by \gls{SetCurrentTrackedDialect} to the
    associated variant (may be empty)}
  }
  % \CurrentTrackedDialectScript
  \gcmd{Current\-Track\-ed\-Di\-alect\-Script}
  {
    \providedby{\file{tracklang.tex} v1.3+}
    \desc{defined by \gls{SetCurrentTrackedDialect} to the
     script associated with the dialect, or to the default script for the language}
  }
  % \CurrentTrackedDialectSubLang
  \gcmd{Current\-Track\-ed\-Di\-alect\-Sub\-Lang}
  {
    \providedby{\file{tracklang.tex} v1.3+}
    \desc{defined by \gls{SetCurrentTrackedDialect} to the sub
     language associated with the dialect (may be empty)}
  }
  % \CurrentTrackedDialectAdditional
  \gcmd{Current\-Track\-ed\-Di\-alect\-Ad\-di\-tional}
  {
    \providedby{\file{tracklang.tex} v1.3+}
    \desc{defined by \gls{SetCurrentTrackedDialect} to the
     additional part associated with the dialect (may be empty)}
  }
  % \CurrentTrackedLanguageTag
  \gcmd{Current\-Track\-ed\-Lan\-guage\-Tag}
  {
    \providedby{\file{tracklang.tex} v1.3+}
    \desc{defined by \gls{SetCurrentTrackedDialect} to the language
     tag that identifies the dialect or \iso{undetermined} if no match}
  }
  % \CurrentTrackedRegion
  \gcmd{Current\-Track\-ed\-Region}
  {
    \providedby{\file{tracklang.tex} v1.3+}
    \desc{defined by \gls{SetCurrentTrackedDialect} to the 
    \idxn{3166-1} region code associated with the dialect (may be empty)}
  }
  % \CurrentTrackedIsoCode
  \gcmd{Current\-Track\-ed\-Iso\-Code}
  {
    \providedby{\file{tracklang.tex} v1.3+}
    \desc{defined by \gls{SetCurrentTrackedDialect} to the
     \idxn{639-1} or \idx{639-2} or \idx{639-3} language code (may be empty)}
  }
  % \AddTrackedLanguageIsoCodes
  \gcmd{Add\-Track\-ed\-Lan\-guage\-Iso\-Codes}
  {
    \providedby{\file{tracklang.tex} v1.3+}
    \syntax{\margm{root language label}}
    \desc{adds the \idxn{639-1}, \idx{639-2} and \idx{639-3} codes, which must have
    previously been declared using \gls{TrackLangNewLanguage}}
  }
  % \AddTrackedCountryIsoCode
  \gcmd{Add\-Track\-ed\-Coun\-try\-Iso\-Code}
  {
    \providedby{\file{tracklang.tex} v1.3+}
    \syntax{\margm{language}}
    \desc{adds the \idxn{3166-1} code}
  }
  % \GetTrackedDialectFromLanguageTag
  \gcmd{Get\-Track\-ed\-Di\-alect\-From\-Lan\-guage\-Tag}
  {
    \providedby{\file{tracklang.tex} v1.3+}
    \syntax{\margm{tag}\margm{cs}}
    \desc{finds the tracked dialect that matches the given language
    tag and stores the dialect label in \meta{cs}. If no match found,
    \meta{cs} will be empty}
  }
  % \TrackedDialectClosestSubMatch
  \gcmd{Track\-ed\-Dialect\-Closest\-Sub\-Match}
  {
    \providedby{\file{tracklang.tex} v1.3.6+}
    \desc{defined by \gls{GetTrackedDialectFromLanguageTag} to the
    closest match}
  }
  % \TrackPredefinedDialect
  \gcmd{Track\-Pre\-de\-fined\-Di\-alect}
  {
    \providedby{\file{tracklang.tex} v1.0+}
    \syntax{\margm{dialect label}}
    \desc{tracks a predefined language or dialect}
  }
  % \TrackLangIfAlphaNumericChar
  \gcmd{Track\-Lang\-If\-Alpha\-Numeric\-Char}
  {
    \providedby{\file{tracklang.tex} v1.3+}
    \syntax{\margm{tag}\margm{true}\margm{false}}
    \desc{does \meta{true} if the argument is a single alphanumeric character
     otherwise does \meta{false}}
  }
  % \TrackLangIfLanguageTag
  \gcmd{Track\-Lang\-If\-Lan\-guage\-Tag}
  {
    \providedby{\file{tracklang.tex} v1.3+}
    \syntax{\margm{tag}\margm{true}\margm{false}}
    \desc{does \meta{true} if the argument is a language tag
     otherwise does \meta{false}}
  }
  % \TrackLangIfRegionTag
  \gcmd{Track\-Lang\-If\-Region\-Tag}
  {
    \providedby{\file{tracklang.tex} v1.3+}
    \syntax{\margm{tag}\margm{true}\margm{false}}
    \desc{does \meta{true} if the argument is a region tag
     otherwise does \meta{false}}
  }
  % \TrackLangIfScriptTag
  \gcmd{Track\-Lang\-If\-Script\-Tag}
  {
    \providedby{\file{tracklang.tex} v1.3+}
    \syntax{\margm{tag}\margm{true}\margm{false}}
    \desc{does \meta{true} if the argument is a script tag
     otherwise does \meta{false}}
  }
  % \TrackLangIfVariantTag
  \gcmd{Track\-Lang\-If\-Vari\-ant\-Tag}
  {
    \providedby{\file{tracklang.tex} v1.3+}
    \syntax{\margm{tag}\margm{true}\margm{false}}
    \desc{does \meta{true} if the argument is a variant tag
     otherwise does \meta{false}}
  }
  % \TrackLanguageTag
  \gcmd{Track\-Lan\-guage\-Tag}
  {
    \providedby{\file{tracklang.tex} v1.3+}
    \syntax{\margm{tag}}
    \desc{parse \meta{tag}, which should be a regular, well-formed
     RFC 5646 language tag (not an irregular grandfather tag) and
track the dialect. Note that the tag must start with a language
identifier and can't simply be a region code}
  }
  % \TrackIfKnownLanguage
  \gcmd{Track\-If\-Known\-Lan\-guage}
  {
    \providedby{\file{tracklang.tex} v1.3.9+}
    \syntax{\margm{tag}\margm{success code}\margm{fail code}}
    \desc{as \gls{TrackLanguageTag} but does \meta{fail code}
    if the tag doesn't contain a valid language code. If successful, does
    \meta{success code} after tracking the language}
  }
  % \TrackLangAddExtraRegionFile
  \gcmd{Track\-Lang\-Add\-Extra\-Region\-File}
  {
    \providedby{\file{tracklang.tex} v1.4+}
    \syntax{\margm{file}}
    \desc{adds \meta{file} to the list of extra region code files that should
    be input by \file{tracklang-region-codes.tex}}
  }
  % \TrackLangAddExtraScriptFile
  \gcmd{Track\-Lang\-Add\-Extra\-Script\-File}
  {
    \providedby{\file{tracklang.tex} v1.4+}
    \syntax{\margm{file}}
    \desc{adds \meta{file} to the list of files that should
    be input by \file{tracklang-scripts.tex}}
  }
  % \TrackLangFromEnv
  \gcmd{Track\-Lang\-From\-Env}
  {
    \providedby{\file{tracklang.tex} v1.3+}
    \desc{queries environment variable if \gls{TrackLangEnv} not
    already set, parses \gls{TrackLangEnv} if it has been set, and
    adds the dialect if it's recognised}
  }
  % \TrackLocale
  \gcmd{Track\-Locale}
  {
    \providedby{\file{tracklang.tex} v1.3+}
    \syntax{\margm{locale}}
    \desc{tracks the dialect identified by the given \meta{locale}, which
    may either be a predefined language\slash dialect or in the same format as
    \gls{TrackLangEnv}}
  }
  % \TrackLangProvidePredefinedLanguage
  \gcmd{Track\-Lang\-Provide\-Pre\-de\-fined\-Lan\-guage}
  {
    \providedby{\file{tracklang.tex} v1.4+}
    \syntax{\margm{language label}}
    \desc{sets up a language label for use with \gls{TrackPredefinedDialect}}
  }
  % \TrackLangDeclareLanguageOption
  \gcmd{Track\-Lang\-Declare\-Lan\-guage\-Op\-tion}
  {
    \providedby{\file{tracklang.tex} v1.3+}
    \syntax{\margm{language name}\margm{639-1 code}\margm{639-2 (T)}\margm{639-2
(B)}\margm{639-3}\margm{3166-1}\margm{default script}}
    \desc{defines a new root language that's declared as an option}
  }
  % \TrackLangProvidePredefinedDialect
  \gcmd{Track\-Lang\-Provide\-Pre\-de\-fined\-Di\-alect}
  {
    \providedby{\file{tracklang.tex} v1.4+}
    \syntax{\margm{dialect label}\margm{root
language label}\margm{3166-1 code}\margm{modifier}\margm{variant}\margm{map}\margm{script}}
    \desc{defines a predefined dialect label that can be used
by \gls{TrackPredefinedDialect}}
  }
  % \TrackLangDeclareDialectOption
  \gcmd{Track\-Lang\-Declare\-Di\-alect\-Op\-tion}
  {
    \providedby{\file{tracklang.tex} v1.3+}
    \syntax{\margm{dialect}\margm{root
language}\margm{3166-1
code}\margm{modifier}\margm{variant}\margm{map}\margm{script}}
    \desc{defines a predefined dialect label that can be used
by \gls{TrackPredefinedDialect}}
  }
  % \TrackLangProvidesResource
  \gcmd{Track\-Lang\-Provides\-Resource}
  {
    \providedby{\file{tracklang.tex} v1.3+}
    \syntax{\margm{tag}\oargm{version info}}
    \desc{analogous to \gls{ProvidesFile}}
  }
  % \TrackLangEncodingName
  \gcmd{Track\-Lang\-Encoding\-Name}
  {
    \providedby{\file{tracklang.tex} v1.6.1+}
    \desc{expands to \gls{inputencodingname} if it has been defined
    or \code{utf8} otherwise}
  }
  % \TrackLangAddToHook
  \gcmd{Track\-Lang\-Add\-To\-Hook}
  {
    \providedby{\file{tracklang.tex} v1.3+}
    \syntax{\margm{code}\margm{type}}
    \desc{for use within resource files, this can be used to add
\meta{code} to the appropriate hook}
  }
  % \TrackLangAddToCaptions
  \gcmd{Track\-Lang\-Add\-To\-Captions}
  {
    \providedby{\file{tracklang.tex} v1.3+}
    \syntax{\margm{code}}
    \desc{a shortcut that just does
    \code{\gls{TrackLangAddToHook}\margm{code}\marg{captions}}}
  }
  % \TrackLangRedefHook
  \gcmd{Track\-Lang\-Re\-def\-Hook}
  {
    \providedby{\file{tracklang.tex} v1.4+}
    \syntax{\margm{code}\margm{type}}
    \desc{similar to \gls{TrackLangAddToHook} but redefines the hook
   rather than appending to it}
  }
  % \TrackLangRequireResource
  \gcmd{Track\-Lang\-Require\-Resource}
  {
    \providedby{\file{tracklang.tex} v1.3+}
    \syntax{\margm{tag}}
    \desc{loads the appropriate \ext{ldf} file if it hasn't already
been loaded}
  }
  % \TrackLangRequireResourceOrDo
  \gcmd{Track\-Lang\-Require\-Resource\-Or\-Do}
  {
    \providedby{\file{tracklang.tex} v1.3+}
    \syntax{\margm{tag}\margm{code1}\margm{code2}}
    \desc{as \gls{TrackLangRequireResource} but does \meta{code1} 
    if the file is now loaded or \meta{code2}
    if the file has already been loaded}
  }
  % \TrackLangRequestResource
  \gcmd{Track\-Lang\-Request\-Resource}
  {
    \providedby{\file{tracklang.tex} v1.3+}
    \syntax{\margm{tag}\margm{not found code}}
    \desc{as \gls{TrackLangRequireResource} but does \meta{not found code}
if the file doesn't exist}
  }
  % \TrackLangRequireDialect
  \gcmd{Track\-Lang\-Require\-Di\-alect}
  {
    \providedby{\file{tracklang.tex} v1.3+}
    \syntax{\oargm{load code}\margm{pkgname}\margm{dialect}}
    \desc{loads the dialect for the given package using 
     \gls{IfTrackedLanguageFileExists}}
  }
  % \TrackLangRequireDialectOmitDialectLabel
  \gcmd{Track\-Lang\-Require\-Di\-alect\-Omit\-Di\-alect\-Label}
  {
    \providedby{\file{tracklang.tex} v1.3+}
    \syntax{\oargm{load code}\margm{pkgname}\margm{dialect}}
    \desc{loads the dialect for the given package using 
     \gls{IfTrackedLanguageFileExistsOmitDialectLabel}}
  }
  % \TrackLangRequireDialectOmitDialectLabelOmitOnlyRegion
  \gcmd{Track\-Lang\-Require\-Di\-alect\-Omit\-Di\-alect\-Label\-Omit\-Only\-Region}
  {
    \providedby{\file{tracklang.tex} v1.3+}
    \syntax{\oargm{load code}\margm{pkgname}\margm{dialect}}
    \desc{loads the dialect for the given package using 
     \gls{IfTrackedLanguageFileExistsOmitDialectLabelOmitOnlyRegion}}
  }
  % \TrackLangRequireDialectOmitOnlyRegion
  \gcmd{Track\-Lang\-Require\-Di\-alect\-Omit\-Only\-Region}
  {
    \providedby{\file{tracklang.tex} v1.3+}
    \syntax{\oargm{load code}\margm{pkgname}\margm{dialect}}
    \desc{loads the dialect for the given package using 
     \gls{IfTrackedLanguageFileExistsOmitOnlyRegion}}
  }
  % \TrackLangRequireDialectPrefix
  \gcmd{Track\-Lang\-Require\-Di\-alect\-Prefix}
  {
    \providedby{\file{tracklang.tex} v1.3+}
    \desc{defined by \gls{TrackLangRequireDialect}}
  }
  % \SetTrackedDialectLabelMap
  \gcmd{Set\-Track\-ed\-Di\-alect\-Label\-Map}
  {
    \providedby{\file{tracklang.tex} v1.3+}
    \syntax{\margm{tracklang-label}\margm{hook-label}}
    \desc{defines a mapping between a \sty{tracklang} dialect label
     and the corresponding dialect label used by a language hook, such as
     \gls{captionsdialect}}
  }
  % \TrackLangLastTrackedDialect
  \gcmd{Track\-Lang\-Last\-Track\-ed\-Dialect}
  {
    \providedby{\file{tracklang.tex} v1.3+}
    \desc{expands to the label of the last tracked dialect}
  }
  % COMMANDS: INTERNAL
  % \@tracklang@declareoption
  \gcmd{@track\-lang\-@\-declare\-option}
  {
    \providedby{\sty{tracklang} v1.1+}
    \syntax{\margm{dialect}}
    \desc{provided by \file{tracklang.sty} to declare \meta{dialect} 
     as a package option that tracks \meta{dialect}. Provided by
     \file{tracklang.tex}, if not already defined, to ignore its argument}
  }
  % \@tracklang@for
  \gcmd{@track\-lang\-@\-for}
  {
    \providedby{\file{tracklang.tex} v1.0+}
    \syntax{\meta{cs}:=\meta{list}\cmd{do}\margm{body}}
    \desc{as \LaTeX's \gls{@for}}
  }
  % \@tracklang@prelangpkgcheck@hook
  \gcmd{@track\-lang\-@\-pre\-lang\-pkg\-check\-@\-hook}
  {
    \desc{if defined before \file{tracklang.sty} v1.3.8+ is loaded, this
    command will be done after package options have been processed but
    before the check for language packages, such as \sty{babel} and
    \sty{polyglossia}}
  }
  % COMMANDS: tracklang-region-codes.tex
  % \TrackLangAlphaIIToNumericRegion
  \gcmd{Track\-Lang\-Alpha\-II\-To\-Numeric\-Region}
  {
    \providedby{\file{tracklang-region-codes.tex} v1.3+}
    \syntax{\margm{alpha-2 code}}
    \desc{expands to the numeric code corresponding to the given
alpha-2 code}
  }
  % \TrackLangNumericToAlphaIIRegion
  \gcmd{Track\-Lang\-Numeric\-To\-Alpha\-II\-Region}
  {
    \providedby{\file{tracklang-region-codes.tex} v1.3+}
    \syntax{\margm{numeric code}}
    \desc{expands to the alpha-2 code corresponding to the given
numeric code}
  }
  % \TrackLangIfKnownAlphaIIRegion
  \gcmd{Track\-Lang\-If\-Known\-Alpha\-II\-Region}
  {
    \providedby{\file{tracklang-region-codes.tex} v1.3+}
    \syntax{\margm{alpha-2 code}\margm{true}\margm{false}}
    \desc{expands to \meta{true} if there's a known mapping for the
given alpha-2 \idx{region} code, otherwise expands to \meta{false}}
  }
  % \TrackLangIfKnownNumericRegion
  \gcmd{Track\-Lang\-If\-Known\-Numeric\-Region}
  {
    \providedby{\file{tracklang-region-codes.tex} v1.3+}
    \syntax{\margm{numeric code}\margm{true}\margm{false}}
    \desc{expands to \meta{true} if there's a known mapping for the
given numeric \idx{region} code, otherwise expands to \meta{false}}
  }
  % \TrackLangAlphaIIIToNumericRegion
  \gcmd{Track\-Lang\-Alpha\-III\-To\-Numeric\-Region}
  {
    \providedby{\file{tracklang-region-codes.tex} v1.3+}
    \syntax{\margm{alpha-3 code}}
    \desc{expands to the numeric code corresponding to the given
alpha-3 code}
  }
  % \TrackLangNumericToAlphaIIIRegion
  \gcmd{Track\-Lang\-Numeric\-To\-Alpha\-III\-Region}
  {
    \providedby{\file{tracklang-region-codes.tex} v1.3+}
    \syntax{\margm{numeric code}}
    \desc{expands to the alpha-3 code corresponding to the given
numeric code}
  }
  % \TrackLangIfKnownAlphaIIIRegion
  \gcmd{Track\-Lang\-If\-Known\-Alpha\-III\-Region}
  {
    \providedby{\file{tracklang-region-codes.tex} v1.3+}
    \syntax{\margm{alpha-3 code}\margm{true}\margm{false}}
    \desc{expands to \meta{true} if there's a known mapping for the
given \meta{alpha-3 code}, otherwise expands to \meta{false}}
  }
  % \TrackLangRegionMap
  \gcmd{Track\-Lang\-Region\-Map}
  {
    \providedby{\file{tracklang-region-codes.tex} v1.3+}
    \syntax{\margm{numeric}\margm{alpha-2}\margm{alpha-3}}
    \desc{establishes a mapping between a numeric \idx{region} code
    and alpha-2 and alpha-3 codes}
  }
  % COMMANDS: tracklang-scripts.tex
  % \TrackLangScriptMap
  \gcmd{Track\-Lang\-Script\-Map}
  {
    \providedby{\file{tracklang-scripts.tex} v1.3+}
    \syntax{\margm{letter code}\margm{numeric code}\margm{script name}\margm{direction}\margm{parent script}}
    \desc{defines a mapping between an alpha code and a numeric code}
  }
  % \TrackLangScriptAlphaToNumeric
  \gcmd{Track\-Lang\-Script\-Alpha\-To\-Numeric}
  {
    \providedby{\file{tracklang-scripts.tex} v1.3+}
    \syntax{\margm{alpha code}}
    \desc{expands to the numeric script code corresponding to the given alpha code}
  }
  % \TrackLangScriptIfKnownAlpha
  \gcmd{Track\-Lang\-Script\-If\-Known\-Alpha}
  {
    \providedby{\file{tracklang-scripts.tex} v1.3+}
    \syntax{\margm{alpha code}\margm{true}\margm{false}}
    \desc{expands to \meta{true} if there's a known mapping for the
    given alpha script code otherwise expands to \meta{false}}
  }
  % \TrackLangScriptNumericToAlpha
  \gcmd{Track\-Lang\-Script\-Numeric\-To\-Alpha}
  {
    \providedby{\file{tracklang-scripts.tex} v1.3+}
    \syntax{\margm{numeric code}}
    \desc{expands to the alpha script code corresponding to the
     given numeric code}
  }
  % \TrackLangScriptIfKnownNumeric
  \gcmd{Track\-Lang\-Script\-If\-Known\-Numeric}
  {
    \providedby{\file{tracklang-scripts.tex} v1.3+}
    \syntax{\margm{numeric code}\margm{true}\margm{false}}
    \desc{expands to \meta{true} if there's a known mapping for the
     given numeric script code otherwise expands to \meta{false}}
  }
  % \TrackLangScriptAlphaToName
  \gcmd{Track\-Lang\-Script\-Alpha\-To\-Name}
  {
    \providedby{\file{tracklang-scripts.tex} v1.3+}
    \syntax{\margm{alpha code}}
    \desc{expands to the name associated with the given alpha script
    code}
  }
  % \TrackLangScriptAlphaToDir
  \gcmd{Track\-Lang\-Script\-Alpha\-To\-Dir}
  {
    \providedby{\file{tracklang-scripts.tex} v1.3+}
    \syntax{\margm{alpha code}}
    \desc{expands to the direction associated with the given alpha script
    code}
  }
  % \TrackLangScriptSetParent
  \gcmd{Track\-Lang\-Script\-Set\-Parent}
  {
    \providedby{\file{tracklang-scripts.tex} v1.3+}
    \syntax{\margm{alpha code}\margm{parent alpha code}}
    \desc{sets the parent for the given alpha script code}
  }
  % \TrackLangScriptGetParent
  \gcmd{Track\-Lang\-Script\-Get\-Parent}
  {
    \providedby{\file{tracklang-scripts.tex} v1.3+}
    \syntax{\margm{alpha code}}
    \desc{expands to the parent of the given alpha script code}
  }
  % \TrackLangScriptIfHasParent
  \gcmd{Track\-Lang\-Script\-If\-Has\-Parent}
  {
    \providedby{\file{tracklang-scripts.tex} v1.3+}
    \syntax{\margm{alpha code}\margm{true}\margm{false}}
    \desc{expands to \meta{true} if the given alpha script code has
     a parent otherwise expands to \meta{false}}
  }
  % \TrackLangScript<Code>
  \gcmdmeta{Track\-Lang\-Script}{Code}{}
  {
    \providedby{\file{tracklang-scripts.tex} v1.3+}
    \desc{set by \gls{TrackLangScriptMap} to the associated alpha code \meta{Code}}
  }
  % PACKAGE OPTIONS:
  \gstyopt{verbose}
  {
    \providedby{\sty{tracklang} v1.6.3+}
    \desc{switches on verbose setting}
  }
  \gstyopt{noverbose}
  {
    \providedby{\sty{tracklang} v1.6.3+}
    \desc{switches off verbose setting (default)}
  }
  \gstyopt{warn}
  {
    \providedby{\sty{tracklang} v1.6.5+}
    \desc{switches on warning setting (default)}
  }
  \gstyopt{nowarn}
  {
    \providedby{\sty{tracklang} v1.6.5+}
    \desc{switches off warning setting}
  }
  \gstyopt{isotag}
  {
    \name{\styoptfmt{\meta{iso-tag}}}
    \desc{Any ISO tag listed in \tableref{tab:isoopts} may be used
as a package option}
  }
  \gstyopt{dialect}
  {
    \name{\styoptfmt{\meta{dialect}}}
    \desc{Any dialect label listed in \tableref{tab:isoopts} may be used
as a package option}
  }
  % FILES
  \gfile{track\-lang.tex}{}% tracklang.tex
  \gfile{track\-lang.sty}% tracklang.sty
  {\field{alias}{pkg.tracklang}}%
  \gfile{track\-lang\dhyphen scripts.sty}% tracklang-scripts.sty
  {\field{alias}{pkg.tracklang-scripts}}%
  \gfile{tracklang\dhyphen region\dhyphen codes.tex}{}% tracklang-region-codes.tex
  \gfile{tracklang\dhyphen scripts.tex}{}% tracklang-scripts.tex
  \gfile{tex\-os\-query.tex}{}% texosquery.tex
  \gfile{tex\-os\-query.cfg}{}% texosquery.cfg
  \gfilemetameta{}{prefix}{\dhyphen}{localeid}{.ldf}{} % <prefix>-<localeid>.ldf
  % FILE EXTENSIONS
  \gext{tex}{}% .tex
  \gext{ldf}{}% .ldf
  \gext{log}{}% .log
  % PACKAGES
  \gpkg{track\-lang}{\common}% tracklang
  \gpkg{track\-lang\dhyphen scripts}{}% tracklang-scripts
  \gpkg{tex\-os\-query}{}% texosquery
  \gpkg{poly\-glossia}{}% polyglossia.sty
  \gpkg{babel}{}% babel.sty
  \gpkg{translator}{}% translator.sty
  \gpkg{shell\-esc}{}% shellesc.sty
  \gpkg{ngerman}{}% ngerman.sty
  \gpkg{german}{}% german.sty
  \gpkg{glossaries}{}% glossaries.sty
  \gpkg{etool\-box}{}% etoolbox.sty
  \gpkg{date\-time2}{}% datetime2.sty
  \gpkg{input\-enc}{}% inputenc.sty
  % Example packages
  \gfile{animals.sty}{}% animals.sty
  \gfile{regions.sty}{}% regions.sty
  \gfile{alien.sty}{}% alien.sty
  \gpkg{alien}{\field{alias}{file.alien.sty}}
  % environment variables
  \genvvar{LC\dsb ALL}{}% LC_ALL
  \genvvar{LANG}{}% LANG
  \genvvar{LC\dsb MONETARY}{}% LC_MONETARY
  % TERMS
  \gterm{shellescape}
  {
     \name{shell escape}
     \desc{\TeX\ has the ability to run \idx{cli} applications while
      it's typesetting a document. Whilst this is a convenient way
      of using tools to help build the document, it's a security
      risk. To help protect users from arbitrary\dash and
      potentially dangerous\dash code from begin executed, \TeX\ has
      a restricted mode, where only trusted applications are allowed to
      run. This is usually the default mode, but your \TeX\
      installation may be set up so that the shell escape is disabled by
      default. The unrestricted mode allows you to run any
      application from the shell escape. Take care about
      enabling this option. If you receive a document or package
      from an untrusted source, first run \TeX\ with the shell escape
      disabled or in restricted mode and search the \ext+{log} file for
      \qt{runsystem} before using the unrestricted mode. Note that
      \LuaLaTeX\ additionally requires the \sty{shellesc} package}
  }
  \gtermacr{cli}{CLI}{command-line interface}%
  {%  
    \desc{an application that doesn't have a graphical user
     interface. That is, an application that doesn't have any windows,
     buttons or menus and can be run in
     \dickimawhref{latex/novices/html/terminal.html}{a command
     prompt or terminal}}% 
  }%
  % INDEX ONLY
  % COMMANDS - GENERAL
  \gcmd{input\-encoding\-name}{}% \inputencodingname
  \gcmd{Input\-If\-File\-Exists}{}% \InputIfFileExists
  \gcmd{direct\-lua}{}% \directlua
  \gcmd{Locale\-For\-Each}{}% \LocaleForEach
  \gcmd{babel\-provide}{}% \babelprovide
  \gcmd{bbl\-@\-loaded}{}% \bbl@loaded
  \gcmd{select\-language}{}% \selectlanguage
  \gcmd{input}{}% \input
  \gcmd{Require\-Package}{}% \RequirePackage
  \gcmd{Declare\-Option}{}% \DeclareOption
  \gcmdmeta{captions}{dialect}{}{}% \captions<dialect>
  \gcmdmeta{date}{dialect}{}{}% \date<dialect>
  \gcmd{Provides\-File}{}% \ProvidesFile
  \gcmd{xpg\-@\-bcp\-@\-loaded}{}% \xpg@bcp@loaded
  \gcmd{xpg\-@\-loaded}{}% \xpg@loaded
  \gcmd{trans\-@\-languages}{}% \trans@languages
  \gcmd{lan\-guage\-name}{}% \languagename
  \gcmd{TeX\-OS\-Query\-Lang\-Tag}{}% \TeXOSQueryLangTag
  \gcmd{TeX\-OS\-Query\-Locale}{}% \TeXOSQueryLocale
  \gcmd{@for}{}
  \gcmd{@nil}{}
  \gcmd{At\-Begin\-Doc\-u\-ment}{}% \AtBeginDocument
  % APPLICATIONS
  \gapp{tex\-os\-query}{}% texosquery
  \gapp{kpse\-which}{}% kpsewhich
  \gapp{etex}{}% etex
  \gapp{tex}{}% tex
  \gapp{pdflatex}{}% pdflatex
  % PUNCTUATION
  \gpunc{atletter}% @ as a letter
  {\name{\code{@} (catcode 11)}\field{text}{\code{@}}}%
  \gpunc{atmod}% @ separates modifier
  {\name{\code{@} (modifier)}\field{text}{\code{@}}}%
  \gpunc{hyphensep}% - in tag
  {\name{\code{-} (separator)}\field{text}{\code{-}}}%
  \gpunc{underscoresep}% _ in tag
  {\name{\code{\_} (separator)}\field{text}{\code{\_}}}%
  \gpunc{dotsep}% . separates code-set
  {\name{\code{.}\ (code-set)}\field{text}{\code{.}}}%
  \gpunc{dollarenv}% ${ENV VAR}
  {\name{\code{\$} (environment variable)}\field{text}{\code{\$}}}
  \gpunc{escbsl}% \\
  {\name{\code{\glsbackslash\glsbackslash} (escaped backslash)}
   \field{text}{\code{\glsbackslash\glsbackslash}}
  }
  % INDEX ONLY TERMS
  \gidx{code-set}{}
  \gidx{modifier}{}
  \gidx{variant}{}
  \gidx{territory}{}
  \gidx{region}{\field{alias}{idx.territory}}
  \gidx{script}{}
  \gidx{BCP47}{\name{BCP~47}}
  % ISO CODES
  \gidx{639-1}{\name{ISO \mbox{639-1}}\field{text}{\mbox{639-1}}}
  \gidx{639-2}{\name{ISO \mbox{639-2}}\field{text}{\mbox{639-2}}}
  \gidx{639-2B}{\parent{idx.639-2}%
    \name{ISO \mbox{639-2} (B)}%
    \field{text}{\mbox{639-2} (B)}}
  \gidx{639-2T}{\parent{idx.639-2}%
    \name{ISO \mbox{639-2} (T)}%
    \field{text}{\mbox{639-2} (T)}}
  \gidx{639-3}{\name{ISO \mbox{639-3}}\field{text}{\mbox{639-3}}}
  \gidx{3166-1}{\name{ISO \mbox{3166-1}}\field{text}{\mbox{3166-1}}}
  \gidx{15924}{\name{ISO 15924}\field{text}{15924}}
  % ABBREVIATIONS
  \gacr{ISO}{ISO}{International Organization for Standardization}{\common}
  \gacr{POSIX}{POSIX}{Portable Operating System Interface}{}
  % SWITCHES
  \glongswitchpunc{shell\dhyphen escape}{}
  % PREDEFINED ISO LANGUAGE-REGION TAGS
  \gisolangtag{en}{US}{american}{}
  \gisolangtag{en}{GB}{british}{}
  \gisolangtag{en}{AU}{australian}{}
  \gisolangtag{en}{NZ}{newzealand}{}
  \gisolangtag{en}{CA}{canadian}{}
  \gisolangtag{fr}{CA}{canadien}{}
  \gisolangtag{fr}{BE}{belgique}{}
  \gisolangtag{pt}{BR}{brazilian}{}
  \gisolangtag{it}{HR}{istriacountyitalian}{}
  \gisolangtag{nl}{BE}{flemish}{}
  \gisolangtag{fr}{FR}{france}{}
  \gisolangtag{de}{DE}{germanDE}{}
  \gisolangtag{de}{BE}{belgiangerman}{}
  \gisolangtag{en}{GG}{guernseyenglish}{}
  \gisolangtag{fr}{GG}{guernseyfrench}{}
  \gisolangtag{it}{IT}{italy}{}
  \gisolangtag{mt}{MT}{maltamaltese}{}
  \gisolangtag{en}{MT}{maltaenglish}{}
  \gisolangtag{en}{IM}{isleofmanenglish}{}
  \gisolangtag{en}{JE}{jerseyenglish}{}
  \gisolangtag{fr}{JE}{jerseyfrench}{}
  \gisolangtag{nl}{NL}{netherlands}{}
  \gisolangtag{pt}{PT}{portugal}{}
  \gisolangtag{it}{SM}{sanmarino}{}
  \gisolangtag{sl}{SI}{slovenia}{}
  \gisolangtag{it}{SI}{sloveneistriaitalian}{}
  \gisolangtag{es}{ES}{spainspanish}{}
  \gisolangtag{es}{AR}{argentinespanish}{}
  \gisolangtag{es}{BO}{bolivianspanish}{}
  \gisolangtag{es}{CL}{chilianspanish}{}
  \gisolangtag{es}{CO}{columbianspanish}{}
  \gisolangtag{es}{CR}{costaricanspanish}{}
  \gisolangtag{es}{CU}{cubanspanish}{}
  \gisolangtag{es}{DO}{dominicanspanish}{}
  \gisolangtag{es}{EC}{ecudorianspanish}{}
  \gisolangtag{es}{SV}{elsalvadorspanish}{}
  \gisolangtag{es}{GT}{guatemalanspanish}{}
  \gisolangtag{es}{HN}{honduranspanish}{}
  \gisolangtag{es}{MX}{mexicanspanish}{}
  \gisolangtag{es}{NI}{nicaraguanspanish}{}
  \gisolangtag{es}{PA}{panamaspanish}{}
  \gisolangtag{es}{PY}{paraguayspanish}{}
  \gisolangtag{es}{PE}{peruvianspanish}{}
  \gisolangtag{es}{PR}{puertoricospanish}{}
  \gisolangtag{es}{UY}{uruguayspanish}{}
  \gisolangtag{es}{VE}{venezuelanspanish}{}
  \gisolangtag{de}{CH}{swissgerman}{}
  \gisolangtag{fr}{CH}{swissfrench}{}
  \gisolangtag{it}{CH}{swissitalian}{}
  \gisolangtag{rm}{CH}{swissromansh}{}
  \gisolangtag{it}{VA}{vatican}{}
  \gisolangtag{ga}{IE}{IEirish}{}
  \gisolangtag{ga}{GB}{GBirish}{}
  \gisolangtag{en}{IE}{IEenglish}{}
  \gisolangtagwithvar{de}{AT}{1996}{naustrian}{}
  \gisolangtag{de}{AT}{austrian}{}
  \gisolangtag{id}{IN}{bahasa}{}
  \gisolangtag{ms}{MY}{malay}{}
  \gisolangtag{hr}{HR}{croatia}{}
  \gisolangtagwithvar{de}{DE}{1996}{ngermanDE}{}
  \gisolangtagwithvar{de}{CH}{1996}{nswissgerman}{}
  \gisolangtag{hu}{HU}{hungarian}{}
  \gisolangtag{gd}{GB}{GBscottish}{}
  \gisolangtag{cy}{GB}{GBwelsh}{}
  % PREDEFINED ROOT LANGUAGE TAGS
  \grootlangtag{abkhaz}{ab}{}
  \grootlangtag{afar}{aa}{}
  \grootlangtag{afrikaans}{af}{}
  \grootlangtag{akan}{ak}{}
  \grootlangtag{albanian}{sq}{}
  \grootlangtagwithreg{amharic}{am}{ET}{}
  \grootlangtag{anglosaxon}{ang}{}
  \grootlangtag{apache}{apa}{}
  \grootlangtag{arabic}{ar}{}
  \grootlangtagwithreg{aragonese}{an}{ES}{}
  \grootlangtag{armenian}{hy}{}
  \grootlangtag{assamese}{as}{}
  \grootlangtag{asturian}{ast}{}
  \grootlangtag{avaric}{av}{}
  \grootlangtag{avestan}{ae}{}
  \grootlangtag{aymara}{ay}{}
  \grootlangtag{azerbaijani}{az}{}
  \grootlangtagwithreg{bahasai}{id}{IN}{}
  \grootlangtagwithreg{bahasam}{ms}{MY}{}
  \grootlangtagwithreg{bambara}{bm}{ML}{}
  \grootlangtag{bashkir}{ba}{}
  \grootlangtag{basque}{eu}{}
  \grootlangtag{belarusian}{be}{}
  \grootlangtag{bengali}{bn}{}
  \grootlangtag{berber}{ber}{}
  \grootlangtag{bihari}{bh}{}
  \grootlangtagwithreg{bislama}{bi}{VU}{}
  \grootlangtagwithreg{bokmal}{nb}{NO}{}
  \grootlangtag{bosnian}{bs}{}
  \grootlangtagwithreg{breton}{br}{FR}{}
  \grootlangtag{bulgarian}{bg}{}
  \grootlangtag{burmese}{my}{}
  \grootlangtag{catalan}{ca}{}
  \grootlangtag{chamorro}{ch}{}
  \grootlangtag{chechen}{ce}{}
  \grootlangtag{chichewa}{ny}{}
  \grootlangtag{chinese}{zh}{}
  \grootlangtag{churchslavonic}{cu}{}
  \grootlangtagwithreg{chuvash}{cv}{RU}{}
  \grootlangtag{coptic}{cop}{}
  \grootlangtagwithreg{cornish}{kw}{GB}{}
  \grootlangtag{corsican}{co}{}
  \grootlangtag{cree}{cr}{}
  \grootlangtag{croatian}{hr}{}
  \grootlangtag{czech}{cs}{}
  \grootlangtag{danish}{da}{}
  \grootlangtagwithreg{divehi}{dv}{MV}{}
  \grootlangtag{dutch}{nl}{}
  \grootlangtagwithreg{dzongkha}{dz}{BT}{}
  \grootlangtagwithreg{easternpunjabi}{pa}{IN}{}
  \grootlangtag{english}{en}{}
  \grootlangtag{esperanto}{eo}{}
  \grootlangtag{estonian}{et}{}
  \grootlangtag{ewe}{ee}{}
  \grootlangtag{faroese}{fo}{}
  \grootlangtag{farsi}{fa}{}
  \grootlangtagwithreg{fijian}{fj}{FJ}{}
  \grootlangtag{finnish}{fi}{}
  \grootlangtag{french}{fr}{}
  \grootlangtagwithreg{friulan}{fur}{IT}{}
  \grootlangtag{fula}{ff}{}
  \grootlangtag{galician}{gl}{}
  \grootlangtagwithreg{ganda}{lg}{UG}{}
  \grootlangtag{georgian}{ka}{}
  \grootlangtag{german}{de}{}
  \grootlangtag{greek}{el}{}
  \grootlangtag{guarani}{gn}{}
  \grootlangtag{gujarati}{gu}{}
  \grootlangtagwithreg{haitian}{ht}{HT}{}
  \grootlangtag{hausa}{ha}{}
  \grootlangtag{hebrew}{he}{}
  \grootlangtag{herero}{hz}{}
  \grootlangtag{hindi}{hi}{}
  \grootlangtagwithreg{hirimotu}{ho}{PG}{}
  \grootlangtagwithreg{icelandic}{is}{IS}{}
  \grootlangtag{ido}{io}{}
  \grootlangtag{igbo}{ig}{}
  \grootlangtag{interlingua}{ia}{}
  \grootlangtag{interlingue}{ie}{}
  \grootlangtag{inuktitut}{iu}{}
  \grootlangtag{inupiaq}{ik}{}
  \grootlangtag{irish}{ga}{}
  \grootlangtag{italian}{it}{}
  \grootlangtag{japanese}{ja}{}
  \grootlangtag{javanese}{jv}{}
  \grootlangtag{kalaallisut}{kl}{}
  \grootlangtagwithreg{kannada}{kn}{IN}{}
  \grootlangtag{kanuri}{kr}{}
  \grootlangtagwithreg{kashmiri}{ks}{IN}{}
  \grootlangtag{kazakh}{kk}{}
  \grootlangtag{khmer}{km}{}
  \grootlangtag{kikuyu}{ki}{}
  \grootlangtag{kinyarwanda}{rw}{}
  \grootlangtag{kirundi}{rn}{}
  \grootlangtagwithreg{komi}{kv}{RU}{}
  \grootlangtag{kongo}{kg}{}
  \grootlangtag{korean}{ko}{}
  \grootlangtag{kurdish}{ku}{}
  \grootlangtag{kwanyama}{kj}{}
  \grootlangtag{kyrgyz}{ky}{}
  \grootlangtag{lao}{lo}{}
  \grootlangtag{latin}{la}{}
  \grootlangtag{latvian}{lv}{}
  \grootlangtag{limburgish}{li}{}
  \grootlangtag{lingala}{ln}{}
  \grootlangtag{lithuanian}{lt}{}
  \grootlangtagwithreg{lsorbian}{dsb}{DE}{}
  \grootlangtagwithreg{lubakatanga}{lu}{CD}{}
  \grootlangtag{luxembourgish}{lb}{}
  \grootlangtag{macedonian}{mk}{}
  \grootlangtag{magyar}{hu}{}
  \grootlangtag{malagasy}{mg}{}
  \grootlangtagwithreg{malayalam}{ml}{IN}{}
  \grootlangtag{maltese}{mt}{}
  \grootlangtagwithreg{manx}{gv}{IM}{}
  \grootlangtagwithreg{maori}{mi}{NZ}{}
  \grootlangtagwithreg{marathi}{mr}{IN}{}
  \grootlangtagwithreg{marshallese}{mh}{MH}{}
  \grootlangtag{mongolian}{mn}{}
  \grootlangtagwithreg{nauruan}{na}{NR}{}
  \grootlangtagwithreg{navajo}{nv}{US}{}
  \grootlangtag{ndonga}{ng}{}
  \grootlangtag{nepali}{ne}{}
  \grootlangtag{nko}{nqo}{}
  \grootlangtag{northernndebele}{nd}{}
  \grootlangtagwithreg{nynorsk}{nn}{NO}{}
  \grootlangtag{norsk}{no}{}
  \grootlangtag{northernsotho}{nso}{}
  \grootlangtagwithreg{nuosu}{ii}{CN}{}
  \grootlangtag{occitan}{oc}{}
  \grootlangtag{ojibwe}{oj}{}
  \grootlangtag{oromo}{om}{}
  \grootlangtag{oriya}{or}{}
  \grootlangtag{ossetian}{os}{}
  \grootlangtag{pali}{pi}{}
  \grootlangtag{pashto}{ps}{}
  \grootlangtagwithreg{piedmontese}{pms}{IT}{}
  \grootlangtag{polish}{pl}{}
  \grootlangtag{portuges}{pt}{}
  \grootlangtag{quechua}{qu}{}
  \grootlangtag{romanian}{ro}{}
  \grootlangtagwithreg{romansh}{rm}{CH}{}
  \grootlangtag{russian}{ru}{}
  \grootlangtag{samin}{se}{}
  \grootlangtag{sanskrit}{sa}{}
  \grootlangtag{samoan}{sm}{}
  \grootlangtag{sango}{sg}{}
  \grootlangtagwithreg{sardinian}{sc}{IT}{}
  \grootlangtag{scots}{sco}{}
  \grootlangtag{scottish}{gd}{}
  \grootlangtag{serbian}{sr}{}
  \grootlangtag{shona}{sn}{}
  \grootlangtag{sindhi}{sd}{}
  \grootlangtagwithreg{sinhalese}{si}{LK}{}
  \grootlangtag{slovak}{sk}{}
  \grootlangtag{slovene}{sl}{}
  \grootlangtag{somali}{so}{}
  \grootlangtagwithreg{southernndebele}{nr}{ZA}{}
  \grootlangtag{southernsotho}{st}{}
  \grootlangtag{spanish}{es}{}
  \grootlangtag{sudanese}{su}{}
  \grootlangtag{swahili}{sw}{}
  \grootlangtag{swati}{ss}{}
  \grootlangtag{swedish}{sv}{}
  \grootlangtag{syriac}{syr}{}
  \grootlangtagwithreg{tagalog}{tl}{PH}{}
  \grootlangtagwithreg{tahitian}{ty}{PF}{}
  \grootlangsametag{tai}{}
  \grootlangtag{tajik}{tg}{}
  \grootlangtag{tamil}{ta}{}
  \grootlangtag{tatar}{tt}{}
  \grootlangtagwithreg{telugu}{te}{IN}{}
  \grootlangtagwithreg{thai}{th}{TH}{}
  \grootlangtag{tibetan}{bo}{}
  \grootlangtag{tigrinya}{ti}{}
  \grootlangtagwithreg{tonga}{to}{TO}{}
  \grootlangtag{tsonga}{ts}{}
  \grootlangtag{tswana}{tn}{}
  \grootlangtag{turkish}{tr}{}
  \grootlangtag{turkmen}{tk}{}
  \grootlangtagwithreg{twi}{tw}{GH}{}
  \grootlangtagwithreg{ukrainian}{uk}{UA}{}
  \grootlangtag{undetermined}{und}{}
  \grootlangtag{urdu}{ur}{}
  \grootlangtagwithreg{usorbian}{hsb}{DE}{}
  \grootlangtagwithreg{uyghur}{ug}{CN}{}
  \grootlangtag{uzbek}{uz}{}
  \grootlangtagwithreg{venda}{ve}{ZA}{}
  \grootlangtag{vietnamese}{vi}{}
  \grootlangtag{volapuk}{vo}{}
  \grootlangtag{walloon}{wa}{}
  \grootlangtag{welsh}{cy}{}
  \grootlangtagwithreg{westernfrisian}{fy}{NL}{}
  \grootlangtag{wolof}{wo}{}
  \grootlangtag{xhosa}{xh}{}
  \grootlangtag{yiddish}{yi}{}
  \grootlangtag{yoruba}{yo}{}
  \grootlangtagwithreg{zhuang}{za}{CN}{}
  \grootlangtag{zulu}{zu}{}
  % PREDEFINED NON-ISO DIALECTS
  \gdialecttag{acadian}{french}{}
  \gdialecttagwithreg{american}{english}{US}{}
  \gdialecttagwithreg{australian}{english}{AU}{}
  \gdialecttagwithreg{austrian}{german}{AT}{}
  \gdialecttagwithreg{naustrian}{german}{AT-1996}{}
  \gdialecttagwithreg{bahasa}{bahasai}{IN}{}
  \gdialecttagwithreg{brazil}{portuges}{BR}{}
  \gdialecttagwithreg{brazilian}{portuges}{BR}{}
  \gdialecttagwithreg{british}{english}{GB}{}
  \gdialecttagwithreg{canadian}{english}{CA}{}
  \gdialecttagwithreg{canadien}{french}{CA}{}
  \gdialecttagwithreg{croatia}{croatian}{HR}{}
  \gdialecttagwithreg{istriacountycroatian}{croatian}{HR}{}
  \gdialecttagwithreg{istriacountyitalian}{italian}{HR}{}
  \gdialecttagwithreg{netherlands}{dutch}{NL}{}
  \gdialecttag{persian}{farsi}{}
  \gdialecttagwithreg{flemish}{dutch}{BE}{}
  \gdialecttag{francais}{french}{}
  \gdialecttag{frenchb}{french}{}
  \gdialecttagwithreg{france}{french}{FR}{}
  \gdialecttagwithreg{belgique}{french}{BE}{}
  \gdialecttagwithreg{belgiangerman}{german}{BE}{}
  \gdialecttagwithmapandreg{nbelgiangerman}{german}{BE-1996}{ngerman}{}
  \gdialecttagwithreg{friulian}{friulan}{IT}{}
  \gdialecttagwithreg{friulano}{friulan}{IT}{}
  \gdialecttagwithreg{furlan}{friulan}{IT}{}
  \gdialecttag{kurmanji}{kurdish}{}
  \gdialecttag{galicien}{galician}{}
  \gdialecttag{deutsch}{german}{}
  \gdialecttagsuppl{ngerman}{german}{1996}{}
  \gdialecttagsupplwithmap{ngermanb}{german}{1996}{ngerman}{}
  \gdialecttag{germanb}{german}{}
  \gdialecttagwithmapandreg{ngermanDE}{german}{DE-1996}{ngerman}{}
  \gdialecttagwithreg{germanDE}{german}{DE}{}
  \gdialecttagwithreg{hungarian}{magyar}{HU}{}
  \gdialecttagwithreg{indon}{bahasai}{IN}{}
  \gdialecttagwithreg{indonesian}{bahasai}{IN}{}
  \gdialecttag{gaeilge}{irish}{}
  \gdialecttagwithreg{IEirish}{irish}{IE}{}
  \gdialecttagwithreg{GBirish}{irish}{GB}{}
  \gdialecttagwithmapandreg{IEenglish}{english}{IE}{british}{}
  \gdialecttagwithreg{italy}{italian}{IT}{}
  \gdialecttagwithreg{vatican}{italian}{VA}{}
  \gdialecttagwithreg{sanmarino}{italian}{SM}{}
  \gdialecttagwithreg{sloveneistriaitalian}{italian}{SI}{}
  \gdialecttagwithmapandreg{jerseyenglish}{english}{JE}{british}{}
  \gdialecttagwithreg{jerseyfrench}{french}{JE}{}
  \gdialecttagwithmapandreg{guernseyenglish}{english}{GG}{british}{}
  \gdialecttagwithreg{guernseyfrench}{french}{GG}{}
  \gdialecttag{latein}{latin}{}
  \gdialecttagwithreg{lowersorbian}{lsorbian}{DE}{}
  \gdialecttagwithreg{malay}{bahasam}{MY}{}
  \gdialecttagwithreg{meyalu}{bahasam}{MY}{}
  \gdialecttagwithreg{maltamaltese}{maltese}{MT}{}
  \gdialecttagwithmapandreg{maltaenglish}{english}{MT}{british}{}
  \gdialecttagwithreg{newzealand}{english}{NZ}{}
  \gdialecttagwithmapandreg{isleofmanenglish}{english}{IM}{british}{}
  \gdialecttagwithreg{norwegian}{norsk}{NO}{}
  \gdialecttagwithreg{piemonteis}{piedmontese}{IT}{}
  \gdialecttag{polutonikogreek}{greek}{}
  \gdialecttag{polutoniko}{greek}{}
  \gdialecttag{portuguese}{portuges}{}
  \gdialecttagwithreg{portugal}{portuges}{PT}{}
  \gdialecttag{romansch}{romansh}{}
  \gdialecttag{rumantsch}{romansh}{}
  \gdialecttag{romanche}{romansh}{}
  \gdialecttag{russianb}{russian}{}
  \gdialecttag{gaelic}{scottish}{}
  \gdialecttagwithreg{GBscottish}{scottish}{GB}{}
  \gdialecttagsuppl{serbianc}{serbian}{Cyrl}{}
  \gdialecttagsuppl{serbianl}{serbian}{Latn}{}
  \gdialecttag{slovenian}{slovene}{}
  \gdialecttagwithmapandreg{slovenia}{slovene}{SI}{slovenian}{}
  \gdialecttagwithmapandreg{sloveneistriaslovenian}{slovene}{SI}{slovenian}{}
  \gdialecttagwithreg{spainspanish}{spanish}{ES}{}
  \gdialecttagwithreg{argentinespanish}{spanish}{AR}{}
  \gdialecttagwithreg{bolivianspanish}{spanish}{BO}{}
  \gdialecttagwithreg{chilianspanish}{spanish}{CL}{}
  \gdialecttagwithreg{columbianspanish}{spanish}{CO}{}
  \gdialecttagwithreg{costaricanspanish}{spanish}{CR}{}
  \gdialecttagwithreg{cubanspanish}{spanish}{CU}{}
  \gdialecttagwithreg{dominicanspanish}{spanish}{DO}{}
  \gdialecttagwithreg{ecudorianspanish}{spanish}{EC}{}
  \gdialecttagwithreg{elsalvadorspanish}{spanish}{SV}{}
  \gdialecttagwithreg{guatemalanspanish}{spanish}{GT}{}
  \gdialecttagwithreg{honduranspanish}{spanish}{HN}{}
  \gdialecttagwithreg{mexicanspanish}{spanish}{MX}{}
  \gdialecttagwithreg{nicaraguanspanish}{spanish}{NI}{}
  \gdialecttagwithreg{panamaspanish}{spanish}{PA}{}
  \gdialecttagwithreg{paraguayspanish}{spanish}{PY}{}
  \gdialecttagwithreg{peruvianspanish}{spanish}{PE}{}
  \gdialecttagwithreg{puertoricospanish}{spanish}{PR}{}
  \gdialecttagwithreg{uruguayspanish}{spanish}{UY}{}
  \gdialecttagwithreg{venezuelanspanish}{spanish}{VE}{}
  \gdialecttagwithreg{swissgerman}{german}{CH}{}
  \gdialecttagwithmapandreg{nswissgerman}{german}{CH-1996}{ngerman}{}
  \gdialecttagwithreg{swissfrench}{french}{CH}{}
  \gdialecttagwithreg{swissitalian}{italian}{CH}{}
  \gdialecttagwithreg{swissromansh}{romansh}{CH}{}
  \gdialecttagwithreg{UKenglish}{english}{GB}{}
  \gdialecttagwithreg{ukraineb}{ukrainian}{UA}{}
  \gdialecttagwithreg{ukraine}{ukrainian}{UA}{}
  \gdialecttagwithreg{uppersorbian}{usorbian}{DE}{}
  \gdialecttagwithreg{USenglish}{english}{US}{}
  \gdialecttag{valencian}{catalan}{}
  \gdialecttag{valencien}{catalan}{}
  \gdialecttag{cymraeg}{welsh}{}
  \gdialecttagwithreg{GBwelsh}{welsh}{GB}{}
  \gdialecttag{nil}{undetermined}{}
  % PREDEFINED REGIONS
  \gregion{004}{AF}{AFG}{}%
  \gregion{248}{AX}{ALA}{}%
  \gregion{008}{AL}{ALB}{}%
  \gregion{012}{DZ}{DZA}{}%
  \gregion{016}{AS}{ASM}{}%
  \gregion{020}{AD}{AND}{}%
  \gregion{024}{AO}{AGO}{}%
  \gregion{660}{AI}{AIA}{}%
  \gregion{010}{AQ}{ATA}{}%
  \gregion{028}{AG}{ATG}{}%
  \gregion{032}{AR}{ARG}{}%
  \gregion{051}{AM}{ARM}{}%
  \gregion{533}{AW}{ABW}{}%
  \gregion{036}{AU}{AUS}{}%
  \gregion{040}{AT}{AUT}{}%
  \gregion{031}{AZ}{AZE}{}%
  \gregion{044}{BS}{BHS}{}%
  \gregion{048}{BH}{BHR}{}%
  \gregion{050}{BD}{BGD}{}%
  \gregion{052}{BB}{BRB}{}%
  \gregion{112}{BY}{BLR}{}%
  \gregion{056}{BE}{BEL}{}%
  \gregion{084}{BZ}{BLZ}{}%
  \gregion{204}{BJ}{BEN}{}%
  \gregion{060}{BM}{BMU}{}%
  \gregion{064}{BT}{BTN}{}%
  \gregion{068}{BO}{BOL}{}%
  \gregion{535}{BQ}{BES}{}%
  \gregion{070}{BA}{BIH}{}%
  \gregion{072}{BW}{BWA}{}%
  \gregion{074}{BV}{BVT}{}%
  \gregion{076}{BR}{BRA}{}%
  \gregion{086}{IO}{IOT}{}%
  \gregion{096}{BN}{BRN}{}%
  \gregion{100}{BG}{BGR}{}%
  \gregion{854}{BF}{BFA}{}%
  \gregion{108}{BI}{BDI}{}%
  \gregion{132}{CV}{CPV}{}%
  \gregion{116}{KH}{KHM}{}%
  \gregion{120}{CM}{CMR}{}%
  \gregion{124}{CA}{CAN}{}%
  \gregion{136}{KY}{CYM}{}%
  \gregion{140}{CF}{CAF}{}%
  \gregion{148}{TD}{TCD}{}%
  \gregion{152}{CL}{CHL}{}%
  \gregion{156}{CN}{CHN}{}%
  \gregion{162}{CX}{CXR}{}%
  \gregion{166}{CC}{CCK}{}%
  \gregion{170}{CO}{COL}{}%
  \gregion{174}{KM}{COM}{}%
  \gregion{180}{CD}{COD}{}%
  \gregion{178}{CG}{COG}{}%
  \gregion{184}{CK}{COK}{}%
  \gregion{188}{CR}{CRI}{}%
  \gregion{384}{CI}{CIV}{}%
  \gregion{191}{HR}{HRV}{}%
  \gregion{192}{CU}{CUB}{}%
  \gregion{531}{CW}{CUW}{}%
  \gregion{196}{CY}{CYP}{}%
  \gregion{203}{CZ}{CZE}{}%
  \gregion{208}{DK}{DNK}{}%
  \gregion{262}{DJ}{DJI}{}%
  \gregion{212}{DM}{DMA}{}%
  \gregion{214}{DO}{DOM}{}%
  \gregion{218}{EC}{ECU}{}%
  \gregion{818}{EG}{EGY}{}%
  \gregion{222}{SV}{SLV}{}%
  \gregion{226}{GQ}{GNQ}{}%
  \gregion{232}{ER}{ERI}{}%
  \gregion{233}{EE}{EST}{}%
  \gregion{231}{ET}{ETH}{}%
  \gregion{238}{FK}{FLK}{}%
  \gregion{234}{FO}{FRO}{}%
  \gregion{242}{FJ}{FJI}{}%
  \gregion{246}{FI}{FIN}{}%
  \gregion{250}{FR}{FRA}{}%
  \gregion{254}{GF}{GUF}{}%
  \gregion{258}{PF}{PYF}{}%
  \gregion{260}{TF}{ATF}{}%
  \gregion{266}{GA}{GAB}{}%
  \gregion{270}{GM}{GMB}{}%
  \gregion{268}{GE}{GEO}{}%
  \gregion{276}{DE}{DEU}{}%
  \gregion{288}{GH}{GHA}{}%
  \gregion{292}{GI}{GIB}{}%
  \gregion{300}{GR}{GRC}{}%
  \gregion{304}{GL}{GRL}{}%
  \gregion{308}{GD}{GRD}{}%
  \gregion{312}{GP}{GLP}{}%
  \gregion{316}{GU}{GUM}{}%
  \gregion{320}{GT}{GTM}{}%
  \gregion{831}{GG}{GGY}{}%
  \gregion{324}{GN}{GIN}{}%
  \gregion{624}{GW}{GNB}{}%
  \gregion{328}{GY}{GUY}{}%
  \gregion{332}{HT}{HTI}{}%
  \gregion{334}{HM}{HMD}{}%
  \gregion{336}{VA}{VAT}{}%
  \gregion{340}{HN}{HND}{}%
  \gregion{344}{HK}{HKG}{}%
  \gregion{348}{HU}{HUN}{}%
  \gregion{352}{IS}{ISL}{}%
  \gregion{356}{IN}{IND}{}%
  \gregion{360}{ID}{IDN}{}%
  \gregion{364}{IR}{IRN}{}%
  \gregion{368}{IQ}{IRQ}{}%
  \gregion{372}{IE}{IRL}{}%
  \gregion{833}{IM}{IMN}{}%
  \gregion{376}{IL}{ISR}{}%
  \gregion{380}{IT}{ITA}{}%
  \gregion{388}{JM}{JAM}{}%
  \gregion{392}{JP}{JPN}{}%
  \gregion{832}{JE}{JEY}{}%
  \gregion{400}{JO}{JOR}{}%
  \gregion{398}{KZ}{KAZ}{}%
  \gregion{404}{KE}{KEN}{}%
  \gregion{296}{KI}{KIR}{}%
  \gregion{408}{KP}{PRK}{}%
  \gregion{410}{KR}{KOR}{}%
  \gregion{414}{KW}{KWT}{}%
  \gregion{417}{KG}{KGZ}{}%
  \gregion{418}{LA}{LAO}{}%
  \gregion{428}{LV}{LVA}{}%
  \gregion{422}{LB}{LBN}{}%
  \gregion{426}{LS}{LSO}{}%
  \gregion{430}{LR}{LBR}{}%
  \gregion{434}{LY}{LBY}{}%
  \gregion{438}{LI}{LIE}{}%
  \gregion{440}{LT}{LTU}{}%
  \gregion{442}{LU}{LUX}{}%
  \gregion{446}{MO}{MAC}{}%
  \gregion{807}{MK}{MKD}{}%
  \gregion{450}{MG}{MDG}{}%
  \gregion{454}{MW}{MWI}{}%
  \gregion{458}{MY}{MYS}{}%
  \gregion{462}{MV}{MDV}{}%
  \gregion{466}{ML}{MLI}{}%
  \gregion{470}{MT}{MLT}{}%
  \gregion{584}{MH}{MHL}{}%
  \gregion{474}{MQ}{MTQ}{}%
  \gregion{478}{MR}{MRT}{}%
  \gregion{480}{MU}{MUS}{}%
  \gregion{175}{YT}{MYT}{}%
  \gregion{484}{MX}{MEX}{}%
  \gregion{583}{FM}{FSM}{}%
  \gregion{498}{MD}{MDA}{}%
  \gregion{492}{MC}{MCO}{}%
  \gregion{496}{MN}{MNG}{}%
  \gregion{499}{ME}{MNE}{}%
  \gregion{500}{MS}{MSR}{}%
  \gregion{504}{MA}{MAR}{}%
  \gregion{508}{MZ}{MOZ}{}%
  \gregion{104}{MM}{MMR}{}%
  \gregion{516}{NA}{NAM}{}%
  \gregion{520}{NR}{NRU}{}%
  \gregion{524}{NP}{NPL}{}%
  \gregion{528}{NL}{NLD}{}%
  \gregion{540}{NC}{NCL}{}%
  \gregion{554}{NZ}{NZL}{}%
  \gregion{558}{NI}{NIC}{}%
  \gregion{562}{NE}{NER}{}%
  \gregion{566}{NG}{NGA}{}%
  \gregion{570}{NU}{NIU}{}%
  \gregion{574}{NF}{NFK}{}%
  \gregion{580}{MP}{MNP}{}%
  \gregion{578}{NO}{NOR}{}%
  \gregion{512}{OM}{OMN}{}%
  \gregion{586}{PK}{PAK}{}%
  \gregion{585}{PW}{PLW}{}%
  \gregion{275}{PS}{PSE}{}%
  \gregion{591}{PA}{PAN}{}%
  \gregion{598}{PG}{PNG}{}%
  \gregion{600}{PY}{PRY}{}%
  \gregion{604}{PE}{PER}{}%
  \gregion{608}{PH}{PHL}{}%
  \gregion{612}{PN}{PCN}{}%
  \gregion{616}{PL}{POL}{}%
  \gregion{620}{PT}{PRT}{}%
  \gregion{630}{PR}{PRI}{}%
  \gregion{634}{QA}{QAT}{}%
  \gregion{638}{RE}{REU}{}%
  \gregion{642}{RO}{ROU}{}%
  \gregion{643}{RU}{RUS}{}%
  \gregion{646}{RW}{RWA}{}%
  \gregion{652}{BL}{BLM}{}%
  \gregion{654}{SH}{SHN}{}%
  \gregion{659}{KN}{KNA}{}%
  \gregion{662}{LC}{LCA}{}%
  \gregion{663}{MF}{MAF}{}%
  \gregion{666}{PM}{SPM}{}%
  \gregion{670}{VC}{VCT}{}%
  \gregion{882}{WS}{WSM}{}%
  \gregion{674}{SM}{SMR}{}%
  \gregion{678}{ST}{STP}{}%
  \gregion{682}{SA}{SAU}{}%
  \gregion{686}{SN}{SEN}{}%
  \gregion{688}{RS}{SRB}{}%
  \gregion{690}{SC}{SYC}{}%
  \gregion{694}{SL}{SLE}{}%
  \gregion{702}{SG}{SGP}{}%
  \gregion{534}{SX}{SXM}{}%
  \gregion{703}{SK}{SVK}{}%
  \gregion{705}{SI}{SVN}{}%
  \gregion{090}{SB}{SLB}{}%
  \gregion{706}{SO}{SOM}{}%
  \gregion{710}{ZA}{ZAF}{}%
  \gregion{239}{GS}{SGS}{}%
  \gregion{728}{SS}{SSD}{}%
  \gregion{724}{ES}{ESP}{}%
  \gregion{144}{LK}{LKA}{}%
  \gregion{729}{SD}{SDN}{}%
  \gregion{740}{SR}{SUR}{}%
  \gregion{744}{SJ}{SJM}{}%
  \gregion{748}{SZ}{SWZ}{}%
  \gregion{752}{SE}{SWE}{}%
  \gregion{756}{CH}{CHE}{}%
  \gregion{760}{SY}{SYR}{}%
  \gregion{158}{TW}{TWN}{}%
  \gregion{762}{TJ}{TJK}{}%
  \gregion{834}{TZ}{TZA}{}%
  \gregion{764}{TH}{THA}{}%
  \gregion{626}{TL}{TLS}{}%
  \gregion{768}{TG}{TGO}{}%
  \gregion{772}{TK}{TKL}{}%
  \gregion{776}{TO}{TON}{}%
  \gregion{780}{TT}{TTO}{}%
  \gregion{788}{TN}{TUN}{}%
  \gregion{792}{TR}{TUR}{}%
  \gregion{795}{TM}{TKM}{}%
  \gregion{796}{TC}{TCA}{}%
  \gregion{798}{TV}{TUV}{}%
  \gregion{800}{UG}{UGA}{}%
  \gregion{804}{UA}{UKR}{}%
  \gregion{784}{AE}{ARE}{}%
  \gregion{826}{GB}{GBR}{}%
  \gregion{581}{UM}{UMI}{}%
  \gregion{840}{US}{USA}{}%
  \gregion{858}{UY}{URY}{}%
  \gregion{860}{UZ}{UZB}{}%
  \gregion{548}{VU}{VUT}{}%
  \gregion{862}{VE}{VEN}{}%
  \gregion{704}{VN}{VNM}{}%
  \gregion{092}{VG}{VGB}{}%
  \gregion{850}{VI}{VIR}{}%
  \gregion{876}{WF}{WLF}{}%
  \gregion{732}{EH}{ESH}{}%
  \gregion{887}{YE}{YEM}{}%
  \gregion{894}{ZM}{ZMB}{}%
  \gregion{716}{ZW}{ZWE}{}%
  % PREDEFINED SCRIPTS
  \gscript{Adlm}{166}{Adlam}{RL}{}{}
  \gscript{Afak}{439}{Afaka}{varies}{}{}
  \gscript{Aghb}{239}{Caucasian Albanian}{LR}{}{}
  \gscript{Ahom}{338}{Ahom, Tai Ahom}{LR}{}{}
  \gscript{Arab}{160}{Arabic}{RL}{}{}
  \gscript{Aran}{161}{Arabic (Nastaliq variant)}{RL}{}{}
  \gscript{Armi}{124}{Imperial Aramaic}{RL}{}{}
  \gscript{Armn}{230}{Armenian}{LR}{}{}
  \gscript{Avst}{134}{Avestan}{RL}{}{}
  \gscript{Bali}{360}{Balinese}{LR}{}{}
  \gscript{Bamu}{435}{Bamum}{LR}{}{}
  \gscript{Bass}{259}{Bassa Vah}{LR}{}{}
  \gscript{Batk}{365}{Batak}{LR}{}{}
  \gscript{Beng}{334}{Bhaiksuki}{LR}{}{}
  \gscript{Blis}{550}{Blissymbols}{varies}{}{}
  \gscript{Bopo}{285}{Bopomofo}{LR}{}{}
  \gscript{Brah}{300}{Brahmi}{LR}{}{}
  \gscript{Brai}{570}{Braille}{LR}{}{}
  \gscript{Bugi}{367}{Buginese}{LR}{}{}
  \gscript{Buhd}{372}{Buhid}{LR}{}{}
  \gscript{Cakm}{349}{Chakma}{LR}{}{}
  \gscript{Cans}{440}{Unified Canadian Aboriginal Syllabics}{LR}{}{}
  \gscript{Cari}{201}{Carian}{LR}{}{}
  \gscript{Cham}{358}{Cham}{LR}{}{}
  \gscript{Cher}{445}{Cherokee}{LR}{}{}
  \gscript{Cirt}{291}{Cirth}{varies}{}{}
  \gscript{Copt}{204}{Coptic}{LR}{}{}
  \gscript{Cprt}{403}{Cypriot}{RL}{}{}
  \gscript{Cyrl}{220}{Cyrillic}{LR}{}{}
  \gscript{Cyrs}{221}{Cyrillic (Old Church Slavonic variant)}{varies}{}{}
  \gscript{Deva}{315}{Devanagari (Nagari)}{LR}{}{}
  \gscript{Dsrt}{250}{Deseret (Mormon)}{LR}{}{}
  \gscript{Dupl}{755}{Duployan shorthand, Duployan stenography}{LR}{}{}
  \gscript{Egyd}{070}{Egyptian demotic}{RL}{}{}
  \gscript{Egyh}{060}{Egyptian hieratic}{RL}{}{}
  \gscript{Egyp}{050}{Egyptian hieroglyphs}{LR}{}{}
  \gscript{Elba}{226}{Elbasan}{LR}{}{}
  \gscript{Ethi}{430}{Ethiopic (Ge'ez)}{LR}{}{}
  \gscript{Geok}{241}{Khutsuri (Asomtavruli and Nuskhuri)}{LR}{}{}
  \gscript{Geor}{240}{Georgian (Mkhedruli)}{LR}{}{}
  \gscript{Glag}{225}{Glagolitic}{LR}{}{}
  \gscript{Goth}{206}{Gothic}{LR}{}{}
  \gscript{Gran}{343}{Grantha}{LR}{}{}
  \gscript{Grek}{200}{Greek}{LR}{}{}
  \gscript{Gujr}{320}{Gujarati}{LR}{}{}
  \gscript{Guru}{310}{Gurmukhi}{LR}{}{}
  \gscript{Hanb}{503}{Han with Bopomofo (alias for Han + Bopomofo)}{LR}{}{}
  \gscript{Hang}{286}{Hangul}{LR}{}{}
  \gscript{Hani}{500}{Han (Hanzi, Kanji, Hanja)}{LR}{}{}
  \gscript{Hano}{371}{Hanunoo}{LR}{}{}
  \gscript{Hans}{501}{Han (Simplified variant)}{varies}{}{}
  \gscript{Hant}{502}{Han (Traditional variant)}{varies}{}{}
  \gscript{Hatr}{127}{Hatran}{RL}{}{}
  \gscript{Hebr}{125}{Hebrew}{RL}{}{}
  \gscript{Hira}{410}{Hiragana}{LR}{}{}
  \gscript{Hluw}{080}{Anatolian Hieroglyphs (Luwian Hieroglyphs, Hittite Hieroglyphs)}{LR}{}{}
  \gscript{Hmng}{450}{Pahawh Hmong}{LR}{}{}
  \gscript{Hrkt}{412}{Japanese syllabaries (alias for Hiragana + Katakana)}{varies}{}{}
  \gscript{Hung}{176}{Old Hungarian (Hungarian Runic)}{RL}{}{}
  \gscript{Inds}{610}{Indus (Harappan)}{RL}{}{}
  \gscript{Ital}{210}{Old Italic (Etruscan, Oscan, etc.)}{LR}{}{}
  \gscript{Jamo}{284}{Jamo (alias for Jamo subset of Hangul)}{LR}{}{}
  \gscript{Java}{361}{Javanese}{LR}{}{}
  \gscript{Jpan}{413}{Japanese (alias for Han + Hiragana + Katakana)}{varies}{}{}
  \gscript{Jurc}{510}{Jurchen}{LR}{}{}
  \gscript{Kali}{357}{Kayah Li}{LR}{}{}
  \gscript{Kana}{411}{Katakana}{LR}{}{}
  \gscript{Khar}{305}{Kharoshthi}{RL}{}{}
  \gscript{Khmr}{355}{Khmer}{LR}{}{}
  \gscript{Khoj}{322}{Khojki}{LR}{}{}
  \gscript{Kitl}{505}{Khitan large script}{LR}{}{}
  \gscript{Kits}{288}{Khitan small script}{TB}{}{}
  \gscript{Knda}{345}{Kannada}{LR}{}{}
  \gscript{Kore}{287}{Korean (alias for Hangul + Han)}{LR}{}{}
  \gscript{Kpel}{436}{Kpelle}{LR}{}{}
  \gscript{Kthi}{317}{Kaithi}{LR}{}{}
  \gscript{Lana}{351}{Tai Tham (Lanna)}{LR}{}{}
  \gscript{Laoo}{356}{Lao}{LR}{}{}
  \gscript{Latf}{217}{Latin (Fraktur variant)}{varies}{}{}
  \gscript{Latg}{216}{Latin (Gaelic variant)}{LR}{}{}
  \gscript{Latn}{215}{Latin}{LR}{}{}
  \gscript{Leke}{364}{Leke}{LR}{}{}
  \gscript{Lepc}{335}{Lepcha}{LR}{}{}
  \gscript{Limb}{336}{Limbu}{LR}{}{}
  \gscript{Lina}{400}{Linear A}{LR}{}{}
  \gscript{Linb}{401}{Linear B}{LR}{}{}
  \gscript{Lisu}{399}{Lisu (Fraser)}{LR}{}{}
  \gscript{Loma}{437}{Loma}{LR}{}{}
  \gscript{Lyci}{202}{Lycian}{LR}{}{}
  \gscript{Lydi}{116}{Lydian}{RL}{}{}
  \gscript{Mahj}{314}{Mahajani}{LR}{}{}
  \gscript{Mand}{140}{Mandaic, Mandaean}{RL}{}{}
  \gscript{Mani}{139}{Manichaean}{RL}{}{}
  \gscript{Marc}{332}{Marchen}{LR}{}{}
  \gscript{Maya}{090}{Mayan hieroglyphs}{varies}{}{}
  \gscript{Mend}{438}{Mende Kikakui}{RL}{}{}
  \gscript{Merc}{101}{Meroitic Cursive}{RL}{}{}
  \gscript{Mero}{100}{Meroitic Hieroglyphs}{RL}{}{}
  \gscript{Mlym}{347}{Malayalam}{LR}{}{}
  \gscript{Modi}{324}{Modi}{LR}{}{}
  \gscript{Mong}{145}{Mongolian}{TB}{}{}
  \gscript{Moon}{218}{Moon (Moon code, Moon script, Moon type)}{varies}{}{}
  \gscript{Mroo}{199}{Mro, Mru}{LR}{}{}
  \gscript{Mtei}{337}{Meitei Mayek (Meithei, Meetei)}{LR}{}{}
  \gscript{Mult}{323}{Multani}{LR}{}{}
  \gscript{Mymr}{350}{Myanmar (Burmese)}{LR}{}{}
  \gscript{Narb}{106}{Old North Arabian (Ancient North Arabian)}{RL}{}{}
  \gscript{Nbat}{159}{Nabataean}{RL}{}{}
  \gscript{Newa}{333}{Newa, Newar, Newari}{LR}{}{}
  \gscript{Nkgb}{420}{Nakhi Geba}{LR}{}{}
  \gscript{Nkoo}{165}{N'Ko}{RL}{}{}
  \gscript{Nshu}{499}{Nushu}{LR}{}{}
  \gscript{Ogam}{212}{Ogham}{varies}{}{}
  \gscript{Olck}{261}{Ol Chiki}{LR}{}{}
  \gscript{Orkh}{175}{Old Turkic, Orkhon Runic}{RL}{}{}
  \gscript{Orya}{327}{Oriya}{LR}{}{}
  \gscript{Osge}{219}{Osage}{LR}{}{}
  \gscript{Osma}{260}{Osmanya}{LR}{}{}
  \gscript{Palm}{126}{Palmyrene}{RL}{}{}
  \gscript{Pauc}{263}{Pau Cin Hau}{LR}{}{}
  \gscript{Perm}{227}{Old Permic}{LR}{}{}
  \gscript{Phag}{331}{Phags-pa}{TB}{}{}
  \gscript{Phli}{131}{Inscriptional Pahlavi}{RL}{}{}
  \gscript{Phlp}{132}{Psalter Pahlavi}{RL}{}{}
  \gscript{Phlv}{133}{Book Pahlavi}{RL}{}{}
  \gscript{Phnx}{115}{Phoenician}{RL}{}{}
  \gscript{Piqd}{293}{Klingon (KLI plqaD)}{LR}{}{}
  \gscript{Plrd}{282}{Miao (Pollard)}{LR}{}{}
  \gscript{Prti}{130}{Inscriptional Parthian}{RL}{}{}
  \gscript{Qaaa}{900}{Reserved for private use (start)}{varies}{}{}
  \gscript{Qaai}{908}{Private use}{varies}{}{}
  \gscript{Qabx}{949}{Reserved for private use (end)}{varies}{}{}
  \gscript{Rjng}{363}{Rejang (Redjang, Kaganga)}{LR}{}{}
  \gscript{Roro}{620}{Rongorongo}{varies}{}{}
  \gscript{Runr}{211}{Runic}{LR}{}{}
  \gscript{Samr}{123}{Samaritan}{RL}{}{}
  \gscript{Sara}{292}{Sarati}{varies}{}{}
  \gscript{Sarb}{105}{Old South Arabian}{RL}{}{}
  \gscript{Saur}{344}{Saurashtra}{LR}{}{}
  \gscript{Sgnw}{095}{SignWriting}{TB}{}{}
  \gscript{Shaw}{281}{Shavian (Shaw)}{LR}{}{}
  \gscript{Shrd}{319}{Sharada}{LR}{}{}
  \gscript{Sidd}{302}{Siddham}{LR}{}{}
  \gscript{Sind}{318}{Khudawadi, Sindhi}{LR}{}{}
  \gscript{Sinh}{348}{Sinhala}{LR}{}{}
  \gscript{Sora}{398}{Sora Sompeng}{LR}{}{}
  \gscript{Sund}{362}{Sundanese}{LR}{}{}
  \gscript{Sylo}{316}{Syloti Nagri}{LR}{}{}
  \gscript{Syrc}{135}{Syriac}{RL}{}{}
  \gscript{Syre}{138}{Syriac (Estrangelo variant)}{RL}{}{}
  \gscript{Syrj}{137}{Syriac (Western variant)}{RL}{}{}
  \gscript{Syrn}{136}{Syriac (Eastern variant)}{RL}{}{}
  \gscript{Tagb}{373}{Tagbanwa}{LR}{}{}
  \gscript{Takr}{321}{Takri}{LR}{}{}
  \gscript{Tale}{353}{Tai Le}{LR}{}{}
  \gscript{Talu}{354}{New Tai Lue}{LR}{}{}
  \gscript{Taml}{346}{Tamil}{LR}{}{}
  \gscript{Tang}{520}{Tangut}{LR}{}{}
  \gscript{Tavt}{359}{Tai Viet}{LR}{}{}
  \gscript{Telu}{340}{Telugu}{LR}{}{}
  \gscript{Teng}{290}{Tengwar}{LR}{}{}
  \gscript{Tfng}{120}{Tifinagh (Berber)}{LR}{}{}
  \gscript{Tglg}{370}{Tagalog (Baybayin, Alibata)}{LR}{}{}
  \gscript{Thaa}{170}{Thaana}{RL}{}{}
  \gscript{Thai}{352}{Thai}{LR}{}{}
  \gscript{Tibt}{330}{Tibetan}{LR}{}{}
  \gscript{Tirh}{326}{Tirhuta}{LR}{}{}
  \gscript{Ugar}{040}{Ugaritic}{LR}{}{}
  \gscript{Vaii}{470}{Vai}{LR}{}{}
  \gscript{Visp}{280}{Visible Speech}{LR}{}{}
  \gscript{Wara}{262}{Warang Citi (Varang Kshiti)}{LR}{}{}
  \gscript{Wole}{480}{Woleai}{RL}{}{}
  \gscript{Xpeo}{030}{Old Persian}{LR}{}{}
  \gscript{Xsux}{020}{Cuneiform, Sumero-Akkadian}{LR}{}{}
  \gscript{Yiii}{460}{Yi}{LR}{}{}
  \gscript{Zinh}{994}{Inherited script}{inherited}{}{}
  \gscript{Zmth}{995}{Mathematical notation}{LR}{}{}
  \gscript{Zsym}{996}{Symbols}{varies}{}{}
  \gscript{Zsye}{993}{Symbols (emoji variant)}{varies}{}{}
  \gscript{Zxxx}{997}{Unwritten documents}{varies}{}{}
  \gscript{Zyyy}{998}{Undetermined script}{varies}{}{}
  \gscript{Zzzz}{999}{Uncoded script}{varies}{}{}
}

\title{tracklang.sty v1.6.5: 
tracking language options}
\author{Nicola L.C. Talbot\\[10pt]
Dickimaw Books\\
\href{https://www.dickimaw-books.com/}{\nolinkurl{dickimaw-books.com}}}
\date{2025-03-04
} 

\newcommand{\refoptstables}{\tablesref{tab:isoopts,tab:rootlangopts,tab:nonisoopts}}

\begin{document}
\maketitle

\htmlavailable

\begin{abstract}
The \sty+{tracklang} package is provided for package developers
who want a simple interface to find out which languages the user has
requested through packages such as \sty{babel} and
\sty{polyglossia}. \emph{This package doesn't provide any
translations.}
Its purpose is simply to track which languages have been requested by the
user. Generic \TeX\ code is in \file{tracklang.tex} for
non-\LaTeX\ users.

If the \idx{shellescape} is enabled or \gls{directlua} is available,
this package may also be used to query the \envvar{LCALL}
or \envvar{LANG} environment variable (see
\sectionref{sec:langsty}). Windows users, who don't have the locale
stored in environment variables, can use \app{texosquery}
in combination with \sty{tracklang}. (Similarly if \envvar{LCALL}
or \envvar{LANG} don't contain sufficient information.) In order to
use \app{texosquery} through the restricted \idx{shellescape}, you must
have at least Java~8 and set up \file{texosquery.cfg}
appropriately. (See the \app{texosquery} manual for further details.)
\end{abstract}

The fundamental aim of this generic package is to be able to
effectively say:
\begin{quote}
The user (that is, the \emph{document} author) wants to use
dialects \langtagfmt{xx-XX}, \langtagfmt{yy-YY-Scrp}, etc in their
document. Any packages used by their document that provide 
multilingual or region-dependent support should do whatever is
required to activate the settings for those languages and regions
(or warn the user that there's no support).
\end{quote}
Naturally, this is only of use if the locale-sensitive packages use
\sty{tracklang} to pick up this information, which is entirely up
to the package authors, but at the moment there's no standard method
for packages to detect the required language and region. The aim of
\sty{tracklang} is to provide that method. In particular, the
emphasis is on using \idx+{ISO} language and region codes rather than
hard-coding the various language labels used by different language
packages.

Related articles: 
\tugboat{Localisation of \TeX\ documents: \styfmt{tracklang}.}
{2016}{37}{3}{http://www.tug.org/TUGboat/tb37-3/tb117talbot.pdf},
\dickimawhref{latex/tracklang}{Localisation with \filefmt{tracklang.tex}},
and \faqspkg{tracklang}.

\frontmatter
\tableofcontents
\listoftables

\mainmatter
\part{User Guide}

\chapter{Introduction}
\label{sec:intro}

When I'm developing a package that provides multilingual support
(for example, \sty{glossaries}) it's cumbersome trying to work out
if the user has requested translations for fixed text.  This usually
involves checking if \sty{babel} or \sty{translator} or
\sty{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 \sty{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, \sty{tracklang} now checks for
\sty{babel}['s] \gls{LocaleForEach} and, if defined, will
use that command to iterate over all languages that have currently
been loaded either via package option or using \gls{babelprovide}.
Note that \qt{lazy loading} a language via \gls{selectlanguage}
in the document is too late for \sty{tracklang} to detect.

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

The \sty{tracklang} package works fairly well with
\sty{translator} but will additionally assume the root language was
also requested when a dialect is specified. So, for example,
\begin{codebox}
\cmd{usepackage}[\opt{british}]\marg{translator}
\cmd{usepackage}\marg{tracklang}
\end{codebox}
is equivalent to
\begin{compactcodebox}
\cmd{usepackage}[\opt{british}]\marg{translator}
\cmd{usepackage}[\opt{english},\opt{british}]\marg{tracklang}
\end{compactcodebox}
This means that \gls{ForEachTrackedDialect} will iterate
through the list \qt{\opt{english}\dcomma\opt{british}} instead of just
\qt{\opt{british}}, which can result in some redundancy.

If any document class or package options are passed to
\sty{tracklang}, then \sty{tracklang} won't bother checking
for known language packages. So, if the above example is changed to:
\begin{codebox}
\cmd{documentclass}[\opt{british}]\marg{article}
\cmd{usepackage}\marg{translator}
\cmd{usepackage}\marg{tracklang}
\end{codebox}
then the dialect list will just consist of \qt{\opt{british}} rather than
\qt{\opt{english},\opt{british}}. This does, however, mean that if the user mixes
class and package options, only the class options will be detected.
For example:
\begin{codebox}
\cmd{documentclass}[\opt{british}]\marg{article}
\cmd{usepackage}[\opt{french}]\marg{babel}
\cmd{usepackage}\marg{tracklang}
\end{codebox}
In this case, only the \opt{british} option will be detected. The user
can therefore use the document class option (or \sty{tracklang}
package option) to override the dialect and set the country code
(where provided). For example:
\begin{codebox}
\cmd{documentclass}[\opt{es-MX}]\marg{article}
\cmd{usepackage}[\opt{spanish}]\marg{babel}
\cmd{usepackage}\marg{tracklang}
\end{codebox}
This sets the dialect to \opt{mexicanspanish} and the root language to
\opt{spanish}. 

Predefined dialects are listed in \refoptstables. These may be 
passed in the document class options or
used in \gls{TrackPredefinedDialect}, as illustrated above. 

\Sectionref{sec:summary} provides brief examples of use for those
who want a general overview before reading the more detailed
sections.
\Sectionref{sec:generic} describes generic commands for
identifying the document languages.
\Sectionref{sec:user} 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
\sty{babel}. \Sectionref{sec:langsty} is for
developers of language definition packages who want to help other
package writers to detect what languages have been requested.

\printunsrttable
[
  type=index,
  block-style=name-other,
  other=dialect,
  toctitle={Predefined ISO Language-Region Dialects},
  title={Predefined \idx+{ISO} Language-Region Dialects. (\idx{ISO} tag or
  dialect label may be used as a
   package option or with \gls{TrackPredefinedDialect})},
  label={tab:isoopts},
  postamble={Other combinations need to be set with \gls{TrackLocale}
  or \gls{TrackLanguageTag}},
  init={%
   \renewcommand{\glstableNameTarget}[1]{\inlineglsdef[optdef]{##1}}%
   \let\glstableOtherFmt\optfmt
   \renewcommand{\glstablenameheader}{ISO Tag}%
   \renewcommand{\glstableotherheader}{Dialect Label}%
   \renewcommand{\glstableiffilter}[3]{\glsifcategory{##1}{isolangregion}{##3}{##2}}%
  }
]

\printunsrttable
[
  type=index,
  header=false,rules=false,blocksep={},clearpage,
  block-style=name,blocks=3,
  other=isotag,
  toctitle={Predefined Root Languages},
  title={Predefined Root Languages. (\fnregion Has an associated
   territory.) The corresponding tag obtained with
  \code{\gls{GetTrackedLanguageTag}\margm{dialect}} is shown in 
  parentheses},
  label={tab:rootlangopts},
  init={\let\glstableOtherFmt\optfmt
   \renewcommand{\glstableNameTarget}[1]{\inlineglsdef[optdef]{##1}}%
   \renewcommand{\glstableiffilter}[3]{\glsifcategory{##1}{rootlang}{##3}{##2}}%
  }
]

\printunsrttable
[
  type=index,
  block-style=name,rules=false,header=false,blocksep={},clearpage,
  other=tags,par=ragged,
  toctitle={Predefined Non-ISO Dialects},
  title={Predefined Non-ISO Dialects. (\fnregion Has an 
  associated territory.) The corresponding
language tag obtained with
\code{\gls{GetTrackedLanguageTag}\margm{dialect}}
is shown in parentheses. If the dialect has a corresponding mapping
for the closest matching non-root language \gls{captionsdialect} or
\gls{datedialect}, this is also included after the tag following a
slash.},
  label={tab:nonisoopts},
  init={%
   \renewcommand{\glstableiffilter}[3]{\glsifcategory{##1}{noniso}{##3}{##2}}%
   \renewcommand{\glstableNameTarget}[1]{\inlineglsdef[optdef]{##1}}%
  }
]

\chapter{Summary of Use}
\label{sec:summary}

There are three levels of use:
\begin{enumerate}
\item document level (code used by document authors);

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

\item language set-up level (code for packages that set up
the document languages, such as \sty{babel} or \sty{polyglossia}).
\end{enumerate}

\section{Document Level}
\label{sec:summary-doc}

Document level use can be divided into generic \TeX\ use 
(\sectionref{sec:tex}) and \LaTeX-specific use (\sectionref{sec:latex}).

\subsection{Generic \texorpdfstring{\TeX}{TeX}}
\label{sec:tex}

This section is for generic \TeX\ use. The \sty+{tracklang} files are
loaded with \gls{input}. See \sectionref{sec:latex} for \LaTeX\ use.

A Unix-like user wants the locale information picked up from the 
locale environment variable (the \ext+{tex} extension may be omitted):
\begin{codebox*}
\gls{input} \file{tracklang.tex} \comment{v1.3}
\gls{TrackLangFromEnv}
\comment{load packages that use tracklang for localisation}
\end{codebox*}

A Windows user wants the locale information picked up from the 
operating system (again the \ext{tex} extension may be omitted):
\begin{codebox*}
\gls{input} \file{texosquery.tex}
\gls{input} \file{tracklang.tex} \comment{v1.3}
\gls{TrackLangFromEnv}
\comment{load packages that use tracklang for localisation}
\end{codebox*}
Or (\sty{texosquery} v1.2)
\begin{codebox*}
\gls{input} \file{texosquery.tex} \comment{v1.2}
\gls{input} \file{tracklang.tex} \comment{v1.3}
\codepar
\gls{TeXOSQueryLangTag}\marg{\cmd{langtag}}
\gls{TrackLanguageTag}\marg{\cmd{langtag}}
\comment{load packages that use tracklang for localisation}
\end{codebox*}
A Unix-like user who may or may not have \app{texosquery} setup to run in the
\idx{shellescape}:
\begin{codebox*}
\gls{input} \file{texosquery.tex}
\gls{input} \file{tracklang.tex} \comment{v1.3}
\codepar
\cmd{ifx}\gls{TeXOSQueryLangTag}\cmd{undefined}
 \gls{TrackLangFromEnv}
\cmd{else}
 \gls{TeXOSQueryLangTag}\marg{\cmd{langtag}}
 \gls{TrackLanguageTag}\marg{\cmd{langtag}}
\cmd{fi}
\comment{load packages that use tracklang for localisation}
\end{codebox*}

A user is writing in Italy in Armenian with a Latin
\idx{script} (\opt{Latn}) and the arevela \idx{variant}:
\begin{codebox*}
\gls{input} \file{tracklang.tex} \comment{v1.3}
\gls{TrackLanguageTag}\marg{hy-Latn-IT-arevela}
\comment{load packages that use tracklang for localisation}
\end{codebox*}

A user is writing in English in the UK:
\begin{codebox*}
\gls{input} \file{tracklang.tex}
\gls{TrackPredefinedDialect}\marg{british}
\comment{load packages that use tracklang for localisation}
\end{codebox*}

Find out information about the current language (supplied
in \gls{languagename}):
\begin{codebox*}
\gls{SetCurrentTrackedDialect}\marg{\gls{languagename}}
Dialect: \gls{CurrentTrackedDialect}.
Language: \gls{CurrentTrackedLanguage}.
ISO Code: \gls{CurrentTrackedIsoCode}.
Region: \gls{CurrentTrackedRegion}.
Modifier: \gls{CurrentTrackedDialectModifier}.
Variant: \gls{CurrentTrackedDialectVariant}.
Script: \gls{CurrentTrackedDialectScript}.
Sub-Lang: \gls{CurrentTrackedDialectSubLang}.
Additional: \gls{CurrentTrackedDialectAdditional}.
Language Tag: \gls{CurrentTrackedLanguageTag}.
\end{codebox*}
Additional information about the \idx{script} can be obtained by
also loading \sty{tracklang-scripts}:
\begin{codebox*}
\gls{input} \file{tracklang-scripts.tex}
\end{codebox*}
The name, numeric code and direction can now be obtained:
\begin{codebox*}
Name: \gls{TrackLangScriptAlphaToName}\marg{\gls{CurrentTrackedDialectScript}}.
Numeric: 
\gls{TrackLangScriptAlphaToNumeric}\marg{\gls{CurrentTrackedDialectScript}}.
Direction: 
\gls{TrackLangScriptAlphaToDir}\marg{\gls{CurrentTrackedDialectScript}}.
\end{codebox*}
Test for a specific \idx{script} (in this case \opt{Latn}):
\begin{codebox*}
Latin?
\cmd{ifx}\gls{CurrentTrackedDialectScript}\tklscript{Latn}
 Yes
\cmd{else}
 No
\cmd{fi}
\end{codebox*}

\subsection{\texorpdfstring{\LaTeX}{LaTeX}}
\label{sec:latex}

This section is for \LaTeX\ use. See \sectionref{sec:tex} for generic \TeX\ use.

With newer versions of \sty{polyglossia}, where \gls{xpg@bcp@loaded}
is defined, you just need to make sure the languages are set before
\sty{tracklang} is loaded:
\begin{codebox*}
\cmd{documentclass}\marg{article}
\cmd{usepackage}\marg{polyglossia}
\cmd{setmainlanguage}[variant=uk]\marg{english}
\comment{load packages that use tracklang for localisation}
\end{codebox*}
For older versions of \sty{polyglossia} where the regional
information is required, use recognised class options:
\begin{codebox*}
\cmd{documentclass}[\opt{en-GB}]\marg{article}
\cmd{usepackage}\marg{polyglossia}
\cmd{setmainlanguage}[variant=uk]\marg{english}
\comment{load packages that use tracklang for localisation}
\end{codebox*}

For \sty{babel} users where the supplied \sty{babel} dialect
label is sufficient, and is passed either through the document class
or package options, there's no need to do anything special:
\begin{codebox*}
\cmd{documentclass}[\opt{british},\opt{canadien}]\marg{article}
\cmd{usepackage}[T1]\marg{fontenc}
\cmd{usepackage}\marg{babel}
\comment{load packages that use tracklang for localisation}
\end{codebox*}
With \sty{tracklang} v1.6.4+ there is now a check for
\gls{LocaleForEach}, which allows \sty{tracklang} to pick up locales
set with \gls{babelprovide}. For example:
\begin{codebox*}
\cmd{documentclass}\marg{article}
\cmd{usepackage}[T1]\marg{fontenc}
\cmd{usepackage}\oarg{british}\marg{babel}
\gls{babelprovide}\marg{canadianfrench}
\comment{load packages that use tracklang for localisation}
\end{codebox*}

If the region is important but there's no \sty{babel} dialect that
represents it, there are several options.
The first method is to use the class options recognised by \sty{tracklang}
and the root language labels when loading \sty{babel}:
\begin{codebox*}
\cmd{documentclass}[\opt{en-IE},\opt{ga-IE}]\marg{article}
\cmd{usepackage}[english,irish]\marg{babel}
\comment{load packages that use tracklang for localisation}
\end{codebox*}

Another method with \sty{babel} is to use \gls{TrackLanguageTag} and map the new
dialect label to the nearest matching \gls{captionsdialect}:
\begin{codebox*}
\cmd{documentclass}\marg{article}
\codepar
\cmd{usepackage}\marg{tracklang}\comment{v1.3}
\gls{TrackLanguageTag}\marg{\opt{en-MT}}
\gls{SetTrackedDialectLabelMap}
 \marg{\gls{TrackLangLastTrackedDialect}}\marg{\opt{UKenglish}}
\codepar
\cmd{usepackage}[UKenglish]\marg{babel}
\comment{load packages that use tracklang for localisation}
\end{codebox*}
This ensures that the \tklcaptions{UKenglish} hook is detected
by the localisation packages. This mapping isn't needed
for \sty{polyglossia} as the caption hooks use the root language
label. This mapping also isn't needed if \opt{british} is used
instead of \opt{UKenglish} since the \opt{en-MT}
(\opt{maltaenglish})
predefined dialect automatically sets up a mapping to
\opt{british}. (The default mappings are shown in
\tableref{tab:nonisoopts}.)

\section{Locale-Sensitive Packages}
\label{sec:summary-localepkg}

Let's suppose you are developing a package called 
\filefmt{mypackage.sty} or \filefmt{mypackage.tex} and you want
to find out what languages the document author has requested. (See also:
\dickimawhref{latex/tracklang/otherpkg.shtml}{Using
\filefmt{tracklang.tex} in Packages with Localisation Features}.)

Generic \TeX\ use (the \ext{tex} extension may be omitted):
\begin{codebox*}
\gls{input} \file{tracklang.tex}
\end{codebox*}
(Most of the commands used in this section require at least
\sty{tracklang} version 1.3 but 1.4 is better if you want to
include the \idx{script} tag in the \ext+{ldf} files.)
Note that \file{tracklang.tex} has a check to determine if
it's already been loaded, so you don't need to worry about that.

\LaTeX\ use:
\begin{codebox*}
\gls{RequirePackage}\marg{tracklang}[2019/11/30]\comment{at least v1.4}
\end{codebox*}
This will picked up any language options supplied in the document
class options and will also detect if \sty{babel} or
\sty{polyglossia} have been loaded.

(\LaTeX) If you want to allow the user to set the locale in the 
package options:
\begin{codebox*}
\gls{DeclareOption}*\marg{\gls{TrackLanguageTag}\marg{\cmd{CurrentOption}}}
\end{codebox*}
This means the user can do, say,
\begin{codebox}
\cmd{usepackage}[hy-Latn-IT-arevela]\marg{mypackage}
\end{codebox}
With at least version 1.4, it's better to use \gls{TrackIfKnownLanguage}:
\begin{codebox}
\gls{DeclareOption}*\marg{\comment{}
 \gls{TrackIfKnownLanguage}\marg{\cmd{CurrentOption}}\comment{}
 \marg{\comment{successful}
  \cmd{PackageInfo}\marg{mypackage}\marg{Tracking language `\cmd{CurrentOption}'}\comment{}
 }\comment{}
 \marg{\comment{failed}
  \cmd{PackageError}\marg{mypackage}\comment{}
  \marg{Unknown language specification `\cmd{CurrentOption}'}\comment{}
  \marg{You need to supply either a known dialect label 
   or a valid language tag}\comment{}
 }\comment{}
}
\end{codebox}

\begin{information}
The rest of the example package in this section uses generic code.
If you are using \LaTeX, it's better to replace \cmd{def} and
\cmd{ifx} with more appropriate \LaTeX\ commands.
\end{information}

If you want to fetch the locale information from the operating
system when the user hasn't requested a language:
\begin{codebox*}
\gls{AnyTrackedLanguages}
\marg{}
\marg{\comment{fetch locale information from the operating system}
  \cmd{ifx}\gls{TeXOSQueryLangTag}\cmd{undefined}
    \comment{texosquery v1.2 not available}
    \gls{TrackLangFromEnv}
  \cmd{else}
    \comment{texosquery v1.2 available}
    \gls{TeXOSQueryLangTag}\marg{\cmd{langtag}}
    \gls{TrackLanguageTag}\marg{\cmd{langtag}}
  \cmd{fi}
}
\end{codebox*}

Set up the defaults if necessary:
\begin{codebox}
\cmd{def}\cmd{fooname}\marg{Foo}
\cmd{def}\cmd{barname}\marg{Bar}
\end{codebox}

Now load the resource files:
\begin{codebox*}
\gls{AnyTrackedLanguages}
\marg{\comment{}
  \gls{ForEachTrackedDialect}\marg{\cmd{thisdialect}}\marg{\comment{}
    \gls{TrackLangRequireDialect}\marg{mypackage}\marg{\cmd{thisdialect}}\comment{}
  }\comment{}
}
\marg{}\comment{no tracked languages, default already set up}
\end{codebox*}

Each resource file has the naming scheme \file{prefix-localeid.ldf}\glsadd{ext.ldf}.
In this example, the \meta{prefix} is \filefmt{mypackage}. The
\meta{localeid} part may be the language or dialect label (for
example, \opt{english} or \opt{british}) or a combination of the
\idx{ISO} language and region codes (for example, \opt{en-GB} or
\iso{english} or \optfmt{GB}). As from version 1.4, \meta{localeid}
may also include the \idx{script} or \idx{variant}. (See the definition of
\gls{IfTrackedLanguageFileExists} \pref{pg:filesearch} 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 \idx+{ISO}
codes for regional support.

For example, the file \ldf{mypackage}{english}:
\begin{codebox*}
\comment{identify this file:}
\gls{TrackLangProvidesResource}\marg{english}[2016/10/06 v1.0]
\codepar
\gls{TrackLangAddToCaptions}\marg{\comment{}
  \cmd{def}\cmd{fooname}\marg{Foo}\comment{}
  \cmd{def}\cmd{barname}\marg{Bar}\comment{}
}
\end{codebox*}
This sets up appropriate the \gls{captionsdialect} hook (if it's
found). For other hooks, such as \gls{datedialect}, use 
\gls{TrackLangAddToHook} or \gls{TrackLangRedefHook} instead.

With pre-v1.4 versions of \sty{tracklang}, the \idx{script} isn't included
in the file search. If it's needed then either require at least v1.4
or have a base \ext{ldf} file that tries to load a version for the
particular \idx{script} (which can be accessed with
\gls{CurrentTrackedDialectScript}).
Here's an example for a language with different writing systems.
The resource file for Serbian \ldf{mypackage}{serbian}:
\begin{codebox*}
\comment{identify file:}
\gls{TrackLangProvidesResource}\marg{serbian}[2016/10/06 v1.0]
\codepar
\gls{TrackLangRequestResource}\marg{serbian-\gls{CurrentTrackedDialectScript}}
\marg{}\comment{file not found, do something sensible here}
\end{codebox*}
The file \ldf{mypackage}{serbian-Latn} sets up
the Latin \idx{script} (\opt{Latn}):
\begin{codebox*}
\gls{TrackLangProvidesResource}\marg{serbian-Latn}[2016/10/06 v1.0]
\codepar
\gls{TrackLangAddToCaptions}\marg{\comment{}
  \cmd{def}\cmd{fooname}\marg{...}\comment{provide appropriate Latin translations}
  \cmd{def}\cmd{barname}\marg{...}\comment{}
}
\end{codebox*}
The file \ldf{mypackage}{serbian-Cyrl} sets up
the Cyrillic \idx{script} (\opt{Cyrl}):
\begin{codebox*}
\gls{TrackLangProvidesResource}\marg{serbian-Cyrl}[2016/10/06 v1.0]
\codepar
\gls{TrackLangAddToCaptions}\marg{\comment{}
  \cmd{def}\cmd{fooname}\marg{...}\comment{provide appropriate Cyrillic translations}
  \cmd{def}\cmd{barname}\marg{...}\comment{}
}
\end{codebox*}
With v1.4+ you just need \ldf{mypackage}{sr-Latn} and
\ldf{mypackage}{sr-Cyrl} for the regionless versions.

\section{Language Packages}
\label{sec:summary-langpkg}

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 \sectionref{sec:summary-localepkg} to know what languages
the document author has requested. You can use the
\sty{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:
\dickimawhref{latex/tracklang/langpkg.shtml}{Integrating
\filefmt{tracklang.tex} into Language Packages}.)

Generic use:
\begin{codebox}
\gls{input} tracklang
\end{codebox}
Alternative \LaTeX\ use:
\begin{codebox}
\gls{RequirePackage}\marg{tracklang}[2019/11/30]\comment{v1.4}
\end{codebox}
Unlike \gls{input}, \gls{RequirePackage} will allow \sty{tracklang}
to pick up the document class options, but using \gls{RequirePackage}
will also trigger the tests for known language packages.
(If you want to find out if \sty{tracklang} has already been
loaded and locales have already been tracked, you can use the
same code as in the previous section.)

When a user requests a particular language through your package,
the simplest way of letting \sty{tracklang} know about it
is to use \gls{TrackPredefinedDialect} or \gls{TrackLanguageTag}.
For example, if the user requests \opt{british}, that's a
predefined dialect so you can just do:
\begin{codebox}
\gls{TrackPredefinedDialect}\marg{\opt{british}}
\end{codebox}
Alternatively
\begin{codebox}
\gls{TrackLanguageTag}\marg{\opt{en-GB}}
\end{codebox}
If your package uses caption hooks, then you can set up 
a mapping between \sty{tracklang}'s internal dialect label
and your caption label. For example, let's suppose the
closest match to English used in Malta (\opt{en-MT}) is the 
dialect \opt{UKenglish} (for example, the date format is 
similar between GB and MT):
\begin{codebox}
\gls{TrackLanguageTag}\marg{\opt{en-MT}}
\gls{SetTrackedDialectLabelMap}\marg{\gls{TrackLangLastTrackedDialect}}\marg{\opt{UKenglish}}
\cmd{def}\tklcaptions{UKenglish}\marg{\comment{}
  \cmd{def}\cmd{contentsname}\marg{Contents}\comment{}
  \comment{...}
}
\end{codebox}
(The predefined \opt{maltaenglish} option provided by
\sty{tracklang} automatically sets the mapping to
\opt{british}, but the above method will change that mapping
to \opt{UKenglish}.)

This now means that \gls{TrackLangAddToHook} and \gls{TrackLangRedefHook} commands can
find your language hooks. You don't need the map if your dialect
label is the same as \sty{tracklang}'s root language label
for that locale. For example:
\begin{codebox}
\gls{TrackLanguageTag}\marg{\opt{en-MT}}
\cmd{def}\tklcaptions{english}\marg{\comment{}
  \cmd{def}\cmd{contentsname}\marg{Contents}\comment{}
  \comment{...}
}
\end{codebox}

When the user switches language through commands like
\gls{selectlanguage} it would be useful to also use
\code{\gls{SetCurrentTrackedDialect}\margm{dialect}} to make it easier
for the document author or locale-sensitive packages to pick
up the current locale. The \meta{dialect} argument may be
\sty{tracklang}'s internal dialect label or the dialect
label you assigned with \gls{SetTrackedDialectLabelMap}. It
may also be the root language label, in which case
\sty{tracklang} will search for the last dialect to be
tracked with that language. For example:
\begin{codebox}
\cmd{def}\gls{selectlanguage}\#1\marg{\comment{}
  \gls{SetCurrentTrackedDialect}\marg{\#1}\comment{}
  \comment{set up hyphenation patterns etc}
}
\end{codebox}
See the example in \sectionref{sec:summary-doc} or the example in 
\dickimawhref{latex/tracklang/langpkg.shtml}{Integrating
\filefmt{tracklang.tex} into Language Packages}.

\chapter{Generic Use}
\label{sec:generic}

For plain \TeX\ you can input \file{tracklang.tex}:
\begin{codebox}
\gls{input} tracklang
\end{codebox}
or for \TeX\ formats that have an argument form for \gls{input}:
\begin{codebox}
\gls{input}\marg{tracklang}
\end{codebox}
As from version 1.3, you don't need to change the category
code of \idx{atletter} before loading \file{tracklang.tex}
as it will automatically be changed to 11 and switched
back at the end (if required).

The \LaTeX\ package \file{tracklang.sty} 
inputs the generic \TeX\ code in \file{tracklang.tex}, but before 
it does so it defines
\cmddef{@tracklang@declareoption}
to
\begin{compactcodebox*}
\gls{DeclareOption}\margm{dialect}\marg{\gls{TrackPredefinedDialect}\margm{dialect}}
\end{compactcodebox*}
If \gls{@tracklang@declareoption} isn't defined when
\file{tracklang.tex} is input, it will be defined to ignore its
argument.

This means that all the predefined languages and dialects
(\refoptstables) automatically become package options, so
the \file{tracklang.sty} package can pick up document class
options and add them to \sty{tracklang}'s internal list of tracked
document languages.

As from version 1.6.3, the \LaTeX\ package also has options
\inlineoptdef{verbose} and \inlineoptdef{noverbose} to switch on and
off verbose mode.  As from version 1.6.5, there are also
\inlineoptdef{warn} and \inlineoptdef{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
\sty{tracklang} before it's first loaded.

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

\cmddef{TrackPredefinedDialect}
This will add the predefined dialect and its associated \idx{ISO} codes to the list
of tracked document languages. The \meta{dialect label} may be any
of those listed in \refoptstables.

For example:
\begin{codebox}
\gls{input} tracklang
\gls{TrackPredefinedDialect}\marg{\opt{british}}
\end{codebox}
is the Plain \TeX\ alternative to:
\begin{codebox}
\cmd{documentclass}[\opt{british}]\marg{article}
\cmd{usepackage}\marg{tracklang}
\end{codebox}

Note that it's impractical to define every possible language
and region combination as it would significantly slow the
time taken to load \sty{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
\sty{tracklang}, then you can use:
\cmddef{TrackLocale}
If \meta{locale} is a recognised dialect, this is equivalent to
using \gls{TrackPredefinedDialect}, otherwise \meta{locale}
needs to be in one the following formats:
\begin{itemize}
\item \meta{\idx{ISO} lang}
\item \meta{\idx{ISO} lang}\idx{atmod}\meta{modifier}
\item \meta{\idx{ISO} lang}\idx{hyphensep}\meta{\idx{ISO} country}
\item \meta{\idx{ISO} lang}\idx{hyphensep}\meta{\idx{ISO} country}\idx{atmod}\meta{modifier}
\end{itemize}
where \meta{\idx{ISO} lang} is the \idxn{639-1} or \idx{639-2} code identifying
the language (lower case), \meta{\idx{ISO} country} is the \idx{3166-1}
\idx{ISO} code identifying the \idx{territory} (upper case) and 
\meta{modifier} is the \idx{modifier} or \idx{variant}. The hyphen
(\idx{hyphensep}) may be replaced by an underscore character 
(\idx{underscoresep}). \Idx{code-set} information in the
form \code{\idx{dotsep}\meta{codeset}} may optionally appear before the
\idx{modifier}. For example, 
\code{de\idx{hyphensep}DE\idx{dotsep}utf8\idx{atmod}new} (\idx{modifier} is
\optfmt{new}) or \code{en\idx{hyphensep}GB\idx{dotsep}utf8} (\idx{modifier} is missing).
The \idx{code-set} will be ignored if present, but it won't interfere
with the parsing.

For example:
\begin{codebox}
\gls{TrackLocale}\marg{de\idx{hyphensep}NA\idx{atmod}new}
\end{codebox}
indicates German in Namibia using the new spelling.

\begin{important}
If a language has different \idxn{639-2T} and \idx{639-2B} codes, then
the \qt{T} form should be used. (So for the above example,
\code{deu} may be used instead of \code{de}, but \code{ger}
won't be recognised.)
\end{important}

Alternatively, you can use
\cmddef{TrackLanguageTag}
where \meta{tag} is a regular, well-formed language tag or a recognised dialect
label. (Irregular grandfather tags aren't recognised.)
Note that the tag must start with a language
identifier and can't simply be a region code (use \qt{und} if the
language is unknown).
This command will fully expand \meta{tag}.
A warning is issued if the tag is empty.

If you want to first check that \meta{tag} includes a valid language
code, then you can instead use:
\cmddef{TrackIfKnownLanguage}
This will only track \meta{tag} (and then do \meta{success code}) if
\meta{tag} starts with a valid language code (or is a predefined
dialect) otherwise it will do \meta{fail code}. Both
\gls{TrackLanguageTag} and \gls{TrackIfKnownLanguage} will check if
\meta{tag} is a predefined option. (This saves parsing the tag if
it's recognised.)

For example:
\begin{codebox}
\gls{TrackLanguageTag}\marg{hy-Latn-IT-arevela}
Latn-ME: \gls{TrackIfKnownLanguage}\marg{Latn-ME}\marg{success}\marg{fail}.
brazilian: \gls{TrackIfKnownLanguage}\marg{brazilian}\marg{success}\marg{fail}.
\end{codebox}
This will track \optfmt{hy-Latn-IT-arevela} and \opt{brazilian}
(\optfmt{pt-BR}) but not \optfmt{Latn-ME} (because it doesn't contain a
valid language code) even though it's a valid \idx{script} and country
code. The above is just for illustrative purposes. Typically the
language tracking isn't performed within the document text.

The \sty{datetime2} package assumes that any unknown package option is a
language identifier. It could simply do:
\begin{compactcodebox}
\gls{TrackLanguageTag}\marg{\cmd{CurrentOption}}
\end{compactcodebox}
but users can make mistakes sometimes and this won't provide any
helpful information if they, for example, misspelt a package option
or forgot the \qt{\meta{key}=} part of a \keyval\
setting. Instead (as from v1.5.5) \sty{datetime2} now does:
\begin{compactcodebox}
\gls{TrackIfKnownLanguage}\marg{\cmd{CurrentOption}}
\marg{...}\comment{known language}
\marg{\cmd{PackageError}\marg{...}\marg{...}\marg{...}}
\end{compactcodebox}
This will now give the user some guidance. 

If \meta{tag} contains a sub-language tag, this will be set
as the \idx{639-3} code for the \emph{dialect} label. Note that this is
different to the root language codes which are set using the
language label. For example:
\begin{codebox}
\gls{TrackLanguageTag}\marg{zh-cmn-Hans-CN}
\end{codebox}
creates a new dialect with the label \code{zh\-cmn\-Hans\-CN}.
The root language \opt{chinese} has the \idx{639-1} code
\optfmt{zh} and the dialect \code{zh\-cmn\-Hans\-CN} has the
\idxn{639-3} code \optfmt{cmn}.
\begin{codebox}
ISO 639-1: \gls{TrackedIsoCodeFromLanguage}\marg{639-1}\marg{chinese}.
ISO 639-3: \gls{TrackedIsoCodeFromLanguage}\marg{639-3}\marg{zhcmnHansCN}.
\end{codebox}

Version 1.2 of \sty{texosquery} provides the command \gls{TeXOSQueryLangTag},
which may be used to fetch the operating system's regional
information as a language tag. These commands can be used as
follows:
\begin{codebox}
\gls{input} tracklang \comment{v1.3}
\gls{input} texosquery \comment{v1.2}
\codepar
\gls{TeXOSQueryLangTag}\marg{\cmd{langtag}}
\gls{TrackLanguageTag}\marg{\cmd{langtag}}
\end{codebox}
(If the \idx{shellescape} is disabled, \cmd{langtag} will be empty, which
will trigger a~warning but no errors.)

Some of the predefined root language options listed
in \tableref{tab:rootlangopts} have an associated region
(denoted by \fnregion).
If \gls{TrackLocale} is used with just the language \idx{ISO} code,
no region is tracked for that language. For example
\begin{codebox}
\gls{TrackLocale}\marg{\opt{manx}}
\end{codebox}
will track the \optfmt{IM} (Isle of Man) \idxn{3166-1} code but
\begin{codebox}
\gls{TrackLocale}\marg{gv}
\end{codebox}
won't track the region.
Similarly for \gls{TrackLanguageTag}.

(New to version 1.3.)
There's a similar command to \gls{TrackLocale} that doesn't take an argument:
\cmddef{TrackLangFromEnv}
If the \idx{shellescape} has been enabled or \gls{directlua} is
available, this will try to get the language information from the
system environment variables \envvar{LCALL} or \envvar{LANG} and, if
successful, track that.

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

\begin{important}
Not all operating systems use environment variables for
the system locale information. For example, Windows stores the
locale information in the registry. In which case, consider
using \sty{texosquery}.
\end{important}

If the operating system locale can't be obtained from environment variables, then
\sty{tracklang} will use \gls{TeXOSQueryLocale} as a fallback if
\sty{texosquery} has been loaded. Since \sty{texosquery} requires
both the \idx{shellescape} and the Java runtime environment,
\sty{tracklang} doesn't automatically load it.

Plain \TeX\ example:
\begin{codebox}
\gls{input} texosquery
\gls{input} tracklang
\gls{TrackLangFromEnv}
\end{codebox}
Document build:
\begin{terminal}
\app{etex} \switch{shell-escape} \meta{filename}
\end{terminal}

\LaTeX\ example:
\begin{codebox}
\cmd{usepackage}\marg{texosquery}
\cmd{usepackage}\marg{tracklang}
\gls{TrackLangFromEnv}
\end{codebox}
Document build:
\begin{terminal}
\app{pdflatex} \switch{shell-escape} \meta{filename}
\end{terminal}

If the locale can't be determined, there will be warning messages.
These can be suppressed using
\cmddef{TrackLangShowWarningsfalse}
or switched back on again using
\cmddef{TrackLangShowWarningstrue}

For example, I have the environment variable \envvar{LANG} set to 
\code{en\idx{underscoresep}GB\idx{dotsep}utf8} on my Linux system so instead of
\begin{codebox}
\gls{TrackPredefinedDialect}\marg{\opt{british}}
\end{codebox}
I can use
\begin{codebox}
\gls{TrackLangFromEnv}
\end{codebox}

With \LaTeX\ documents I can do
\begin{codebox}
\cmd{documentclass}\marg{article}
\cmd{usepackage}\marg{tracklang}
\gls{TrackLangFromEnv}
\end{codebox}
However, this only helps subsequently loaded packages that
use \sty{tracklang} to determine the required regional 
settings. For example:
\begin{codebox}
\cmd{documentclass}\marg{article}
\cmd{usepackage}\marg{tracklang}
\gls{TrackLangFromEnv}
\cmd{usepackage}[useregional]\marg{datetime2}
\end{codebox}
In my case, with the \envvar{LANG} environment variable set to
\code{en\idx{underscoresep}GB\idx{dotsep}utf8} and the
\idx{shellescape} enabled, this automatically switches on the 
\opt{en-GB} date style.
Naturally this doesn't help locale-sensitive packages that don't use
\sty{tracklang}.

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

If the command:
\cmddef{TrackLangEnv}
is already defined before \gls{TrackLangFromEnv} is used, then the
environment variable won't be queried and the value of
\gls{TrackLangEnv} will be parsed instead.

\begin{important}
The parser which splits the locale string into 
its component parts first tries splitting on the underscore
\idx{underscoresep} with its usual category code~8, then tries splitting 
on a hyphen \idx{hyphensep} with category code~12, and then tries 
splitting on the underscore \idx{underscoresep} with category code~12.
\end{important}

For example:
\begin{codebox}
\cmd{def}\gls{TrackLangEnv}\marg{en-GB}
\gls{TrackLangFromEnv}
\end{codebox}
This doesn't perform a \idx{shellescape} since \gls{TrackLangEnv}
is already defined. In this case, you may just as well use:
\begin{codebox}
\gls{TrackLocale}\marg{en-GB}
\end{codebox}
(unless you happen to additionally require the component
commands that are set by \gls{TrackLangFromEnv}, see below.)

If the \idx{shellescape} 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 \filefmt{myDoc.tex} (and it's
in Plain \TeX):
\begin{terminal}
\app{tex} "\idx{escbsl}def\idx{escbsl}\glscsname{TrackLangEnv}\marg{\idx{dollarenv}\envvar{LANG}}\idx{escbsl}\glscsname{input} myDoc"
\end{terminal}

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

The language code is stored in:
\cmddef{TrackLangEnvLang}

The \idx{territory} (if present) is stored in:
\cmddef{TrackLangEnvTerritory}

The \idx{code-set} (if present) is stored in:
\cmddef{TrackLangEnvCodeSet}

The \idx{modifier} (if present) is stored in:
\cmddef{TrackLangEnvModifier}

If you want to query the language environment, but don't
want to track the result, you can just use:
\cmddef{TrackLangQueryEnv}
This only tries to fetch the value of the
language environment variable (and use \sty{texosquery} as
a fallback, if it has been loaded). It doesn't try to parse the 
result. The result is stored in \gls{TrackLangEnv} (empty if 
unsuccessful). Unlike \gls{TrackLangFromEnv}, this doesn't check if
\gls{TrackLangEnv} already exists. A warning will occur if the shell
escape is unavailable. For systems that store the locale information in
environment variables, this is more efficient than using
\sty{texosquery}'s \gls{TeXOSQueryLocale} command (which is what's
used as the fallback).

The above queries \envvar{LCALL} and, if that is unsuccessful,
then queries \envvar{LANG} (before optionally falling back on 
\sty{texosquery}). If you want another environment
variable tried after \envvar{LCALL} and before \envvar{LANG},
you can instead use:
\cmddef{TrackLangQueryOtherEnv}
For example, to also query \envvar{LCMONETARY}:
\begin{codebox}
\gls{TrackLangQueryOtherEnv}\marg{\envvar{LCMONETARY}}
\end{codebox}

Since this sets \gls{TrackLangEnv}, you can use it before
\gls{TrackLangFromEnv}. For example:
\begin{codebox}
\gls{TrackLangQueryOtherEnv}\marg{\envvar{LCMONETARY}}
\gls{TrackLangFromEnv}
\end{codebox}
Remember that if you only want to do the \idx{shellescape} if
\gls{TrackLangEnv} hasn't already been defined, you can test for this
first:
\begin{codebox}
\cmd{ifx}\gls{TrackLangEnv}\cmd{undefined}
  \gls{TrackLangQueryOtherEnv}\marg{\envvar{LCMONETARY}}
\cmd{fi}
\gls{TrackLangFromEnv}
\end{codebox}

It's also possible to just parse the value of \gls{TrackLangEnv}
without tracking the result using:
\cmddef{TrackLangParseFromEnv}
This is like \gls{TrackLangFromEnv} but assumes that 
\gls{TrackLangEnv} has already been set and doesn't track the 
result. The component parts are stored as for \gls{TrackLangFromEnv}.

Example (Plain \TeX):
\begin{codebox}
\gls{input} tracklang
\codepar
\cmd{def}\gls{TrackLangEnv}\marg{fr\idx{hyphensep}BE\idx{dotsep}utf8\idx{atmod}euro}
\codepar
\gls{TrackLangParseFromEnv}
\codepar
Language: \gls{TrackLangEnvLang}.
Territory: \gls{TrackLangEnvTerritory}.
Codeset: \gls{TrackLangEnvCodeSet}.
Modifier: \gls{TrackLangEnvModifier}.
Any tracked languages? \gls{AnyTrackedLanguages}\marg{Yes}\marg{No}.
\end{codebox}
This produces:
\begin{resultbox}
Language: fr. Territory: BE.  Codeset: utf8.  Modifier: euro.
Any tracked languages? No.
\end{resultbox}

Compare this with:
\begin{codebox}
\gls{input} tracklang
\codepar
\cmd{def}\gls{TrackLangEnv}\marg{fr\idx{hyphensep}BE\idx{dotsep}utf8\idx{atmod}euro}
\codepar
\gls{TrackLangFromEnv}
\codepar
Language: \gls{TrackLangEnvLang}.
Territory: \gls{TrackLangEnvTerritory}.
Codeset: \gls{TrackLangEnvCodeSet}.
Modifier: \gls{TrackLangEnvModifier}.
Any tracked languages? \gls{AnyTrackedLanguages}\marg{Yes}\marg{No}.
Tracked dialect(s):\comment{}
\gls{ForEachTrackedDialect}\marg{\cmd{thisdialect}}\marg{\cmd{space}\cmd{thisdialect}}.
\end{codebox}
This produces:

\begin{resultbox}
Language: fr. Territory: BE.  Codeset: utf8.  Modifier: euro.
Any tracked languages? Yes.
Tracked dialect(s): belgique.
\end{resultbox}

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

For example, \sty{tracklang} doesn't recognise \code{en-BE}, so
the sample document below defines a new dialect labelled
\code{enBEeuro}:
\begin{codebox}
\gls{input} tracklang
\codepar
\cmd{def}\gls{TrackLangEnv}\marg{en\idx{hyphensep}BE\idx{dotsep}utf8\idx{atmod}euro}
\codepar
\gls{TrackLangFromEnv}
\codepar
Language: \gls{TrackLangEnvLang}.
Territory: \gls{TrackLangEnvTerritory}.
Codeset: \gls{TrackLangEnvCodeSet}.
Modifier: \gls{TrackLangEnvModifier}.
Any tracked languages? \gls{AnyTrackedLanguages}\marg{Yes}\marg{No}.
Tracked dialect(s):\comment{}
\gls{ForEachTrackedDialect}\marg{\cmd{thisdialect}}\marg{\cmd{space}\cmd{thisdialect}}.
\end{codebox}
This now produces:
\begin{resultbox}
Language: en. Territory: BE.  Codeset: utf8.  Modifier: euro.
Any tracked languages? Yes.
Tracked dialect(s): enBEeuro.
\end{resultbox}

\chapter{Supplementary Packages}
\label{sec:supplpkgs}

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

\filedef{tracklang-region-codes.tex}
This file is only loaded if a mapping is required between numeric
and alphabetic \idx{region} codes. If \gls{TrackLanguageTag}
encounters a numeric \idx{region} code, it will automatically input
\file{tracklang-region-codes.tex}, if it hasn't already been input.
This file provides the following commands.

\cmddef{TrackLangAlphaIIToNumericRegion}
Expands to the numeric code corresponding to the given alpha-2 code or
empty if no mapping has been supplied.

\cmddef{TrackLangNumericToAlphaIIRegion}
Expands to the alpha-2 code corresponding to the given numeric code or
empty if no mapping has been supplied.

\cmddef{TrackLangIfKnownAlphaIIRegion}
Expands to \meta{true} if there's an alpha-2 to numeric \idx{region}
code mapping, otherwise expands to \meta{false}.

\cmddef{TrackLangIfKnownNumericRegion}
Expands to \meta{true} if there's a numeric to alpha-2 \idx{region}
code mapping, otherwise expands to \meta{false}.

\cmddef{TrackLangAlphaIIIToNumericRegion}
Expands to the numeric code corresponding to the given alpha-3 code or
empty if no mapping has been supplied.

\cmddef{TrackLangNumericToAlphaIIIRegion}
Expands to the alpha-3 code corresponding to the given numeric code or
empty if no mapping has been supplied.

\cmddef{TrackLangIfKnownAlphaIIIRegion}
Expands to \meta{true} if there's an alpha-3 to numeric \idx{region}
code mapping, otherwise expands to \meta{false}.

Mappings are established with:
\cmddef{TrackLangRegionMap}
Predefined mappings are listed in \tableref{tab:regionmappings}.

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

\cmddef{TrackLangAddExtraRegionFile}
This command adds the supplied \meta{file} to the list of extra
region code files that should be input by
\file{tracklang-region-codes.tex}, unless
\file{tracklang-region-codes.tex} has already been input, in which
case \meta{file} will be input straight away.

\filedef{tracklang-scripts.tex}
The \sty{tracklang-scripts} package provides information about
\idxn{15924} scripts. The file isn't automatically loaded. If
you want to use any of the commands provided in it you need to input
it.

Plain \TeX:
\begin{codebox}
\gls{input} tracklang-scripts
\end{codebox}
There's a simple wrapper package \file{tracklang-scripts.sty} for
\LaTeX\ users:
\begin{codebox}
\cmd{usepackage}\marg{tracklang-scripts}
\end{codebox}

\cmddef{TrackLangScriptMap}
Defines a mapping. The first argument is the four letter alpha code,
such as \opt{Latn} or \opt{Cyrl}. The second argument is the numeric
code. The third argument is the script's name, for example
\qt{Imperial Aramaic}. The fourth argument is the direction, which
may be one of: \optfmt{LR} (left-to-right), \optfmt{RL} (right-to-left),
\optfmt{TB} (top-to-bottom), \optfmt{varies} or \optfmt{inherited}.
The \meta{parent} argument is for the parent writing system, which
may be left blank (currently unsupported).

This command defines:
\cmddef{TrackLangScriptCode}
which expands to \meta{Code} for use with \gls{IfTrackedDialectIsScriptCs}.

See \tableref{tab:scriptmappings} for a summary of all the mappings 
that are provided by the file \file{tracklang-scripts.tex}.

\cmddef{TrackLangScriptAlphaToNumeric}
Expands to the numeric code corresponding to the given alpha code or
empty if no mapping.

\cmddef{TrackLangScriptIfKnownAlpha}
Expands to \meta{true} if there is a known alpha to numeric mapping
or \meta{false} otherwise.

\cmddef{TrackLangScriptNumericToAlpha}
Expands to the alpha code corresponding to the given numeric code or
empty if no mapping.

\cmddef{TrackLangScriptIfKnownNumeric}
Expands to \meta{true} if there is a known numeric to alpha mapping
or \meta{false} otherwise.

\cmddef{TrackLangScriptAlphaToName}
Expands to the name corresponding to the given alpha code or
empty if no mapping.

\cmddef{TrackLangScriptAlphaToDir}
Expands to the direction corresponding to the given alpha code or
empty if no mapping.

\cmddef{TrackLangScriptSetParent}
Sets the parent for the given alpha code.

\cmddef{TrackLangScriptGetParent}
Expands to the parent for the given alpha code or empty if no
mapping.

\cmddef{TrackLangScriptIfHasParent}
Expands to \meta{true} if the given alpha code has a parent 
or to \meta{false} otherwise. Note that if a parent is explicitly
set to empty with \gls{TrackLangScriptSetParent} then it will be
considered defined, but if the \meta{parent} argument was empty in 
\gls{TrackLangScriptMap}, then it will be undefined.

\cmddef{TrackLangAddExtraScriptFile}
This command adds \meta{file} to the list of extra script files that should
be input by \file{tracklang-scripts.tex}, unless 
\file{tracklang-scripts.tex} has already been input, in which
case \meta{file} will be input straight away.


\chapter{Detecting the User's Requested Languages}
\label{sec:user}

The \sty{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 \opt{british}, the \emph{root language} label is
\opt{english} and the dialect is \opt{british}, whereas if the
user requested \opt{UKenglish}, the root language label is
\opt{english} and the dialect is \opt{UKenglish}. The
exceptions to this are the \sty{tracklang} package options that have been
specified in the form \meta{iso lang}-\meta{iso country} (listed
in \tableref{tab:rootlangopts}). For
example, the package option \iso{british} behaves as though the
user requested the package option \opt{british}.

If \gls{TrackLocale} or \gls{TrackLangFromEnv} are used and the locale
isn't recognised a new dialect is created with the label formed from
the \idx{ISO} codes (and \idx{modifier}, if present). 
Similarly for \gls{TrackLanguageTag} a new
dialect is created with a label that's essentially the language tag
without the hyphen separators.  For example, 
\begin{codebox}
\gls{TrackLocale}\marg{xx\idx{hyphensep}YY}
\end{codebox}
will add a new dialect with the label \code{xxYY},
\begin{codebox}
\gls{TrackLocale}\marg{xx\idx{hyphensep}YY\idx{atmod}mod}
\end{codebox}
will add a new dialect with the label \code{xxYYmod} and 
\begin{codebox}
\gls{TrackLanguageTag}\marg{xx-Latn-YY}
\end{codebox}
will add a new dialect with the label \code{xxLatnYY}.

\begin{important}
If \gls{TrackLocale} or \gls{TrackLangFromEnv} find a \idx{modifier}, the 
value will be sanitized to allow it to be used as a label. If the
modifier is set explicitly using \gls{SetTrackedDialectModifier}, 
no sanitization is performed.
\end{important}

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

When the \file{tracklang.sty} \LaTeX\ package is loaded, it first attempts to find the
language options through the package options supplied to
\sty{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, \file{tracklang.sty} then attempts to identify language settings in
the following order:
\begin{enumerate}
\item if \gls{LocaleForEach} is defined (\sty{babel}),
\sty{tracklang} will use it to iterate over each dialect label
and fetch the associated \idx{BCP47} tag;

\item if \gls{bbl@loaded} is defined (\sty{babel}), \sty{tracklang}
will iterate over each label in that command definition;

\item if \gls{trans@languages} is defined (\sty{translator}), 
\sty{tracklang} will iterate over each label in that command
definition;

\item if \sty{ngerman} has been loaded, the \opt{ngerman} dialect
will be tracked;

\item if \sty{german} has been loaded, the \opt{german} root
language will be tracked;

\item if \sty{polyglossia} has been loaded:

 \begin{enumerate}
 \item if \gls{xpg@bcp@loaded} has been defined, \sty{tracklang}
will iterate over the \idx{BCP47} tags in that command definition;

 \item if \gls{xpg@loaded} has been defined, \sty{tracklang} will
iterate over each language label in that command definition;

 \item \sty{tracklang} will iterate over all \sty{tracklang} options
and test if the root language has been loaded.
 \end{enumerate}

\end{enumerate}
The check for \sty{ngerman}\slash\sty{german} is retained
for backward-compatibility.

Each identified language and dialect is added to the \emph{tracked
language} and \emph{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:
\cmddef{AnyTrackedLanguages}
This will do \meta{true} if one or more languages have been
tracked otherwise it will do \meta{false}. (Each detected
dialect will automatically have the root language label added
to the tracked language list, if it's not already present.)

You can check whether or not any regions have been detected using:
\cmddef{AnyTrackedRegions}
This will do \meta{true} if one or more regions have been
tracked otherwise it will do \meta{false}.

If you want to find out if any of the tracked dialects
matches a particular language tag, you can use:
\cmddef{GetTrackedDialectFromLanguageTag}
If successful, the supplied control sequence \meta{cs} is set to the
dialect label, otherwise \meta{cs} is set to empty. The test is for an exact
match on the root language, \idx{script}, sub-language, \idx{variant} and
\idx{region}. The control sequence \meta{cs} will be empty if none of the
tracked dialects matches all five of those elements. (If the script
isn't given explicitly, the default for that language is assumed.)
In the event that \meta{cs} is empty, you can now (as from v1.3.6)
get the closest match with:
\cmddef{TrackedDialectClosestSubMatch}
(which is set by \gls{GetTrackedDialectFromLanguageTag}).
This will be empty if no tracked dialects match on the root
language or if there's a tracked dialect label that exactly matches
the label formed by concatenating the language code, sub-language,
\idx{script}, \idx{region}, \idx{modifier} and \idx{variant}.

For example (Plain \TeX):
\begin{codebox}
\gls{input} tracklang
\gls{TrackLanguageTag}\marg{en-826}
Has en-Latn-GB been tracked?
\gls{GetTrackedDialectFromLanguageTag}\marg{en-Latn-GB}\marg{\cmd{thisdialect}}\comment{}
\cmd{ifx}\cmd{thisdialect}\cmd{empty}
 No!
\cmd{else}
 Yes! Dialect label: \cmd{thisdialect}.
\cmd{fi}
\cmd{bye}
\end{codebox}
This matches because the \idx{territory} code \numericcode{GB} is recognised as
equivalent to the code \opt{GB}, and the default \idx{script} for
\opt{english} is \opt{Latn}. In this case, the dialect
label is \opt{british}. Note that this doesn't require
the use of \gls{TrackLanguageTag} to track the dialect. 
It also works if the dialect has been tracked using other commands,
such as \gls{TrackLocale}.

Here's an example that doesn't have an exact match, but does have a
partial match:
\begin{codebox}
\gls{input} tracklang
\gls{TrackLanguageTag}\marg{de-CH-1996}
Has de-DE-1996 been tracked?
\gls{GetTrackedDialectFromLanguageTag}\marg{de-DE-1996}\marg{\cmd{thisdialect}}\comment{}
\cmd{ifx}\cmd{thisdialect}\cmd{empty}
 No!
  \cmd{ifx}\gls{TrackedDialectClosestSubMatch}\cmd{empty}
    No match on root language.
  \cmd{else}
    Closest match: \gls{TrackedDialectClosestSubMatch}.
  \cmd{fi}
\cmd{else}
 Yes! Dialect label: \cmd{thisdialect}.
\cmd{fi}
\cmd{bye}
\end{codebox}
In this case the result is:
\begin{resultbox}
Has de-DE-1996 been tracked? No! Closest match: nswissgerman.
\end{resultbox}

You can iterate through each tracked dialect using:
\cmddef{ForEachTrackedDialect}
At the start of each iteration, this sets the control sequence 
\meta{cs} to the tracked dialect and does \meta{body}.

You can iterate through each tracked language using:
\cmddef{ForEachTrackedLanguage}
At the start of each iteration, this sets the control sequence \meta{cs} to the 
tracked language and does \meta{body}.

You can iterate through each tracked region using:
\cmddef{ForEachTrackedRegion}

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

The provided control sequence \meta{cs} is updated at the
start of each iteration to the current element. The loop is
terminated when this control sequence is set to \gls{@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 \gls{@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 \gls{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:
\cmddef{IfTrackedLanguage}
where \meta{language-label} is the language label. If
true, this does \meta{true} otherwise it does \meta{false}.

You can test if a particular dialect has been detected using:
\cmddef{IfTrackedDialect}
where \meta{dialect-label} is the dialect label. If the root
language was explicitly specified, then it will also be detected as
a dialect.

For example:
\begin{codebox}
\cmd{documentclass}[\opt{british},\opt{dutch}]\marg{article}
\codepar
\cmd{usepackage}\marg{tracklang}
\codepar
\cbeg{document}
``english'' \gls{IfTrackedDialect}\marg{english}\marg{has}\marg{hasn't} been specified.
\codepar
``british'' \gls{IfTrackedDialect}\marg{british}\marg{has}\marg{hasn't} been specified.
\codepar
``flemish'' \gls{IfTrackedDialect}\marg{flemish}\marg{has}\marg{hasn't} been specified.
\codepar
``dutch'' \gls{IfTrackedDialect}\marg{dutch}\marg{has}\marg{hasn't} been specified.
\codepar
``english'' or an English variant 
\gls{IfTrackedLanguage}\marg{english}\marg{has}\marg{hasn't} been specified.
\cend{document}
\end{codebox}
This produces:
\begin{resultbox}
``english'' hasn't been specified.

``british'' has been specified.

``flemish'' hasn't been specified.

``dutch'' has been specified.

``english'' or an English variant has been specified.
\end{resultbox}

You can find the root language label for a given tracked dialect
using:
\cmddef{TrackedLanguageFromDialect}
If \meta{dialect} hasn't been defined this does nothing otherwise it
expands to the root language label.

You can find the tracked dialects from a given root language
using:
\cmddef{TrackedDialectsFromLanguage}
This will expand to a~comma-separated list of dialect labels
if the root language label has been defined, otherwise it
does nothing.

You can test if a language or dialect has a corresponding \idx+{ISO} code using:
\cmddef{IfTrackedLanguageHasIsoCode}
where \meta{code type} is the type of \idx{ISO} code (for example,
\idx{639-1} for root languages or \idx{3166-1} for regional
dialects), and \meta{label} is the language or dialect label.
Note that the \idx{639-3} may be set for the dialect
rather than root language for sub-languages parsed using
\gls{TrackLanguageTag}.

Alternatively, you can test if a particular \idx{ISO} code has been
defined using:
\cmddef{IfTrackedIsoCode}
where \meta{code type} is again the type of \idx{ISO} code (for example,
\idx{639-1} or \idx{3166-1}), and \meta{code} is the
particular code (for example, \opt{en} for \idxn{639-1} or
\opt{GB} for \idxn{3166-1}).

You can fetch the language (or dialect) label associated with a
given \idx{ISO} code using:
\cmddef{TrackedLanguageFromIsoCode}
This does nothing if the given \meta{code} for the given \idx{ISO}
\meta{code type} has not been defined, otherwise it expands
a~comma-separated list of language or dialect labels.

You can fetch the \idx{ISO} code for a given code type using:
\cmddef{TrackedIsoCodeFromLanguage}
where \meta{label} is the language or dialect label and \meta{code
type} is the \idx{ISO} code type (for example, \idx{639-1} or
\idx{3166-1}). Unlike \gls{TrackedLanguageFromIsoCode}, this
command only expands to a single label rather than a~comma-separated
list.

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:
\cmddef{TwoLetterIsoCountryCode}
This expands to \idx{3166-1} and is used for the two-letter country codes.

\cmddef{TwoLetterIsoLanguageCode}
This expands to \idx{639-1} and is used for the two-letter root language codes.

\cmddef{ThreeLetterIsoLanguageCode}
This expands to \idx{639-2} and is used for the three-letter root language
codes.

\cmddef{ThreeLetterExtIsoLanguageCode}
This expands to \idx{639-3}. This code is only used for a root language if 
there's no \idx{639-1} or \idx{639-2} code. It may also be used for a
dialect if a sub-language part has been set in the language
tag parsed by \gls{TrackLanguageTag}.

The \cmd{Get\ldots} commands below are designed to be expandable.
If the supplied \meta{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:
\cmddef{GetTrackedLanguageTag}
where \meta{dialect} is the label identifying the dialect.
Uses the \opt{und} (undetermined) code for unknown languages.

As from v1.3, each tracked dialect may also have an associated 
modifier, which can be fetched using:
\cmddef{GetTrackedDialectModifier}
where \meta{dialect} is the label identifying the dialect.
This value is typically obtained by parsing a \idx{POSIX} locale identifier
with \gls{TrackLocale} or \gls{TrackLangFromEnv} but may be set explicitly.
(See \sectionref{sec:langsty} for setting this value. Likewise for
the following commands.)

You can test if a dialect has an associated \idx{modifier} using:
\cmddef{IfHasTrackedDialectModifier}
If the dialect has an associated \idx{modifier} this does \meta{true}
otherwise it does \meta{false}.

For example:
\begin{codebox}
\cmd{documentclass}[\opt{british}\dcomma\opt{francais}\dcomma\opt{american}\dcomma\opt{canadian}\dcomma\opt{canadien}\dcomma\opt{dutch}]\marg{article}
\codepar
\cmd{usepackage}\marg{tracklang}
\codepar
\cbeg{document}
Languages:
\gls{ForEachTrackedLanguage}\marg{\cmd{ThisLanguage}}\marg{\cmd{ThisLanguage}\cmd{space}
(ISO \gls{TwoLetterIsoLanguageCode}: 
``\gls{TrackedIsoCodeFromLanguage}
    \marg{\gls{TwoLetterIsoLanguageCode}}\marg{\cmd{ThisLanguage}}''). }
\codepar
Dialects:
\gls{ForEachTrackedDialect}\marg{\cmd{ThisDialect}}\marg{\cmd{ThisDialect}\cmd{space} 
(\gls{IfTrackedLanguageHasIsoCode}
  \marg{\gls{TwoLetterIsoCountryCode}}\marg{\cmd{ThisDialect}}\comment{}
 \marg{ISO \gls{TwoLetterIsoCountryCode}: 
  ``\gls{TrackedIsoCodeFromLanguage}
      \marg{\gls{TwoLetterIsoCountryCode}}\marg{\cmd{ThisDialect}}''}%
 \marg{no specific region};
root: \gls{TrackedLanguageFromDialect}\marg{\cmd{ThisDialect}}). }
\codepar
Language for ISO \gls{TwoLetterIsoCountryCode}\cmd{ }``GB'':
\gls{TrackedLanguageFromIsoCode}
  \marg{\gls{TwoLetterIsoCountryCode}}\marg{GB}.
\codepar
Language for ISO \gls{TwoLetterIsoCountryCode}\cmd{ }``CA'': 
\gls{TrackedLanguageFromIsoCode}
  \marg{\gls{TwoLetterIsoCountryCode}}\marg{CA}.
\codepar
Country ISO \gls{TwoLetterIsoCountryCode}\cmd{ }code for ``canadian'':
\gls{TrackedIsoCodeFromLanguage}
  \marg{\gls{TwoLetterIsoCountryCode}}\marg{canadian}.
\cend{document}
\end{codebox}
This produces:
\begin{resultbox}
Languages: english (ISO 639-1: ``en''). french (ISO 639-1: ``fr'').
dutch (ISO 639-1: ``nl'').

Dialects: american (ISO 3166-1: ``US''; root: english).
british (ISO 3166-1: ``GB''; root: english).
canadian (ISO 3166-1: ``CA''; root: english).
canadien (ISO 3166-1: ``CA''; root: french).
dutch (no specific region; root: dutch).
francais (no specific region; root: french).

Language for ISO 3166-1 ``GB'': british.

Language for ISO 3166-1 ``CA'': canadian,canadien.

Country ISO 3166-1 code for ``canadian'': CA.
\end{resultbox}

As from v1.3, each tracked dialect may also have an associated 
variant, which can be fetched using:
\cmddef{GetTrackedDialectVariant}
where \meta{dialect} is the label identifying the dialect.
This value is typically obtained by parsing a language tag
with \gls{TrackLanguageTag} but may be set explicitly.

You can test if a dialect has an associated variant using:
\cmddef{IfHasTrackedDialectVariant}

As from v1.3, each tracked dialect may also have an associated 
script, which can be fetched using:
\cmddef{GetTrackedDialectScript}
where \meta{dialect} is the label identifying the dialect.

You can test if a dialect has an associated script using:
\cmddef{IfHasTrackedDialectScript}
If the dialect has an associated script this does \meta{true}
otherwise it does \meta{false}. This information is provided
for language packages that need to know what script is required,
but there's no guarantee that the script will actually be set
in the document. Similarly for all the other attributes described
here.

Note that the script should be a recognised four-letter \idxn{15924}
code, such as \opt{Latn} or \opt{Cyrl}. If a~dialect
doesn't have an associated script then the default for the root
language should be assumed. For example, \opt{Latn} for English dialects or
\opt{Cyrl} for Russian dialects. The default script for
known languages can be obtained using:
\cmddef{TrackLangGetDefaultScript}
Most root languages have a default script, but there
are a few without one as it may depend on region, politics
or ideology.

There's a convenient expandable command for testing the script:
\cmddef{IfTrackedDialectIsScriptCs}
This tests if the given tracked dialect has an associated script and
compares the value with the replacement text of \meta{cs}.
If the dialect hasn't been explicitly assigned a script,
then test is performed against the default script for the root
language.

The supplementary package \sty{tracklang-scripts} provides some
additional commands relating to writing systems, including commands 
in the form \gls{TrackLangScriptCode} where
\meta{Code} is the \idxn{15924} four-letter code. If the dialect
doesn't have an associated script, \meta{false} is done.
This package isn't
loaded automatically, so you'll need to explicitly load it. The
generic code is in \file{tracklang-scripts.tex}:
\begin{codebox}
\gls{input} tracklang-scripts
\end{codebox}
There's a convenient \LaTeX\ wrapper \file{tracklang-scripts.sty}:
\begin{codebox}
\cmd{usepackage}\marg{tracklang-scripts}
\end{codebox}
See \sectionref{sec:supplpkgs} for further details of
that package.

For example, the following defines a command to check if
the given dialect should use a Latin \idx{script}:
\begin{codebox}
\gls{input} tracklang-scripts
\cmd{def}\cmd{islatin}\#1\#2\#3\marg{\comment{}
  \gls{IfTrackedDialectIsScriptCs}\marg{\#1}\marg{\tklscript{Latn}}\marg{\#2}\marg{\#3}\comment{}
}
\end{codebox}

\begin{important}
Note that the \idx{script} value doesn't mean that the document is
actually using that script. It means that this is the user's
\emph{desired} script, but whether that \idx{script} is actually set relies
on the appropriate settings in the relevant language package (such
as \sty{polyglossia}['s] \optfmt{script} key).
\end{important}

As from v1.3, each tracked dialect may also have a sub-language
identifier (for example, \optfmt{arevela}), which can be fetched
using:
\cmddef{GetTrackedDialectSubLang}
where \meta{dialect} is the label identifying the dialect.

You can test if a dialect has an associated sub-tag using:
\cmddef{IfHasTrackedDialectSubLang}
If the dialect has an associated sub-tag this does \meta{true}
otherwise it does \meta{false}.

As from v1.3, each tracked dialect may also have additional
information, which can be fetched using:
\cmddef{GetTrackedDialectAdditional}
where \meta{dialect} is the label identifying the dialect.

You can test if a dialect has additional information using:
\cmddef{IfHasTrackedDialectAdditional}
If the dialect has additional information this does \meta{true}
otherwise it does \meta{false}.

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
\metametafilefmt{}{prefix}{\dhyphen french\dhyphen }{suffix}{} or 
\metametafilefmt{}{prefix}{\dhyphen frenchb\dhyphen }{suffix}{} or 
\metametafilefmt{}{prefix}{\dhyphen francais\dhyphen}{suffix}{}?
Should, say, the file containing the British English code be called
\metametafilefmt{}{prefix}{\dhyphen british\dhyphen }{suffix}{} or 
\metametafilefmt{}{prefix}{\dhyphen UKenglish\dhyphen }{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?

\label{pg:filesearch}To help with this, \sty{tracklang} provides:
\cmddef{IfTrackedLanguageFileExists}
This attempts to find the file called
\meta{prefix}\meta{localeid}\meta{suffix} where \meta{localeid} is determined
from \meta{dialect} (see below). If the file is found then
\cmddef{CurrentTrackedTag}
is set to \meta{localeid} and \meta{true code} is done, otherwise
\meta{false code} is done.  If this command
is empty, then the dialect hasn't been detected. If the dialect
has been detected, but no file can be found, then
\gls{CurrentTrackedTag} is set to the final attempt at determining
\meta{localeid}.

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.

\cmddef{IfTrackedLanguageFileExistsOmitDialectLabel}
As \gls{IfTrackedLanguageFileExists} but omits the test for the
dialect label. Note that if the dialect label happens to be
identical to the root language label, it will still be checked, but
at the very end instead of near the start.

\cmddef{IfTrackedLanguageFileExistsOmitOnlyRegion}
As \gls{IfTrackedLanguageFileExists} but omits the test for just the
region code.

\cmddef{IfTrackedLanguageFileExistsOmitDialectLabelOmitOnlyRegion}
Combination of the above two commands.
As \gls{IfTrackedLanguageFileExists} but omits the tests for the
dialect label and for just the region code.

There's a convenient shortcut command new to version 1.3:
\cmddef{TrackLangRequireDialect}
which uses \gls{IfTrackedLanguageFileExists} to input the resource
file if found. The prefix is given by \meta{pkgname}\code{-} and
the suffix is \code{.\ext+{ldf}}. A warning is issued if no resource file
is found. Note that while it makes sense for \meta{pkgname}
to be the same as the base name of the package that uses these
resource files, they don't have to be the same. This command
additionally defines:
\cmddef{TrackLangRequireDialectPrefix}
to \meta{pkgname}, which allows the prefix to be picked up by
resource file commands, such as \gls{TrackLangProvidesResource}
and \gls{TrackLangRequireResource}.  (See below.)

There are analogous commands
\cmddef{TrackLangRequireDialectOmitDialectLabel}
As above, but uses \gls{IfTrackedLanguageFileExistsOmitDialectLabel}.

\cmddef{TrackLangRequireDialectOmitDialectLabelOmitOnlyRegion}
As above, but uses
\gls{IfTrackedLanguageFileExistsOmitDialectLabelOmitOnlyRegion}.

\cmddef{TrackLangRequireDialectOmitOnlyRegion}
As above, but uses
\gls{IfTrackedLanguageFileExistsOmitOnlyRegion}.

The optional argument \meta{load code} is the code that actually
inputs the required file. This defaults to
\begin{codebox}
\gls{TrackLangRequireResource}\marg{\gls{CurrentTrackedTag}}
\end{codebox}

The \gls{IfTrackedLanguageFileExists} command sets up the current
tracked dialect with:
\begin{compactcodebox*}
\gls{SetCurrentTrackedDialect}\margm{dialect}
\end{compactcodebox*}
which enables the following commands that may be used within 
\meta{true code} or \meta{false code}:
\cmddef{CurrentTrackedDialect}
Expands to the dialect label.

\cmddef{CurrentTrackedLanguage}
If the dialect hasn't been detected, this command will be empty,
otherwise it will expand to the root language label (which may
be the same as the dialect label).

\cmddef{CurrentTrackedRegion}
If the dialect hasn't been detected, this command will be empty.
If the dialect has been assigned an \idxn{3166-1} code,
\gls{CurrentTrackedRegion} will expand to that code, otherwise it
will be empty.

\cmddef{CurrentTrackedIsoCode}
If the dialect hasn't been detected, this command will be empty.
Otherwise it may be empty or it may expand to the
\idxn{639-1} or \idxn{639-2} or \idxn{639-3} code.

\cmddef{CurrentTrackedDialectModifier}
The dialect's modifier or empty if not set. (This is set but not
used in the set of possible \meta{localeid} values.)

\cmddef{CurrentTrackedDialectVariant}
The dialect's variant or empty if not set.

\cmddef{CurrentTrackedDialectSubLang}
The dialect's sub-language code or empty if not set.

\cmddef{CurrentTrackedDialectAdditional}
The dialect's additional information or empty if not set.

\cmddef{CurrentTrackedLanguageTag}
The dialect's language tag. Take care not to confuse this
with \gls{CurrentTrackedTag}.

\cmddef{CurrentTrackedDialectScript}
The dialect's script. If the dialect doesn't have the script set,
the default script for the language is used instead.

\gls{IfTrackedLanguageFileExists} behaves as follows:
\begin{itemize}
 \item If no dialect with the given label has been
  detected, the condition evaluates to \emph{false} and
 \gls{CurrentTrackedTag} is empty.

 \item If a dialect with the given label has been detected, then:
 \begin{itemize}
 \item For each possible \meta{localeid} in an ordered set of tags determined by
   the dialect label (see below), the first file matching
   \meta{prefix}\meta{localeid}\meta{suffix} that's found on
   \TeX's path results in the condition evaluating to \emph{true} and
   \gls{CurrentTrackedTag} is set to the current \meta{localeid} in the
   set. The rest of the set of possible values of \meta{localeid} is skipped.

 \item If no file matching \meta{prefix}\meta{localeid}\meta{suffix} is
   found on \TeX's path, then the condition evaluates to \emph{false}
   and \gls{CurrentTrackedTag} is set to the final \meta{localeid} in the
   set (the language label).
 \end{itemize}
\end{itemize}

The ordered set of possible values of \meta{localeid} is determined from
the given dialect.
\begin{important}
The ordering has changed in version 1.4, which now also includes the
\idx{script} and \idx{variant}. This new ordering should typically make the more
common combinations closer to the start of the search.
\end{important}
The possible values of \meta{localeid} are listed below in the order of priority used
by \gls{IfTrackedLanguageFileExists}. Note that the set may contain
repetitions (for example, if the dialect label is the same as the
root language label). If an item contains an element that hasn't
been set (such as the \idxn{639-3} code or a sub-language
\meta{sublang} or \idx{variant}) then
that item is skipped.
\begin{enumerate}
\item \meta{localeid} is just the value of \gls{CurrentTrackedLanguageTag}.

\item \meta{localeid} is just the dialect label.
This step is omitted with \gls{IfTrackedLanguageFileExistsOmitDialectLabel}
and \gls{IfTrackedLanguageFileExistsOmitDialectLabelOmitOnlyRegion}.

\item \meta{localeid} is
\meta{ISO~639-1}\code{-}\meta{sublang}\code{-}\meta{script}\code{-}\meta{region}.

\item \meta{localeid} is
\meta{ISO~639-1}\code{-}\meta{script}\code{-}\meta{region}.

\item \meta{localeid} is
\meta{ISO~639-1}\code{-}\meta{sublang}\code{-}\meta{region} (if there's no script or if
the script is the default for the given language).
\meta{ISO~639-1}\code{-}\meta{region} (if there's no script or if
the script is the default for the given language).

\item \meta{localeid} is
\meta{ISO~639-1}\code{-}\meta{sublang}\code{-}\meta{script}.

\item \meta{localeid} is
\meta{ISO~639-1}\code{-}\meta{script}.

\item \meta{localeid} is \meta{ISO~639-1}\code{-}\meta{sublang}.

\item \meta{localeid} is just \meta{ISO~639-1}.

\item \meta{localeid} is
\meta{ISO~639-2}\code{-}\meta{sublang}\code{-}\meta{script}\code{-}\meta{region}.

\item \meta{localeid} is
\meta{ISO~639-2}\code{-}\meta{script}\code{-}\meta{region}.

\item \meta{localeid} is
\meta{ISO~639-2}\code{-}\meta{sublang}\code{-}\code{region} (if there's no script or if
the script is the default for the given language).
\meta{ISO~639-2}\code{-}\meta{region} (if there's no script or if
the script is the default for the given language).

\item \meta{localeid} is
\meta{ISO~639-2}\code{-}\meta{sublang}\code{-}\meta{script}.

\item \meta{localeid} is
\meta{ISO~639-2}\code{-}\meta{script}.

\item \meta{localeid} is \meta{ISO~639-2}\code{-}\meta{sublang}.
\item \meta{localeid} is just \meta{ISO~639-2}.

\item \meta{localeid} is
\meta{ISO~639-3}\code{-}\meta{sublang}\code{-}\meta{script}\code{-}\meta{region}.

\item \meta{localeid} is
\meta{ISO~639-3}\code{-}\meta{script}\code{-}\meta{region}.

\item \meta{localeid} is
\meta{ISO~639-3}\code{-}\meta{sublang}\code{-}\meta{region} (if there's no script or if
the script is the default for the given language).
\meta{ISO~639-3}\code{-}\meta{region} (if there's no script or if
the script is the default for the given language).

\item \meta{localeid} is
\meta{ISO~639-3}\code{-}\meta{sublang}\code{-}\meta{script}.

\item \meta{localeid} is
\meta{ISO~639-3}\code{-}\meta{script}.

\item \meta{localeid} is \meta{ISO~639-3}\code{-}\meta{sublang}.

\item \meta{localeid} is just \meta{ISO~639-3}.

\item \meta{localeid} is just \meta{region}.
This step is omitted with
\gls{IfTrackedLanguageFileExistsOmitOnlyRegion}
and \gls{IfTrackedLanguageFileExistsOmitDialectLabelOmitOnlyRegion}.

\item \meta{localeid} is
\meta{ISO~639-1}\code{-}\meta{sublang}\code{-}\meta{variant}
or \meta{ISO~639-1}\code{-}\meta{variant} if \meta{sublang} is missing.

\item \meta{localeid} is
\meta{ISO~639-2}\code{-}\meta{sublang}\code{-}\meta{variant}
or \meta{ISO~639-2}\code{-}\meta{variant} if \meta{sublang} is missing.

\item \meta{localeid} is
\meta{ISO~639-3}\code{-}\meta{sublang}\code{-}\meta{variant}
or \meta{ISO~639-3}\code{-}\meta{variant} if \meta{sublang} is missing.

\item \meta{localeid} is just the value of \gls{CurrentTrackedLanguage}
(the root language label).
\end{enumerate}

For example (pre v1.3):
\begin{codebox}[fontupper=\small\ttfamily]
\gls{AnyTrackedLanguages}
\marg{\comment{}
 \gls{ForEachTrackedDialect}\marg{\cmd{ThisDialect}}\comment{}
 \marg{\comment{}
  \comment{try to load the language file for this dialect}
  \gls{IfTrackedLanguageFileExists}\marg{\cmd{ThisDialect}}\comment{}
  \marg{mypackage-}\comment{file prefix}
  \marg{.ldf}\comment{file suffix}
  \marg{\gls{input} mypackage-\gls{CurrentTrackedTag}.ldf}\comment{file found}
  \marg{\comment{file not found}
    \cmd{PackageWarning}\marg{mypackage}
      \marg{No support for language `\cmd{ThisDialect}'}\comment{}
  }\comment{}
 }\comment{}
}
\marg{\comment{no languages detected so use defaults}
}
\end{codebox}
With version 1.3 onwards, this can be written more concisely as:
\begin{codebox}[fontupper=\small\ttfamily]
\gls{AnyTrackedLanguages}
\marg{\comment{}
 \gls{ForEachTrackedDialect}\marg{\cmd{ThisDialect}}\comment{}
 \marg{\comment{}
  \comment{try to load the language file for this dialect}
  \gls{TrackLangRequireDialect}\marg{mypackage}\marg{\cmd{ThisDialect}}\comment{}
 }\comment{}
}
\marg{\comment{no languages detected so use defaults}
}
\end{codebox}
which additionally enables the \sty{tracklang} version 1.3 commands described below,
such as \gls{TrackLangRequireResource}.

\plabel{pg.britishfilesearch}%
If, for example, \cmd{ThisDialect} is \opt{british}, then the file search will
be in the order:
\begin{enumerate}
\item \ldf{mypackage}{en-GB} (language tag)
\item \ldf{mypackage}{british} (dialect label)

\item \ldf{mypackage}{en-Latn-GB} (\idx{639-1} language code,
\idx{script}, \idx{region})
\item \ldf{mypackage}{en-GB} (\idx{639-1} language code,
\idx{region})
\item \ldf{mypackage}{en-Latn} (\idx{639-1} language code,
\idx{script})
\item \ldf{mypackage}{en} (\idx{639-1} language code)

\item \ldf{mypackage}{eng-Latn-GB} (\idx{639-2} language
code, \idx{script}, \idx{region})
\item \ldf{mypackage}{eng-GB} (\idx{639-2} language code,
\idx{region})
\item \ldf{mypackage}{eng-Latn} (\idx{639-2} language code,
\idx{script})
\item \ldf{mypackage}{eng} (\idx{639-2} language code)

\item \ldf{mypackage}{GB} (\idx{region})
\item \ldf{mypackage}{english} (language label)
\end{enumerate}

If, for example, \cmd{ThisDialect} is \opt{naustrian}, then the file search will
be in the order:
\begin{enumerate}
\item \ldf{mypackage}{de-AT-1996} (language tag)
\item \ldf{mypackage}{naustrian} (dialect label)

\item \ldf{mypackage}{de-Latn-AT} (\idx{639-1} language code,
\idx{script}, \idx{region})
\item \ldf{mypackage}{de-AT} (\idx{639-1} language code,
\idx{region})
\item \ldf{mypackage}{de-Latn} (\idx{639-1} language code,
\idx{script})
\item \ldf{mypackage}{de} (\idx{639-1} language code)

\item \ldf{mypackage}{deu-Latn-AT} (\idx{639-2} language
code, \idx{script}, \idx{region})
\item \ldf{mypackage}{deu-AT} (\idx{639-2} language code,
\idx{region})
\item \ldf{mypackage}{deu-Latn} (\idx{639-2} language code,
\idx{script})
\item \ldf{mypackage}{deu} (\idx{639-2} language code)

\item \ldf{mypackage}{AT} (\idx{region})

\item \ldf{mypackage}{de-1996} (\idx{639-1} language code,
\idx{variant})
\item \ldf{mypackage}{deu-1996} (\idx{639-2} language code,
\idx{variant})

\item \ldf{mypackage}{german} (language label)
\end{enumerate}

If, for example, \cmd{ThisDialect} is \opt{francais}, then the file search will
be in the order: 
\begin{enumerate}
\item \ldf{mypackage}{fr} (language tag)
\item \ldf{mypackage}{francais} (dialect label)
\item \ldf{mypackage}{fr-Latn} (\idx{639-1} language code,
\idx{script})
\item \ldf{mypackage}{fr} (\idx{639-1} language code)
\item \ldf{mypackage}{fra-Latn} (\idx{639-2} language code,
\idx{script})
\item \ldf{mypackage}{fra} (\idx{639-2} language code)
\item \ldf{mypackage}{french} (language)
\end{enumerate}
This is because the predefined \opt{francais} option has no
region assigned to it. Be careful if the dialect label is the actual
root language. For example, if \cmd{ThisDialect} is \opt{french},
then the file search will be in the order:
\begin{enumerate}
\item \ldf{mypackage}{fr} (language tag)
\item \ldf{mypackage}{french} (dialect label)
\item \ldf{mypackage}{fr-Latn} (\idx{639-1} language code,
\idx{script})
\item \ldf{mypackage}{fr} (\idx{639-1} language code)
\item \ldf{mypackage}{fra-Latn} (\idx{639-2} language code,
\idx{script})
\item \ldf{mypackage}{fra} (\idx{639-2} language code)
\item \ldf{mypackage}{french} (language)
\end{enumerate}
Note that the last try will always fail in this case since if the
file exists, it will be found on the second try.

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 \opt{french},
the script is \opt{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):
\begin{codebox}[fontupper=\small\ttfamily]
\gls{AnyTrackedLanguages}
\marg{\comment{}
 \gls{ForEachTrackedLanguage}\marg{\cmd{ThisLanguage}}\comment{}
 \marg{\comment{try to load the language file for this root language}
   \gls{IfTrackedLanguageFileExists}\marg{\cmd{ThisLanguage}}\comment{}
   \marg{mypackage-}\comment{file prefix}
   \marg{.ldf}\comment{file suffix}
   \marg{\gls{input} mypackage-\gls{CurrentTrackedTag}.ldf}\comment{file found}
   \marg{\comment{file not found}
     \cmd{PackageWarning}\marg{mypackage}\marg{No support for language
      `\cmd{ThisLanguage}'}\comment{}
   }\comment{}
 }\comment{}
}
\marg{\comment{no languages detected so use defaults}
}
\end{codebox}
With version 1.3 onwards, this can be written more concisely as:
\begin{codebox}[fontupper=\small\ttfamily]
\gls{AnyTrackedLanguages}
\marg{\comment{}
 \gls{ForEachTrackedLanguage}\marg{\cmd{ThisLanguage}}\comment{}
 \marg{\comment{try to load the language file for this root language}
   \gls{TrackLangRequireDialect}\marg{mypackage}\marg{\cmd{ThisLanguage}}\comment{}
 }\comment{}
}
\marg{\comment{no languages detected so use defaults}
}
\end{codebox}
which additionally enables the commands described below.
Note that in this case, if more than one dialect for the same
language has been tracked, only the hooks for the last dialect for
that language will be adjusted, so it's usually best to iterate over
the dialects.

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

Within the resource file \localemetafile{pkgname}, 
you can identify the file using (new to version 1.3):
\cmddef{TrackLangProvidesResource}
where \meta{tag} is the locale identifier.

If \gls{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 
\localemetametafile{pkgname}{tag}, 
using (new to version 1.3):
\cmddef{TrackLangRequireResource}
For example, the dialect file \ldf{foo}{en-GB} might need to
load the root language resource file \ldf{foo}{english}:
\begin{codebox}
\comment{(In file \ldf{foo}{en-GB})}
\comment{Declare this regional file:}
\gls{TrackLangProvidesResource}\marg{en-GB}
\comment{load root language file \ldf{foo}{english}:}
\gls{TrackLangRequireResource}\marg{english}
\end{codebox}
If \ldf{foo}{english} is also identified with
\gls{TrackLangProvidesResource}, this will ensure that it's only
loaded once.

It may be that you want to load a file depending on the input
encoding. The \sty{inputenc} package defines
\gls{inputencodingname}, but this is only used with \pdfLaTeX. To
avoid repeated tests to determine whether or not \gls{inputencodingname}
has been defined, you can use:
\cmddef{TrackLangEncodingName}
This will expand to \code{utf8} if \gls{inputencodingname} hasn't
been defined, otherwise it will expand to \gls{inputencodingname}.
For example:
\begin{codebox*}
\gls{InputIfFileExists}\marg{foo-\gls{TrackLangEncodingName}.ldf}
\marg{\comment{support available for the document encoding}
}
\marg{\comment{no support for the document encoding}
}
\end{codebox*}

If you require the resource file and want to perform
\meta{code1} if it's loaded at this point or \meta{code2} if it's
already been loaded then you can use:
\cmddef{TrackLangRequireResourceOrDo}

If you want to load a resource file if it exists (without an
error if it doesn't exist), then you can use
\cmddef{TrackLangRequestResource}
If the file doesn't exist, \meta{not found code} is done.

\begin{important}
Note that these \cmd{\ldots Resource\ldots} commands are only
permitted within the resource files. They are internally enabled
through \gls{TrackLangRequireDialect}.
\end{important}

The above restriction on the resource files loaded through
\gls{TrackLangRequireDialect}, and the fact that it internally uses
\gls{IfTrackedLanguageFileExists}, means that commands like
\gls{CurrentTrackedLanguage} or \gls{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
\ldf{foo}{en-GB} might have been loaded with, say, the
\opt{british} dialect or with the synonymous \opt{UKenglish}
dialect or with a dialect label that doesn't have a corresponding
caption hook, such as \optfmt{enGBLatn}.)

The \sty{polyglossia} package has language caption hooks in the form 
\tklcaptions{\meta{language}} (where \meta{language} is the root language
label) whereas \sty{babel} has dialect captions hooks
in the form \gls{captionsdialect} (where \meta{dialect} is the
dialect label). This leads to a rather
cumbersome set of conditionals:
\begin{compactcodebox}
\cmd{ifcsundef}\marg{captions\gls{CurrentTrackedLanguage}}
\marg{\comment{}
  \cmd{ifcsundef}\marg{captions\gls{CurrentTrackedDialect}}\comment{}
  \marg{}\comment{}
  \marg{\comment{}
    \cmd{csgappto}\marg{captions\gls{CurrentTrackedDialect}}\marg{\comment{}
      \comment{code to append to hook}
    }\comment{}
  }\comment{}
}\comment{}
\marg{\comment{}
  \cmd{csgappto}\marg{captions\gls{CurrentTrackedLanguage}}\marg{\comment{}
    \comment{code to append to hook}
  }\comment{}
}
\comment{do code now to initialise}
\end{compactcodebox}
Note that the above has been simplified through the use of
\sty{etoolbox} commands, which isn't suitable for generic use.
It also doesn't query the mapping from \sty{tracklang}['s] dialect
label to the closest matching \sty{babel} dialect label.

Instead, \sty{tracklang} provides a command
to perform this set of conditionals using generic code:
\cmddef{TrackLangAddToHook}
where \meta{code} is the code to append to the \meta{type} hook.
This always performs \meta{code} after testing for the hook in case
the hook is undefined or has already been called (for example, \sty{ngerman} uses
\tklcaptions{ngerman} when the package is loaded, not at the start of
the document).

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

Since \optfmt{captions} is a commonly used hook type, there's 
a~shortcut command provided:
\cmddef{TrackLangAddToCaptions}
This is equivalent to
\begin{compactcodebox}
\gls{TrackLangAddToHook}\margm{code}\marg{captions}
\end{compactcodebox}

There may be some hooks, such as \gls{datedialect}, that need
redefining rather than appending to, so there's an
analogous command:
\cmddef{TrackLangRedefHook}
which will redefined the hook to do \meta{code}.

Note that no expansion is performed on \meta{code} when appending or
redefining a hook.

\section{Examples}
\label{sec:examples}

The examples in this section illustrate the above commands.

\subsection{\filefmt{animals.sty}}
\label{sec:animals}

This example is for a trivial package called \file{animals.sty}
that defines three textual commands: \cmd{catname}, \cmd{dogname}
and \cmd{ladybirdname}. The default values are: \qt{cat}, \qt{dog} and
\qt{bishy-barney-bee}.\footnote{Thass Broad Norfolk, my bewties
\code{:-P}}
The supported languages are defined in files
\localefile{animals}.

Here's the code for \file{animals.sty}:
\begin{codebox}[fontupper=\small\ttfamily]
\comment{Example package animals.sty}
\cmd{NeedsTeXFormat}\marg{LaTeX2e}
\cmd{ProvidesPackage}\marg{animals}
\codepar
\cmd{RequirePackage}\marg{tracklang}[2019/11/30]\comment{v1.4}
\codepar
\comment{Any undeclared options are language settings:}
\codepar
\cmd{DeclareOption}*\marg{\comment{}
 \gls{TrackIfKnownLanguage}\marg{\cmd{CurrentOption}}\comment{}
 \marg{\comment{successful}
  \cmd{PackageInfo}\marg{animals}\marg{Tracking language `\cmd{CurrentOption}'}\comment{}
 }\comment{}
 \marg{\comment{failed}
   \cmd{PackageError}\marg{animals}\comment{}
   \marg{Unknown language specification `\cmd{CurrentOption}'}\comment{}
   \marg{You need to supply either a known dialect label 
    or a valid language tag}\comment{}
 }\comment{}
}
\codepar
\cmd{ProcessOptions}
\codepar
\comment{Default definitions}
\cmd{newcommand}\cmd{catname}\marg{cat}
\cmd{newcommand}\cmd{dogname}\marg{dog}
\cmd{newcommand}\cmd{ladybirdname}\marg{bishy-barney-bee}
\codepar
\gls{AnyTrackedLanguages}
\marg{\comment{}
  \gls{ForEachTrackedDialect}\marg{\cmd{this@dialect}}\marg{\comment{}
    \gls{TrackLangRequireDialect}\marg{animals}\marg{\cmd{this@dialect}}\comment{}
  }\comment{}
}
\marg{\comment{no tracked languages, default already set up}
}
\codepar
\cmd{endinput}
\end{codebox}
Here's a Plain \TeX\ version that picks up the language from the
locale environment variable:
\begin{codebox}[fontupper=\small\ttfamily]
\gls{input} tracklang
\codepar
\gls{TrackLangFromEnv}
\codepar
\comment{Default definitions}
\cmd{def}\cmd{catname}\marg{cat}
\cmd{def}\cmd{dogname}\marg{dog}
\cmd{def}\cmd{ladybirdname}\marg{bishy-barney-bee}
\codepar
\gls{AnyTrackedLanguages}
\marg{\comment{}
  \gls{ForEachTrackedDialect}\marg{\cmd{thisdialect}}\marg{\comment{}
    \gls{TrackLangRequireDialect}\marg{animals}\marg{\cmd{thisdialect}}\comment{}
  }\comment{}
}
\marg{\comment{no tracked languages, default already set up}
}
\end{codebox}
In the event that a user or supplementary package for some 
reason wants to load a resource
file for a language that hasn't been tracked, it might be worth
providing a command for this purpose:
\begin{codebox}
\cmd{newcommand}*\marg{\cmd{RequireAnimalsDialect}}[1]\marg{\comment{}
  \gls{TrackLangRequireDialect}\marg{animals}\marg{\#1}\comment{}
}
\end{codebox}
The loop can then be changed to:
\begin{codebox}
\gls{ForEachTrackedDialect}\marg{\cmd{this@dialect}}\marg{\comment{}
  \cmd{RequireAnimalsDialect}\cmd{this@dialect}
}\comment{}
\end{codebox}

The \ldf{animals}{english} file valid for both the Plain \TeX\
and \LaTeX\ formats contains:
\begin{codebox}
\gls{TrackLangProvidesResource}\marg{english}
\codepar
\cmd{def}\cmd{englishanimals}\marg{\comment{}
  \cmd{def}\cmd{catname}\marg{cat}\comment{}
  \cmd{def}\cmd{dogname}\marg{dog}\comment{}
  \cmd{def}\cmd{ladybirdname}\marg{bishy-barney-bee}\comment{}
}
\codepar
\gls{TrackLangAddToCaptions}\marg{\cmd{englishanimals}}
\end{codebox}
The \ldf{animals}{en-GB} file contains:
\begin{codebox}
\gls{TrackLangProvidesResource}\marg{en-GB}
\gls{TrackLangRequireResource}\marg{english}
\codepar
\cmd{def}\cmd{enGBanimals}\marg{\comment{}
  \cmd{englishanimals}
  \cmd{def}\cmd{ladybirdname}\marg{ladybird}\comment{}
}
\gls{TrackLangAddToCaptions}\marg{\cmd{enGBanimals}}
\end{codebox}
The \ldf{animals}{en-US} file contains:
\begin{codebox}
\gls{TrackLangProvidesResource}\marg{en-US}
\gls{TrackLangRequireResource}\marg{english}
\codepar
\cmd{def}\cmd{enUSanimals}\marg{\comment{}
  \cmd{englishanimals}
  \cmd{def}\cmd{ladybirdname}\marg{ladybug}\comment{}
}
\gls{TrackLangAddToCaptions}\marg{\cmd{enUSanimals}}
\end{codebox}
Here's a German version in the file \ldf{animals}{german}:
\begin{codebox}
\gls{TrackLangProvidesResource}\marg{german}
\codepar
\cmd{def}\cmd{germananimals}\marg{\comment{}
  \cmd{def}\cmd{catname}\marg{Katze}\comment{}
  \cmd{def}\cmd{dogname}\marg{Hund}\comment{}
  \cmd{def}\cmd{ladybirdname}\marg{Marienk\cmd{"}afer}\comment{}
}
\codepar
\gls{TrackLangAddToCaptions}\marg{\cmd{germananimals}}
\end{codebox}

This means that if \sty{babel} or \sty{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 \cmd{\ldots animals} commands.

Here's an example \LaTeX\ document that doesn't have any caption
hooks:
\begin{codebox}
\cmd{documentclass}[\opt{english},\opt{german}]\marg{article}
\codepar
\cmd{usepackage}\marg{animals}
\codepar
\cbeg{document}
\cmd{englishanimals}
\codepar
\cmd{catname}.
\cmd{dogname}.
\cmd{ladybirdname}.
\codepar
\cmd{germananimals}
\codepar
\cmd{catname}.
\cmd{dogname}.
\cmd{ladybirdname}.
\cend{document}
\end{codebox}
Here's a \sty{babel} example document:
\begin{codebox}
\cmd{documentclass}[\opt{american},\opt{german},\opt{british}]\marg{article}
\codepar
\cmd{usepackage}\marg{babel}
\cmd{usepackage}\marg{animals}
\codepar
\cbeg{document}
\cmd{selectlanguage}\marg{american}
\codepar
\cmd{catname}.
\cmd{dogname}.
\cmd{ladybirdname}.
\codepar
\cmd{selectlanguage}\marg{german}
\codepar
\cmd{catname}.
\cmd{dogname}.
\cmd{ladybirdname}.
\codepar
\cmd{selectlanguage}\marg{british}
\codepar
\cmd{catname}.
\cmd{dogname}.
\cmd{ladybirdname}.
\cend{document}
\end{codebox}

There is some redundancy with the above resource files. Consider the
\sty{babel} example above. The \opt{american} dialect is the
first option, so in that case \ldf{animals}{en-US} is loaded
followed by \ldf{animals}{english}. This means that the
\tklcaptions{american} hook now includes
\begin{codebox}
\cmd{englishanimals}
\cmd{enUSanimals}
\end{codebox}
Since \cmd{enUSanimals} includes \cmd{englishanimals}, there is
redundant code. However, when the \opt{british} dialect is
processed, this loads the file \ldf{animals}{en-GB} but not
the file \ldf{animals}{english} (since it's already been loaded). This
means that \tklcaptions{british} contains \cmd{enGBanimals} but not 
\cmd{englishanimals}.

If this redundancy is an issue (for example, there are so many
redefinitions needed that it significantly slows the document build
process), then it can be addressed with the following modifications.
The \ldf{animals}{en-GB} file is now:
\begin{codebox}
\gls{TrackLangProvidesResource}\marg{en-GB}
\codepar
\cmd{def}\cmd{enGBanimals}\marg{\comment{}
  \cmd{englishanimals}
  \cmd{def}\cmd{ladybirdname}\marg{ladybird}\comment{}
}
\codepar
\gls{TrackLangRequireResourceOrDo}\marg{english}\comment{}
\marg{
  \gls{TrackLangAddToCaptions}\marg{\comment{}
    \cmd{def}\cmd{ladybirdname}\marg{ladybird}\comment{}
  }\comment{}
}
\marg{
  \gls{TrackLangAddToCaptions}\marg{\cmd{enGBanimals}}
}
\end{codebox}
The \ldf{animals}{en-US} file is now:
\begin{codebox}
\gls{TrackLangProvidesResource}\marg{en-US}
\codepar
\cmd{providecommand}*\marg{\cmd{enUSanimals}}\marg{\comment{}
  \cmd{englishanimals}
  \cmd{renewcommand}*\marg{\cmd{ladybirdname}}\marg{ladybug}\comment{}
}
\codepar
\gls{TrackLangRequireResourceOrDo}\marg{english}
\marg{
  \gls{TrackLangAddToCaptions}\marg{\comment{}
    \cmd{renewcommand}*\marg{\cmd{ladybirdname}}\marg{ladybird}\comment{}
  }\comment{}
}
\marg{
  \gls{TrackLangAddToCaptions}\marg{\cmd{enUSanimals}}
}
\end{codebox}
This means that the document that has the dialects listed in the
order \opt{american}, \opt{british} now has
\begin{codebox}
\cmd{englishanimals}
\cmd{def}\cmd{ladybirdname}\marg{ladybird}
\end{codebox}
in the \tklcaptions{british} hook and just \cmd{enUSanimals} in the
\tklcaptions{american} hook, which has removed most of the redundancy.

Note that \sty{polyglossia} has a \tklcaptions{english} hook but not
\tklcaptions{american} or \tklcaptions{british}, so this code doesn't
allow for switching between variants of the same language with
\sty{polyglossia}.

\subsection{\filefmt{regions.sty}}
\label{sec:regions}

\glsadd{file.regions.sty}%
\phyperref{Earlier}{pg.britishfilesearch}, I~mentioned the search order for
\gls{IfTrackedLanguageFileExists} where if, for example, the dialect
is \opt{british}, the file search (v1.4+) will be:
\begin{enumerate}
\item \ldf{mypackage}{en-GB} (language tag)
\item \ldf{mypackage}{british} (dialect label)

\item \ldf{mypackage}{en-Latn-GB} (\idx{639-1} language code,
\idx{script}, \idx{region})
\item \ldf{mypackage}{en-GB} (\idx{639-1} language code,
\idx{region})
\item \ldf{mypackage}{en-Latn} (\idx{639-1} language code,
\idx{script})
\item \ldf{mypackage}{en} (\idx{639-1} language code)

\item \ldf{mypackage}{eng-Latn-GB} (\idx{639-2} language
code, \idx{script}, \idx{region})
\item \ldf{mypackage}{eng-GB} (\idx{639-2} language code,
\idx{region})
\item \ldf{mypackage}{eng-Latn} (\idx{639-2} language code,
\idx{script})
\item \ldf{mypackage}{eng} (\idx{639-2} language code)

\item \ldf{mypackage}{GB} (\idx{region})
\item \ldf{mypackage}{english} (language label)
\end{enumerate}
You may have wondered why
\ldf{mypackage}{GB} is included in the search given that some
countries have multiple official languages, which means that the country code on its
own may not indicate the language.

The reason for including just the country code as the \meta{localeid} in the 
file search is to allow for region rather than language dependent
settings. For example, suppose I~want to write a package that needs
to know whether to use imperial or metric measurements in the
document, but I also want to provide multilingual support. The
language alone won't tell me whether to use imperial or metric (for
example, the US uses imperial and the UK uses metric for most
product attributes). I could provide \ext+{ldf} files for every
language and region combination, but this would result in a lot
redundancy.

\gls{TrackLangRequireDialect} has an optional argument for adjusting
the way the resource files are loaded. Suppose I have
\localefile{regions} resource files, then
\begin{codebox}
\gls{TrackLangRequireDialect}\marg{regions}\marg{\cmd{this@dialect}}
\end{codebox}
loads the resource file for the dialect given by \cmd{this@dialect}
using:
\begin{compactcodebox}
\gls{TrackLangRequireResource}\marg{\gls{CurrentTrackedTag}}
\end{compactcodebox}
I can use the optional argument to also load the resource file for the
root language as well:
\begin{codebox}[fontupper=\small\ttfamily]
\comment{custom file loader for regions.sty}
\cmd{newcommand}*\marg{\cmd{RequireRegionsDialect}}[1]\marg{\comment{}
 \gls{TrackLangRequireDialect}
  \oarg{\gls{TrackLangRequireResource}\marg{\gls{CurrentTrackedTag}}\comment{}
   \gls{TrackLangRequireResource}
     \marg{\gls{CurrentTrackedLanguage}}\comment{}
  }\comment{}
  \marg{regions}\marg{\#1}\comment{}
}
\end{codebox}
Now the dialect \opt{british} can load both
\ldf{regions}{GB} and \ldf{regions}{english}.

The example package (\file{regions.sty}) below illustrates this.
\begin{codebox}[fontupper=\small\ttfamily]
\comment{Example package regions.sty}
\cmd{NeedsTeXFormat}\marg{LaTeX2e}
\cmd{ProvidesPackage}\marg{regions}
\codepar
\gls{RequirePackage}\marg{tracklang}[2016/10/07]\comment{v1.3+}
\codepar
\cmd{DeclareOption}*\marg{\gls{TrackLanguageTag}\marg{\cmd{CurrentOption}}}
\cmd{ProcessOptions}
\codepar
\cmd{newcommand}*\marg{\cmd{weightunit}}\marg{kg}
\cmd{newcommand}*\marg{\cmd{lengthunit}}\marg{mm}
\cmd{newcommand}*\marg{\cmd{currencyunit}}\marg{EUR}
\codepar
\cmd{newcommand}*\marg{\cmd{unitname}}\marg{units}
\codepar
\cmd{newcommand}*\marg{\cmd{RequireRegionsDialect}}[1]\marg{\comment{}
 \gls{TrackLangRequireDialect}
  \oarg{\gls{TrackLangRequireResource}\marg{\gls{CurrentTrackedTag}}\comment{}
   \gls{TrackLangRequireResource}
     \marg{\gls{CurrentTrackedLanguage}}\comment{}
  }\comment{}
  \marg{regions}\marg{\#1}\comment{}
}
\codepar
\gls{AnyTrackedLanguages}
\marg{\comment{}
 \gls{ForEachTrackedDialect}\marg{\cmd{this@dialect}}\marg{\comment{}
   \cmd{RequireRegionsDialect}\cmd{this@dialect}
 }\comment{}
}
\marg{\comment{no tracked languages, default already set up}
}
\codepar
\cmd{endinput}
\end{codebox}
There are separate \ext{ldf} files for region and language.
First are the regions.

\begin{itemize}
\item \ldf{regions}{BE} (Belgium):
\begin{codebox}
\gls{TrackLangProvidesResource}\marg{BE}
\codepar
\cmd{providecommand}*\marg{\cmd{BEunits}}\marg{\comment{}
  \cmd{renewcommand}*\marg{\cmd{weightunit}}\marg{kg}\comment{}
  \cmd{renewcommand}*\marg{\cmd{lengthunit}}\marg{mm}\comment{}
  \cmd{renewcommand}*\marg{\cmd{currencyunit}}\marg{EUR}\comment{}
}
\codepar
\gls{TrackLangAddToCaptions}\marg{\cmd{BEunits}}
\end{codebox}

\item \ldf{regions}{CA} (Canada):
\begin{codebox}
\gls{TrackLangProvidesResource}\marg{CA}
\codepar
\cmd{providecommand}*\marg{\cmd{CAunits}}\marg{\comment{}
  \cmd{renewcommand}*\marg{\cmd{weightunit}}\marg{kg}\comment{}
  \cmd{renewcommand}*\marg{\cmd{lengthunit}}\marg{mm}\comment{}
  \cmd{renewcommand}*\marg{\cmd{currencyunit}}\marg{CAD}\comment{}
}
\codepar
\gls{TrackLangAddToCaptions}\marg{\cmd{CAunits}}
\end{codebox}

\item \ldf{regions}{GB} (Great Britain):
\begin{codebox}
\gls{TrackLangProvidesResource}\marg{GB}
\codepar
\cmd{providecommand}*\marg{\cmd{GBunits}}\marg{\comment{}
  \cmd{renewcommand}*\marg{\cmd{weightunit}}\marg{kg}\comment{}
  \cmd{renewcommand}*\marg{\cmd{lengthunit}}\marg{mm}\comment{}
  \cmd{renewcommand}*\marg{\cmd{currencyunit}}\marg{GBP}\comment{}
}
\codepar
\gls{TrackLangAddToCaptions}\marg{\cmd{GBunits}}
\end{codebox}

\item \ldf{regions}{US} (USA):
\begin{codebox}
\gls{TrackLangProvidesResource}\marg{US}
\codepar
\cmd{providecommand}*\marg{\cmd{USunits}}\marg{\comment{}
  \cmd{renewcommand}*\marg{\cmd{weightunit}}\marg{lb}\comment{}
  \cmd{renewcommand}*\marg{\cmd{lengthunit}}\marg{in}\comment{}
  \cmd{renewcommand}*\marg{\cmd{currencyunit}}\marg{USD}\comment{}
}
\codepar
\gls{TrackLangAddToCaptions}\marg{\cmd{USunits}}
\end{codebox}
\end{itemize}
Now the language files:

\begin{itemize}
\item \ldf{regions}{dutch}:
\begin{codebox}
\gls{TrackLangProvidesResource}\marg{dutch}
\codepar
\cmd{providecommand}*\marg{\cmd{dutchnames}}\marg{\comment{}
  \cmd{renewcommand}*\marg{\cmd{unitname}}\marg{meeteenheden}\comment{}
}
\codepar
\gls{TrackLangAddToCaptions}\marg{\cmd{dutchnames}}
\end{codebox}

\item \ldf{regions}{english}:
\begin{codebox}
\gls{TrackLangProvidesResource}\marg{english}
\codepar
\cmd{providecommand}*\marg{\cmd{englishnames}}\marg{\comment{}
  \cmd{renewcommand}*\marg{\cmd{unitname}}\marg{units}\comment{}
}
\codepar
\gls{TrackLangAddToCaptions}\marg{\cmd{englishnames}}
\end{codebox}

\item \ldf{regions}{french}:
\begin{codebox}
\cmd{TrackLangProvidesResource}\marg{french}
\codepar
\cmd{providecommand}*\marg{\cmd{frenchnames}}\marg{\comment{}
  \cmd{renewcommand}*\marg{\cmd{unitname}}\marg{unit\cmd{'}es}\comment{}
}
\codepar
\gls{TrackLangAddToCaptions}\marg{\cmd{frenchnames}}
\end{codebox}

\item \ldf{regions}{german}:
\begin{codebox}
\gls{TrackLangProvidesResource}\marg{french}
\codepar
\cmd{providecommand}*\marg{\cmd{germannames}}\marg{\comment{}
  \cmd{renewcommand}*\marg{\cmd{unitname}}\marg{Ma\cmd{ss} einheiten}\comment{}
}
\codepar
\gls{TrackLangAddToCaptions}\marg{\cmd{germannames}}
\end{codebox}
\end{itemize}

Here's an example document that uses this package:
\begin{codebox}
\cmd{documentclass}[\opt{canadien}]\marg{article}
\codepar
\cmd{usepackage}\marg{regions}
\codepar
\cbeg{document}
\codepar
\cmd{unitname}: \cmd{weightunit}, \cmd{lengthunit}, \cmd{currencyunit}.
\codepar
\cend{document}
\end{codebox}

This works because the \meta{localeid} search looks for the
country code before the root language label. However, this will fail if 
the dialect label is the same as a root language label that has an
associated territory, marked with \fnregion\ in
\tableref{tab:rootlangopts}, as then it will be picked up before the
country code.

In the above example, 
\ldf{regions}{CA} is matched rather than
\ldf{regions}{french}, so \ldf{regions}{CA} is loaded by
\begin{compactcodebox}
\gls{TrackLangRequireResource}\marg{\gls{CurrentTrackedTag}}
\end{compactcodebox}
After this, the language file \ldf{regions}{french} is then loaded:
\begin{compactcodebox}
\gls{TrackLangRequireResource}\marg{\gls{CurrentTrackedLanguage}}
\end{compactcodebox}

This assumes that there's a country code \ext{ldf} file
available. This example needs a little modification to use default
units in case the region is missing:
\begin{codebox}[fontupper=\small\ttfamily]
\comment{Modified example package regions.sty}
\cmd{NeedsTeXFormat}\marg{LaTeX2e}
\cmd{ProvidesPackage}\marg{regions}
\codepar
\comment{Pass all options to \file{tracklang.sty}:}
\cmd{DeclareOption}*\marg{\cmd{PassOptionsToPackage}\marg{\cmd{CurrentOption}}\marg{tracklang}}
\cmd{ProcessOptions}
\codepar
\gls{RequirePackage}\marg{tracklang}
\codepar
\cmd{newcommand}*\marg{\cmd{weightunit}}\marg{kg}
\cmd{newcommand}*\marg{\cmd{lengthunit}}\marg{mm}
\cmd{newcommand}*\marg{\cmd{currencyunit}}\marg{EUR}
\codepar
\cmd{newcommand}*\marg{\cmd{unitname}}\marg{units}
\codepar
\cmd{newcommand}*\marg{\cmd{defaultunits}}\marg{\comment{}
  \cmd{renewcommand}*\marg{\cmd{weightunit}}\marg{kg}\comment{}
  \cmd{renewcommand}*\marg{\cmd{lengthunit}}\marg{mm}\comment{}
  \cmd{renewcommand}*\marg{\cmd{currencyunit}}\marg{EUR}\comment{}
}
\codepar
\cmd{newcommand}*\marg{\cmd{RequireRegionsDialect}}[1]\marg{\comment{}
 \gls{TrackLangRequireDialect}
  \oarg{\gls{TrackLangRequireResource}\marg{\gls{CurrentTrackedTag}}\comment{}
    \cmd{ifx}\gls{CurrentTrackedTag}\gls{CurrentTrackedLanguage}
      \gls{TrackLangAddToCaptions}\marg{\cmd{defaultunits}}\comment{}
    \cmd{else}
      \gls{TrackLangRequireResource}
        \marg{\gls{CurrentTrackedLanguage}}\comment{}
    \cmd{fi}
  }\comment{}
  \marg{regions}\marg{\#1}\comment{}
}
\codepar
\gls{AnyTrackedLanguages}
\marg{\comment{}
  \gls{ForEachTrackedDialect}\marg{\cmd{this@dialect}}{\comment{}
    \cmd{RequireRegionsDialect}\cmd{this@dialect}
  }\comment{}
}
\marg{\comment{no tracked languages, default already set up}
}
\codepar
\cmd{endinput}
\end{codebox} 
Note that we still have a problem for dialect labels that are
identical to root language labels with an associated territory (such
as \opt{manx}). This case can be checked with the following
adjustment:
\begin{codebox}[fontupper=\small\ttfamily]
\cmd{newcommand}*\marg{\cmd{RequireRegionsDialect}}[1]\marg{\comment{}
 \gls{TrackLangRequireDialect}
 \oarg{\gls{TrackLangRequireResource}\marg{\gls{CurrentTrackedTag}}\comment{}
  \cmd{ifx}\gls{CurrentTrackedTag}\gls{CurrentTrackedLanguage}
    \cmd{ifx}\gls{CurrentTrackedRegion}\cmd{empty}
      \gls{TrackLangAddToCaptions}\marg{\cmd{defaultunits}}\comment{}
    \cmd{else}
      \gls{TrackLangRequireResource}
        \marg{\gls{CurrentTrackedRegion}}\comment{}
    \cmd{fi}
  \cmd{else}
    \gls{TrackLangRequireResource}
       \marg{\gls{CurrentTrackedLanguage}}\comment{}
  \cmd{fi}
 }\comment{}
 \marg{regions}\marg{\#1}\comment{}
}
\end{codebox}
In the case where both the dialect and root language label are
\opt{manx} with the resource files \ldf{regions}{manx}
and \ldf{regions}{IM}, then \gls{CurrentTrackedTag} will be
\opt{manx} (the dialect label) so \ldf{regions}{manx} will
be loaded with:
\begin{compactcodebox}
\gls{TrackLangRequireResource}\marg{\gls{CurrentTrackedTag}}
\end{compactcodebox}
In this case \gls{CurrentTrackedRegion} is \code{IM} (that is, it's
not empty) so then \ldf{regions}{IM} will be loaded with:
\begin{compactcodebox}
\gls{TrackLangRequireResource}\marg{\gls{CurrentTrackedRegion}}
\end{compactcodebox}

Here's another document that sets up dialects with
\sty{tracklang} labels that aren't recognised by \sty{babel}.
This means that there's no corresponding \gls{captionsdialect} hook
for either the dialect label or the root language label,
so mappings need to be defined from the \sty{tracklang} dialect
label to the matching \sty{babel} dialect label.

\begin{codebox}[fontupper=\small\ttfamily]
\cmd{documentclass}\marg{article}
\codepar
\cmd{usepackage}\marg{tracklang}
\codepar
\gls{TrackLanguageTag}\marg{de-US-1996}
\gls{SetTrackedDialectLabelMap}
  \marg{\gls{TrackLangLastTrackedDialect}}\marg{ngerman}
\codepar
\gls{TrackLanguageTag}\marg{en-MT}
\gls{SetTrackedDialectLabelMap}
  \marg{\gls{TrackLangLastTrackedDialect}}\marg{UKenglish}
\codepar
\cmd{usepackage}[main=ngerman,UKenglish]\marg{babel}
\cmd{usepackage}\marg{regions}
\codepar
\cbeg{document}
\gls{selectlanguage}\marg{ngerman}
\codepar
\cmd{unitname}: \cmd{weightunit}, \cmd{lengthunit}, \cmd{currencyunit}.
\codepar
\gls{selectlanguage}\marg{UKenglish}
\codepar
\cmd{unitname}: \cmd{weightunit}, \cmd{lengthunit}, \cmd{currencyunit}.
\codepar
\cend{document}
\end{codebox}
This produces:
\begin{resultbox}
Ma\ss einheiten: lb, in, USD.

units: kg, mm, EUR.
\end{resultbox}
Compare this with:
\begin{codebox}
\cmd{documentclass}\marg{article}
\codepar
\cmd{usepackage}[main=ngerman,UKenglish]\marg{babel}
\cmd{usepackage}\marg{regions}
\codepar
\cbeg{document}
\gls{selectlanguage}\marg{ngerman}
\codepar
\cmd{unitname}: \cmd{weightunit}, \cmd{lengthunit}, \cmd{currencyunit}.
\codepar
\gls{selectlanguage}\marg{UKenglish}
\codepar
\cmd{unitname}: \cmd{weightunit}, \cmd{lengthunit}, \cmd{currencyunit}.
\codepar
\cend{document}
\end{codebox}
which produces:
\begin{resultbox}
Ma\ss einheiten: kg, mm, EUR.

units: kg, mm, GBP.
\end{resultbox}

Note that these mappings aren't needed if \sty{babel}
is loaded with the root language labels instead. For example:
\begin{codebox}[fontupper=\small\ttfamily]
\cmd{documentclass}\marg{article}
\codepar
\cmd{usepackage}\marg{tracklang}
\codepar
\gls{TrackLanguageTag}\marg{de-US-1996}
\gls{SetTrackedDialectLabelMap}
 \marg{\gls{TrackLangLastTrackedDialect}}\marg{ngerman}
\codepar
\gls{TrackLanguageTag}\marg{en-MT}
\codepar
\cmd{usepackage}[main=ngerman,english]\marg{babel}
\cmd{usepackage}\marg{regions}
\codepar
\cbeg{document}
\gls{selectlanguage}\marg{ngerman}
\codepar
\cmd{unitname}: \cmd{weightunit}, \cmd{lengthunit}, \cmd{currencyunit}.
\codepar
\gls{selectlanguage}\marg{english}
\codepar
\cmd{unitname}: \cmd{weightunit}, \cmd{lengthunit}, \cmd{currencyunit}.
\codepar
\cend{document}
\end{codebox}
No mapping is required for the \opt{en-MT} locale as
it can pick up \tklcaptions{english} when \gls{TrackLangAddToHook}
(used by \gls{TrackLangAddToCaptions})
queries the root language label after failing to find the
language hook from the dialect label.

Some of the predefined \sty{tracklang} dialects come with
a mapping to the closest matching \sty{babel} dialect label.
For example, the option \opt{ngermanDE} listed in
\tableref{tab:nonisoopts} automatically provides a mapping
to \opt{ngerman}. Since a \sty{tracklang} dialect label 
can only map to one \sty{babel} label, this can be problematic
for synonymous labels such as
\opt{british}\slash\opt{UKenglish} or
\opt{american}\slash\opt{USenglish}. The default mappings used
by \sty{tracklang} are shown in \tableref{tab:nonisoopts}.

\chapter{Adding Support for Language Tracking}
\label{sec:langsty}

If you are writing a package that \emph{sets up} the document languages (rather
than a package that provides multilingual support if the user has
already loaded a language package) then you can load \sty{tracklang}
and use the commands below to help other packages track your
provided languages. (See also:
\dickimawhref{latex/tracklang/langpkg.shtml}{Integrating
\filefmt{tracklang.tex} into Language Packages}.)

The \sty{tracklang} package can be loaded using
\begin{codebox}
\gls{input} tracklang
\end{codebox}
or (\LaTeX\ only)
\begin{codebox}
\gls{RequirePackage}\marg{tracklang}
\end{codebox}

When using \LaTeX, there's a difference between the two.
The first case prevents \sty{tracklang} from picking up
the document class options but skips the check for known
language packages. This check is redundant since your package is
the language package, so you need to decide whether or
not to allow the user to set up the localisation information
through the document class options.

There's a hook that, if defined, is performed by
\file{tracklang.sty} after the package options have been loaded but
before known language packages are checked:
\cmddef{@tracklang@prelangpkgcheck@hook}

If you prefer \gls{RequirePackage} over \gls{input} but you want to make 
\file{tracklang.sty} skip the check for known
language packages then (as from v1.3.8) define the pre-language
package check hook as follows:
\begin{codebox}
\cmd{providecommand}\gls{@tracklang@prelangpkgcheck@hook}\marg{\cmd{endinput}}
\gls{RequirePackage}\marg{tracklang}[2019/10/06]\comment{v1.3.8+}
\end{codebox}
This will still pick up languages supplied through the
document class options.

If you just use \gls{input}, there's a test at the start of
\file{tracklang.tex} to determine if it's already been loaded, so
you don't need to worry if the document has already input it.

To integrate \sty{tracklang} into your language package, you need 
to consider the following steps:
\begin{enumerate}
\item Does \sty{tracklang} define your supported \idxn{15924} language
scripts in the \file{tracklang-scripts.tex} file?

If yes, then skip this step. Otherwise create a file with the
relevant \gls{TrackLangScriptMap} command for each unknown script and identify
this new file with \gls{TrackLangAddExtraScriptFile} (see
\sectionref{sec:newscripts}). This usually
won't be necessary unless you have a custom script or a child script
(a script that's a sub-category of another script).

\item Does \sty{tracklang} recognise the root language?

If yes, then skip this step.

If your package is setting up a language that \sty{tracklang}
doesn't recognise then you will need to define the root language
using \gls{TrackLangNewLanguage} (see \sectionref{sec:newlanguages}).

This usually won't be the case as \sty{tracklang} should support all
languages that have an official \idxn{639-1} alpha-2 code.

If you simply have a different label from \sty{tracklang}
identifying the root language, then you can just set up your label
as a dialect using \gls{TrackLangProvidePredefinedDialect}.

\item Does \sty{tracklang} define the relevant \idxn{3166-1} region codes
in the \file{tracklang-region-codes.tex} file?

If yes, then skip this step. Otherwise create a file with the
relevant \gls{TrackLangRegionMap} command for each new region and
identify this new file with \gls{TrackLangAddExtraRegionFile} (see
\sectionref{sec:newregions}). This usually won't be necessary as
\sty{tracklang} should recognise all countries that have an alpha-2
region code, but you may require it if you need a broader region,
such as EU.

\item Do you want to define some convenient dialect labels that can
be used with \gls{TrackPredefinedDialect}?

If no, then skip this step. Otherwise you can use
\gls{TrackLangProvidePredefinedLanguage} for root languages
and \gls{TrackLangProvidePredefinedDialect} for dialects with
additional information, such as a region, sub-language or script
(see \sectionref{sec:definelabels}).

\item In your language initialisation code, add the \sty{tracklang}
code to track the particular dialect (for example, use
\gls{TrackPredefinedDialect} for recognised dialect labels or
use the \csmetafmt{AddTracked}{Xxx}{} set of commands). See
\sectionref{sec:initnewlang}.

\item In your language selection code (such as \gls{selectlanguage}), add
\gls{SetCurrentTrackedDialect}\margm{label} to allow the document
author to easily query the current localisation settings (such as
the region). See \sectionref{sec:selectlanguage}.
\end{enumerate}

\section{Initialising a New Language or Dialect}
\label{sec:initnewlang}

When the user requests a particular dialect through your language
package, you can notify \sty{tracklang} of this choice using
\begin{compactcodebox*}
\gls{TrackPredefinedDialect}\margm{dialect label}
\end{compactcodebox*}
provided the dialect label is recognised by \sty{tracklang} (all those
listed in \refoptstables).

If there's no matching dialect predefined by \sty{tracklang}, you
can just use \gls{TrackLocale} or \gls{TrackLanguageTag} 
(described in \sectionref{sec:generic}) 
with the appropriate \idx{ISO} codes \emph{if you're not providing caption
hooks}.

If you are providing a captions hook mechanism
in the form \gls{captionsdialect}, then if \meta{dialect}
doesn't match the corresponding \sty{tracklang} dialect label,
you can provide a mapping using
\gls{SetTrackedDialectLabelMap}, described below.

\section{Switching Language or Dialect}
\label{sec:selectlanguage}

When the document author switches to a different language or
dialect, the current localisation information can be set with:
\cmddef{SetCurrentTrackedDialect}
where \meta{dialect} may the \sty{tracklang} dialect label,
or the mapped label previously set through \gls{SetTrackedDialectLabelMap},
described below, or the language label (in which case the
last dialect to be tracked with that root language will
be assumed).

This will make the following commands available which may be
of use to other packages:
\begin{itemize}
\item\gls{CurrentTrackedDialect} The dialect label recognised
by \sty{tracklang} (which may not be the same as \meta{dialect}).

\item\gls{CurrentTrackedLanguage}
The root language label used by \sty{tracklang}.

\item\gls{CurrentTrackedDialectModifier} The dialect modifier.

\item\gls{CurrentTrackedDialectVariant} The dialect variant.

\item\gls{CurrentTrackedDialectScript} The dialect script.
Note that if \sty{tracklang-scripts} is also loaded, this allows the
script direction to be accessed using
\begin{codebox}
\gls{TrackLangScriptAlphaToDir}
 \marg{\gls{CurrentTrackedDialectScript}}
\end{codebox}
See \sectionref{sec:supplpkgs} for further details.

\item\gls{CurrentTrackedDialectSubLang} The dialect sub-language
code.

\item\gls{GetTrackedDialectAdditional} The dialect's additional
information.

\item\gls{CurrentTrackedIsoCode} The dialect's root language 
\idx{ISO} code. (The first found in the sequence \idx{639-1},
\idx{639-2}, \idx{639-3}.)

\item\gls{CurrentTrackedRegion} The dialect's \idxn{3166-1} region 
code.

\item\gls{CurrentTrackedLanguageTag} The dialect's language tag.

\end{itemize}
(Without this automated use of \gls{SetCurrentTrackedDialect},
the same information can be picked up using commands
like \gls{GetTrackedDialectScript}, but that's less convenient,
especially if \gls{languagename} needs to be converted
to \meta{dialect}. See the accompanying sample file
\filefmt{sample-setlang.tex} for an example.)

\section{Defining New Scripts}
\label{sec:newscripts}

The \file{tracklang-scripts.tex} file isn't automatically loaded,
but if it is then, as from v1.4, it contains a hook at the end of
the file that can be used to load additional files that define
supplementary scripts. This entails creating a file called, say,
\filefmt{mypackage-scripts.tex} that contains:
\begin{compactcodebox*}
\gls{TrackLangScriptMap}\margm{alpha code}\margm{numeric code}\margm{name}\margm{direction}\margm{parent script}
\end{compactcodebox*}
The first argument \meta{alpha code} is the four-letter ISO~15924 code (such as
\opt{Latn}), the second argument is the numeric code (such as
215), the third argument \meta{name} is the name of the script (such
as \optfmt{Latin}), the fourth argument is the direction (such as
\optfmt{LR} for left-to-right) and the final argument is the parent
script (leave blank if there's no parent). Note that this command will override any previous
mapping for those codes. No check is performed to determine if they
have already been defined.

The supplementary file should be identified with:
\begin{compactcodebox*}
\gls{TrackLangAddExtraScriptFile}\margm{filename}
\end{compactcodebox*}

Additional information can be found in \sectionref{sec:supplpkgs}.

\section{Defining New Regions}
\label{sec:newregions}

The \file{tracklang-region-codes.tex} file isn't automatically loaded,
but if it is then, as from v1.4, it contains a hook at the end of
the file that can be used to load additional files that define
supplementary regions. This entails creating a file called, say,
\filefmt{mypackage-regions.tex} that contains:
\begin{compactcodebox*}
\gls{TrackLangRegionMap}\margm{numeric code}\margm{alpha-2
code}\margm{alpha-3 code}
\end{compactcodebox*}
where the first argument is the numeric region code (such as 826),
the second argument is the alpha-2 region code (such as \code{GB})
and the third argument is the alpha-3 region code (such as
\code{GBR}). Note that this command will override any previous
mapping for those codes. No check is performed to determine if they
have already been defined.

The supplementary file should be identified with:
\begin{compactcodebox*}
\gls{TrackLangAddExtraRegionFile}\margm{filename}
\end{compactcodebox*}

Additional information can be found in \sectionref{sec:supplpkgs}.

\section{Defining a New Language}
\label{sec:newlanguages}

(New to version 1.3.)
If the root language isn't recognised by \sty{tracklang}
(not listed in \tableref{tab:rootlangopts}), then
it can be defined (but not tracked at this point) using:
\cmddef{TrackLangNewLanguage}
where \meta{language label} is the root language label, 
\meta{639-1 code} is the \idxn{639-1} code for that language (may be
empty if there isn't one), \meta{639-2 (T)} is the \idxn{639-2T}
code for that language (may be empty if there isn't one),
\meta{639-2 (B)} is the \idxn{639-2B} code for that language (may be
empty if it's the same as \meta{639-2 (T)}), \meta{639-3} is the 
\idxn{639-3} code for that language (empty if the same as the 
\idx{639-2} code), \meta{3166-1} is the territory \idxn{3166-1} code for 
languages that are only spoken in one territory (should be empty if
the language is spoken in multiple territories), and \meta{default
script} is the default script (empty if disputed or varies according
to region).

You can then track this language using: 
\cmddef{AddTrackedDialect}
for dialects (where \meta{dialect label} is the dialect label and
\meta{root language label} is the root language label) or, if 
no regional variant is needed, you can instead use:
\cmddef{AddTrackedLanguage}
This is equivalent to 
\begin{compactcodebox}
\gls{AddTrackedDialect}\margm{root language label}\margm{root language label}
\end{compactcodebox}
Note that \gls{AddTrackedDialect} defines:
\cmddef{TrackLangLastTrackedDialect}
to the dialect label, which makes it easier to reference the last
dialect to be tracked.

\section{Defining New \styfmt{tracklang} Labels}
\label{sec:definelabels}

A dialect label may be predefined with associated information that
allows that particular combination to be easily tracked with
\gls{TrackPredefinedDialect}. In the case of a dialect label that
only requires the information provided in \gls{TrackLangNewLanguage}
you can use:
\cmddef{TrackLangProvidePredefinedLanguage}
where \meta{language label} corresponds to the language label used in
\gls{TrackLangNewLanguage}. This allows
\begin{compactcodebox*}
\gls{TrackPredefinedDialect}\margm{label}
\end{compactcodebox*}
to not only track the root language but also the associated ISO codes.

If the dialect label doesn't match the root language label then use:
\cmddef{TrackLangProvidePredefinedDialect}
where \meta{dialect label} is the new \sty{tracklang} dialect label,
\marg{root language label} is the \sty{tracklang} root language label,
\meta{region} is the \idxn{3166-1} region code (may be empty),
\meta{modifier} is the \idx{modifier} (may be empty), \meta{variant}
is the \idx{variant} information (may be empty), \meta{map} is your
package's language label that corresponds to the \sty{tracklang}
dialect label supplied in the first argument (may be empty if
identical), and \meta{script} is the \idxn{15924} alpha-4 script code
(may be empty if it's the same as the default script for the root
language).

For compatibility with pre version 1.3, 
if the dialect isn't predefined by
\sty{tracklang}, then you can use:
\begin{compactcodebox*}
\gls{AddTrackedDialect}\margm{dialect}\margm{root language label}
\end{compactcodebox*}
where \meta{root language label} is the label for the dialect's root
language (\tableref{tab:rootlangopts}) and \meta{dialect} matches
the captions hook. If the dialect is already in the tracked dialect
list, it won't be added again. If the root language is already in
the tracked language list, it won't be added again. As from version
1.3 this additionally defines
\gls{TrackLangLastTrackedDialect}
to \meta{dialect} for convenient reference if required.
Note that \gls{AddTrackedDialect} is internally used by commands like
\gls{TrackPredefinedDialect}, \gls{TrackLocale} and
\gls{TrackLanguageTag}.

(New to version 1.3.) Many of the \sty{tracklang} dialect
labels don't have a corresponding match in various language packages. For 
example, \sty{tracklang} provides \opt{ngermanDE} but the
closest match in \sty{babel} is \opt{ngerman}. This means that
the caption hook \tklcaptions{ngerman} can't be accessed
through:
\begin{compactcodebox}
\cmd{csname} captions\gls{CurrentTrackedDialect}\cmd{endcsname}
\end{compactcodebox}
in the resource files. In this case, a mapping may be defined
between the \sty{tracklang} dialect label and the closest
matching label used by the language hooks. This is done through
\cmddef{SetTrackedDialectLabelMap}
where \meta{tracklang-label} is the \sty{tracklang} label and
\meta{hook-label} is the language hook label. For example:
\begin{compactcodebox*}[fontupper=\small\ttfamily]
\gls{TrackLanguageTag}\marg{de-AR-1996}
\gls{SetTrackedDialectLabelMap}
  \marg{\gls{TrackLangLastTrackedDialect}}\marg{ngerman}
\end{compactcodebox*}
Since \gls{TrackLanguageTag} internally uses \gls{AddTrackedDialect}
the dialect label created by \sty{tracklang} can be accessed
using \gls{TrackLangLastTrackedDialect}. This means that
\gls{TrackLangAddToCaptions} can now find the \tklcaptions{ngerman}
hook even though the \sty{tracklang} dialect label isn't \opt{ngerman}.

(New to version 1.3.)
If the root language label is recognised by \sty{tracklang}, you
can add the \idx{ISO} codes using:
\cmddef{AddTrackedLanguageIsoCodes}

As from v1.3, you can also provide a modifier for a given
dialect using:
\cmddef{SetTrackedDialectModifier}
where \meta{dialect} is the dialect label and \meta{value}
is the modifier value. For example:
\begin{compactcodebox*}
\gls{AddTrackedDialect}\marg{oldgerman}\marg{\opt{german}}
\gls{AddTrackedLanguageIsoCodes}\marg{german}
\gls{SetTrackedDialectModifier}\marg{oldgerman}\marg{old}
\end{compactcodebox*}

Note that no sanitization is performed on \meta{value} when the
modifier is set explicitly through \gls{SetTrackedDialectModifier},
since it's assumed that any package that specifically sets the
modifier in this way is using a sensible labelling system. If the
modifier is obtained through commands like \gls{TrackLocale}, then
the modifier is sanitized as the value may have been obtained from
the operating system and there's no guarantee that it won't contain
problematic characters.

The \idx{modifier} is typically obtained by parsing locale information in
\idx{POSIX} format.
\begin{compactcodebox*}
\meta{language}[\idx{underscoresep}\meta{territory}][\idx{dotsep}\meta{codeset}][\idx{atmod}\meta{modifier}]
\end{compactcodebox*}
whereas the \idx{variant} is typically obtained by parsing the language
tag.

The information provided in the commands below (such as the script)
are typically obtained by parsing the language tag. For example,
with Serbian in the Latin alphabet the modifier would be \optfmt{latin}
whereas the script would be \opt{Latn}:
\begin{codebox*}
\gls{AddTrackedDialect}\marg{serbianlatin}\marg{\opt{serbian}}
\gls{AddTrackedLanguageIsoCodes}\marg{\opt{serbian}}
\gls{SetTrackedDialectModifier}\marg{serbianlatin}\marg{latin}
\gls{SetTrackedDialectScript}\marg{serbianlatin}\marg{\opt{Latn}}
\end{codebox*}

As from v1.3, you can provide a script (for example,
\opt{Latn} or \opt{Cyrl}) using:
\cmddef{SetTrackedDialectScript}
where \meta{dialect} is the dialect label and \meta{value} is the
\idxn{15924} alpha-4 script identifier. For example:
\begin{codebox*}
\gls{AddTrackedDialect}\marg{serbiancyrl}\marg{\opt{serbian}}
\gls{AddTrackedLanguageIsoCodes}\marg{serbian}
\gls{SetTrackedDialectScript}\marg{serbiancyrl}\marg{\opt{Cyrl}}
\end{codebox*}

As from v1.3, you can provide a variant for a given
dialect using:
\cmddef{SetTrackedDialectVariant}
For example:
\begin{codebox*}
\gls{AddTrackedDialect}\marg{german1901}\marg{german}
\gls{SetTrackedDialectVariant}\marg{german1901}\marg{1901}
\end{codebox*}

As from v1.3, you can also provide a sub-language using:
\cmddef{SetTrackedDialectSubLang}
where \meta{dialect} is the dialect label and \meta{value} is the
code. For example:
\begin{codebox*}
\gls{AddTrackedDialect}\marg{mandarin}\marg{\opt{chinese}}
\gls{AddTrackedLanguageIsoCodes}\marg{\opt{chinese}}
\gls{SetTrackedDialectSubLang}\marg{mandarin}\marg{cmn}
\gls{AddTrackedIsoLanguage}\marg{639-3}\marg{cmn}\marg{mandarin}
\end{codebox*}

As from v1.3, you can also provide additional information using:
\cmddef{SetTrackedDialectAdditional}
where \meta{dialect} is the dialect label and \meta{value} is the
additional information.

\section{Example (\filefmt{alien.sty})}
\label{sec:examplenewlang}

Suppose I want to create a language package \file{alien.sty} that defines the
\optfmt{martian} language with regional dialects
\optfmt{lowermartian} and \optfmt{uppermartian}. First, let's
suppose that \sty{tracklang} recognises the root language
\optfmt{martian}:
\begin{codebox}
\cmd{ProvidesPackage}\marg{alien}
\codepar
\gls{input}{tracklang}\comment{v1.3}
\codepar
\cmd{DeclareOption}\marg{martian}\marg{\comment{}
 \gls{TrackPredefinedDialect}\marg{martian}
}
\cmd{DeclareOption}\marg{lowermartian}\marg{\comment{}
 \gls{AddTrackedDialect}\marg{lowermartian}\marg{martian}
 \gls{AddTrackedLanguageIsoCodes}\marg{martian}
 \gls{AddTrackedIsoLanguage}\marg{3166-1}\marg{YY}\marg{lowermartian}
 \comment{other attributes such as}
 \comment{\gls{SetTrackedDialectVariant}\marg{lowermartian}\marg{...}}
}
\cmd{DeclareOption}\marg{uppermartian}\marg{\comment{}
 \gls{AddTrackedDialect}\marg{uppermartian}\marg{martian}
 \gls{AddTrackedLanguageIsoCodes}\marg{martian}
 \gls{AddTrackedIsoLanguage}\marg{3166-1}\marg{XX}\marg{uppermartian}
 \comment{other attributes such as}
 \comment{\gls{SetTrackedDialectVariant}\marg{uppermartian}\marg{...}}
}
\codepar
\cmd{ProcessOptions}
\codepar
\cmd{newcommand}*\marg{\gls{selectlanguage}}[1]\marg{\comment{}
 \cmd{def}\gls{languagename}\marg{\#1}\comment{}
 \comment{other stuff}
 \gls{SetCurrentTrackedDialect}\marg{\#1}\comment{} 
}
\codepar
\gls{AnyTrackedLanguages}
\marg{
 \gls{ForEachTrackedDialect}\marg{\cmd{thisdialect}}
 \marg{\comment{}
  \gls{TrackLangRequireDialect}\marg{alien}\marg{\cmd{thisdialect}}
 }
}
\end{codebox}
The caption commands and language set up are in the files
\localefile{alien} as in the examples from
\sectionref{sec:examples}. This allows for the user having already
loaded \sty{tracklang} before \sty{alien} and used \gls{TrackLangFromEnv} to pick up
the locale from the operating system's environment variables.
(For example, they may have \envvar{LANG} set to
\code{xx\idx{underscoresep}YY}.)

The resource files may need to set the mapping between the
\sty{tracklang} dialect label and the \sty{alien} dialect
label. For example, in \ldf{alien}{xx-YY}:
\begin{codebox*}
\gls{TrackLangProvidesResource}\marg{xx-YY}
\codepar
\gls{TrackLangRequireResource}\marg{martian}\comment{load common elements}
\codepar
\cmd{newcommand}\marg{\tklcaptions{lowermartian}}\marg{\comment{}
 \tklcaptions{martian}
 \cmd{def}\cmd{contentsname}\marg{X'flurp}\comment{regional variation}
}
\codepar
\gls{SetTrackedDialectLabelMap}\marg{\gls{CurrentTrackedDialect}}\marg{lowermartian}
\end{codebox*}

Now let's consider the case where \sty{tracklang} doesn't know
about the \optfmt{martian} language. In this case the user can't 
track the dialect until the root language has been defined, so the
user can't use \gls{TrackLangFromEnv} before using the \sty{alien}
package.

With \sty{tracklang} v1.3. The new root language can be defined
with a minor adjustment to the above code:
\begin{codebox*}[fontupper=\small\ttfamily]
\cmd{ProvidesPackage}\marg{alien}
\codepar
\gls{input}\marg{tracklang}\comment{needs v1.3}
\codepar
\gls{TrackLangIfKnownLang}\marg{martian}
\marg{\comment{tracklang already knows about the martian language}
}\comment{}
\marg{
 \comment{tracklang doesn't known about the martian language,}
 \comment{so define it}
 \comment{with \idxn{639-1} (xx) and \idxn{639-2} (xxx) codes:}
 \gls{TrackLangNewLanguage}\marg{martian}\marg{xx}\marg{xxx}\marg{}\marg{}\marg{}\marg{\opt{Latn}}
}
\end{codebox*}
The rest is as before.

Now other package writers who want to provide support
for the Martian dialects can easily detect which language options
the user requested through my package, \emph{without needing to know
anything about my \sty{alien} package}.

\part{Summaries}
\appendix

\chapter{Region and Script Mappings}
\label{sec:regscriptmappings}

Region mappings are listed in \tableref{tab:regionmappings}, and
script mappings are listed in \tableref{tab:scriptmappings}.

\printunsrttable[type=index,
 title={Region Mappings},other={alpha3},blocks=2,
 block-style={name-other-desc},label={tab:regionmappings},
 init={%
 \renewcommand{\glstableNameTarget}[1]{\inlineglsdef[optdef]{##1}}%
 \renewcommand{\glstableiffilter}[3]{\glsifcategory{##1}{region}{##3}{##2}}%
 \renewcommand{\glstablenameheader}{Alpha-2}%
 \renewcommand{\glstableotherheader}{Alpha-3}%
 \renewcommand{\glstabledescheader}{Numeric}%
 \renewcommand{\glstableDesc}{\numerictag}%
}
]

\printunsrttable[type=index,clearpage,par=ragged,
 title={Script Mappings},other=userii,blocks=1,
 block-style={name-symbol-other-desc},label={tab:scriptmappings},
 init={%
 \renewcommand{\glstableNameTarget}[1]{\inlineglsdef[optdef]{##1}}%
 \renewcommand{\glstableiffilter}[3]{\glsifcategory{##1}{script}{##3}{##2}}%
 \renewcommand{\glstablenameheader}{Alpha-2}%
 \renewcommand{\glstablesymbolheader}{Numeric}%
 \renewcommand{\glstableSymbol}{\numerictag}%
 \renewcommand{\glstableotherheader}{Direction}%
}
]

\backmatter
\printterms
\printsummary

\renewcommand{\fnregion}{}%
\glsdefpostname{isolangregion}{ (option)}%
\glsdefpostname{rootlang}{ (root language)}%
\glsdefpostname{isocode}{ (\idx{ISO} code)}%
\glsdefpostname{noniso}{ (option)}%
\glsdefpostname{region}{ (region)}%
\glsdefpostname{script}{ (script)}%
\glsdefpostname{application}{ (application)}%
\printuserguideindex 

\end{document}
