summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/translations/translations_en.tex
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/translations/translations_en.tex')
-rw-r--r--macros/latex/contrib/translations/translations_en.tex778
1 files changed, 778 insertions, 0 deletions
diff --git a/macros/latex/contrib/translations/translations_en.tex b/macros/latex/contrib/translations/translations_en.tex
new file mode 100644
index 0000000000..a39561bdc2
--- /dev/null
+++ b/macros/latex/contrib/translations/translations_en.tex
@@ -0,0 +1,778 @@
+% !arara: pdflatex: { shell: on }
+% !arara: biber
+% arara: pdflatex
+% arara: pdflatex
+% --------------------------------------------------------------------------
+% the TRANSLATIONS package
+%
+% internationalizations of LaTeX2e packages
+%
+% --------------------------------------------------------------------------
+% Clemens Niederberger
+% Web: https://github.com/cgnieder/translations
+% E-Mail: contact@mychemistry.eu
+% --------------------------------------------------------------------------
+% Copyright 2012-2017 Clemens Niederberger
+%
+% This work may be distributed and/or modified under the
+% conditions of the LaTeX Project Public License, either version 1.3
+% of this license or (at your option) any later version.
+% The latest version of this license is in
+% http://www.latex-project.org/lppl.txt
+% and version 1.3 or later is part of all distributions of LaTeX
+% version 2005/12/01 or later.
+%
+% This work has the LPPL maintenance status `maintained'.
+%
+% The Current Maintainer of this work is Clemens Niederberger.
+% --------------------------------------------------------------------------
+% The translations package is part of the exsheets bundle
+% --------------------------------------------------------------------------
+% If you have any ideas, questions, suggestions or bugs to report, please
+% feel free to contact me.
+% --------------------------------------------------------------------------
+\documentclass[load-preamble+,french,spanish,ngerman,english]{cnltx-doc}
+% ----------------------------------------------------------------------------
+% document layout and typographic features
+\setcnltx{
+ package = {translations} ,
+ authors = Clemens Niederberger ,
+ email = contact@mychemistry.eu ,
+ url = https://github.com/cgnieder/translations ,
+ info = {Internationalization of \LaTeXe\ Packages} ,
+ add-cmds = {
+ baselanguage,
+ DeclareDictTranslation,
+ DeclareLanguage,
+ DeclareLanguageAlias,
+ DeclareLanguageDialect,
+ DeclareTranslation,
+ declaretranslation,
+ DeclareTranslationFallback,
+ declaretranslationfallback,
+ GetTranslation,
+ GetTranslationFor,
+ IfTranslation,
+ LoadDictionary,
+ LoadDictionaryFor,
+ NewTranslation,
+ definetranslation,
+ NewTranslationFallback,
+ definetranslationfallback,
+ ProvideDictionaryFor,
+ ProvideDictTranslation,
+ ProvideTranslation,
+ addtranslation,
+ ProvideTranslationFallback,
+ addtranslationfallback,
+ RenewTranslation,
+ redefinetranslation,
+ RenewTranslationFallback,
+ redefinetranslationfallback,
+ SaveTranslation,
+ SaveTranslationFor
+ } ,
+ add-silent-cmds = {
+ cuisine,kitchen,mypackage@title
+ } ,
+ makeindex-setup = {options={-s cnltx.ist},columns=3,columnsep=1em} ,
+ index-setup = {othercode=\footnotesize,level=\addsec,noclearpage}
+}
+
+\microtypesetup{tracking=scshape}
+
+\defbibheading{bibliography}[\bibname]{\addsec{#1}}
+
+\usepackage{csquotes}
+
+\usepackage{embrac}[2012/06/29]
+ \ChangeEmph{[}[,.02em]{]}[.055em,-.08em]
+ \ChangeEmph{(}[-.01em,.04em]{)}[.04em,-.05em]
+
+% ----------------------------------------------------------------------------
+% other packages, bibliography, index
+\usepackage{array,longtable,booktabs}
+\AfterPackage!{hyperref}{\usepackage[sort]{cleveref}}
+
+% ----------------------------------------------------------------------------
+% example definitions that have to be done in the preamble:
+\DeclareTranslation{English}{Kueche}{kitchen}
+\DeclareTranslation{German}{Kueche}{K\"uche}
+\DeclareTranslation{Spanish}{Kueche}{cocina}
+\DeclareTranslation{French}{Kueche}{cuisine}
+\DeclareTranslation{English}{farbe}{color}
+\DeclareTranslation{British}{farbe}{colour}
+\LoadDictionaryFor{German}{translations-basic-dictionary}
+
+% ----------------------------------------------------------------------------
+\usepackage{bbding}
+
+\newrobustcmd\fnote[1]{\textsuperscript{#1}}
+
+\begin{document}
+
+\section{Motivation}
+This package provides means for package authors to have an easy interface for
+internationalization of their packages. The functionality of this package is
+in many parts also covered by the package
+\pkg{translator}~\cite{pkg:translator} (part of the \pkg*{beamer} bundle).
+Internationalization is also possible with \pkg{babel}~\cite{pkg:babel} and
+it's \cs*{addto}\cs*{captions\meta{language}} mechanism or \KOMAScript's
+\cs*{providecaptionname} and similar commands. However, I believe that
+\translations\ is more flexible than all of these. Unlike \pkg{translator} it
+detects the used (\pkg{babel} or \pkg{polyglossia}~\cite{pkg:polyglossia})
+language itself and provides expandable retrieving of the translated key.
+\translations\ also provides support for language dialects which means package
+authors can for example distinguish between British, Australian, Canadian and
+US~English.
+
+The first draft of the package was written since I missed an expandable
+version of \pkg{translator}'s \cs*{translate} command. Once I had the
+package available I began using it in various of my other packages so it got
+extended to the needs I faced there.
+
+
+\section{License and Requirements}\label{sec:license}
+\license
+
+\translations\ requires the packages \pkg{etoolbox}~\cite{pkg:etoolbox} and
+\pkg{scrlfile} (part of the \KOMAScript\ bundle~\cite{bnd:koma-script}).
+
+
+\section{Usage}
+\subsection{Background}
+The \translations\ package enables the author of a package or a class (or a
+document) to declare translations of key words in different languages and
+fetch these translations in the document depending on the active language as
+set by \pkg{babel} or \pkg{polyglossia}. Since \translations\ checks which
+language is active it is generally not necessary (although possible) to
+specify the language for which a translation should be fetched manually.
+
+\translations\ knows of three types of languages: main languages (see
+\cref{tab:languages} on \cpageref{tab:languages}), language dialects (see
+\cref{tab:dialects} on \cpageref{tab:dialects}), and language aliases (see
+\cref{tab:aliases} on \cpageref{tab:aliases}). For the commands declaring or
+fetching a translation base languages and language aliases are equivalent.
+Dialects are similar to aliases but there are important differences. An alias
+can for example be an alias of a dialect.
+
+\Cref{fig:scheme} shows what happens if \translations\ is asked to fetch a
+translation for a given key.
+
+\begin{figure}[htbp]
+ \centering
+ \newlength\nodewidth
+ \setlength\nodewidth{.375\linewidth}
+ \newcommand*\yes{\centering\textcolor{green}{\CheckmarkBold}\par}
+ \renewcommand*\no{\centering\textcolor{red}{\XSolidBrush}\par}
+ \begin{tikzpicture}
+ [
+ level/.style={sibling distance=.5\linewidth/#1},
+ every node/.style={
+ draw,
+ rounded corners=3pt,
+ align=left,
+ anchor=north,
+ font=\small\sffamily
+ }
+ ]
+ \node {check if any\fnote{a} translation is defined in given language}
+ child {
+ node[text width=\nodewidth]
+ {\yes check if language is a dialect}
+ child {
+ node[text width=\nodewidth/2]
+ {\yes check if dialect translation is given}
+ child {
+ node[text width=\nodewidth/2.75]
+ {\yes use dialect translation}
+ }
+ child {
+ node[text width=\nodewidth/2.75]
+ {\no use lan\-guage\fnote{b} translation}
+ }
+ }
+ child {
+ node[text width=\nodewidth/2]
+ {\no use translation}}
+ }
+ child {
+ node[text width=\nodewidth]
+ {\no check if fallback translation is given}
+ child {
+ node[text width=\nodewidth/2.75]
+ {\yes use fallback translation}
+ }
+ child {
+ node[text width=\nodewidth/2.75]
+ {\no use literal key}
+ }
+ } ;
+ \end{tikzpicture}
+ \caption{Schematic representation of \translations' translating
+ mechansim. Notes: \fnote{a} except for a possible fallback
+ translation. \fnote{b} \ie, the base language of the dialect.}
+ \label{fig:scheme}
+\end{figure}
+
+What happens if you declare a translation? There are four cases:
+\begin{enumerate}
+ \item You declare a translation for a base language: this is the normal case
+ where an internal macro is defined which can be fetched by the
+ \cs{GetTranslation} command (see \cref{ssec:commands}).
+ \item You declare a translation for a language alias: this is the very same
+ as the first case since the same internal macro is defined.
+ \item You declare a translation for a dialect: this is two-fold. Either a
+ translation for the base language exists so only the translation for the
+ dialect is saved. If the translation for the base language does not exist
+ it is defined to be the same as the one for the dialect.
+ \item You declare a translation for an alias of a dialect: this is the very
+ same as the third case as again the internal macros are the same.
+\end{enumerate}
+
+\emph{Beware that if the current language is a language using a non-latin
+ font, a translation is missing for said language, and the fallback
+ translation needs a Latin script font then \emph{nothing} might be printed.}
+
+\subsection{Available Commands}\label{ssec:commands}
+Below the commands provided by \translations\ are explained. The symbol
+\textcolor{expandable}{\expandablesign} means that the command is expandable.
+Commands without the marker aren't expandable.
+
+\begin{commands}
+ \command{DeclareLanguage}[\marg{lang}]
+ Declare a language that can be used by \translations. If the language
+ already exists it will be silently redefined. This command can only be
+ used in the preamble. It should never be necessary to use this command as
+ \translations\ already declares loads of languages (\cref{sec:languages}).
+ Should you miss one please send me an email and I'll add it to
+ \translations.
+ \command{DeclareLanguageAlias}[\marg{lang2}\marg{lang1}]
+ Declares \meta{lang2} to be an alias of \meta{lang1}. If \meta{lang1}
+ doesn't exist yet a warning will be raised and it will be defined. This
+ command can only be used in the preamble. It should never be necessary to
+ use this command as \translations\ already declares loads of languages
+ (\cref{sec:languages}). Should you miss one please send me an email and
+ I'll add it to \translations.
+ \command{DeclareLanguageDialect}[\marg{dialect}\marg{lang}]
+ Declares \meta{dialect} to be a dialect of language \meta{lang}. If a
+ translation for \meta{dialect} is provided it is used by the translation
+ macros. If there is none the corresponding translation for \meta{lang}
+ is used instead. It should never be necessary to use this command as
+ \translations\ already declares loads of languages (\cref{sec:languages}).
+ Should you miss one please send me an email and I'll add it to
+ \translations.
+ \command{NewTranslation}[\marg{lang}\marg{key}\marg{translation}]
+ Defines a translation of key \meta{key} for the language \meta{lang}.
+ An error will be raised if a translation of \meta{key} in language
+ \marg{lang} already exists. This command can only be used in the
+ preamble.
+ \command{NewTranslationFallback}[\marg{key}\marg{translation}]
+ \sinceversion{1.4}Defines a fallback translation of key \meta{key} for the
+ language \meta{lang}. An error will be raised if a fallback translation of
+ \meta{key} already exists. This command can only be used in the preamble.
+ \command{RenewTranslation}[\marg{lang}\marg{key}\marg{translation}]
+ Redefines a translation of key \meta{key} for the language \meta{lang}.
+ An error will be raised if no translation of \meta{key} in language
+ \meta{lang} exists. This command can only be used in the preamble.
+ \command{RenewTranslationFallback}[\marg{key}\marg{translation}]
+ \sinceversion{1.4}Renews a fallback translation. This command can only be
+ used in the preamble.
+ \command{ProvideTranslation}[\marg{lang}\marg{key}\marg{translation}]
+ \sinceversion{1.2}Provides a translation of key \meta{key} for the
+ language \meta{lang}. If a translation of \meta{key} in language
+ \meta{lang} already exists it won't be overwritten and no error will be
+ raised. This command can only be used in the preamble.
+ \command{ProvideTranslationFallback}[\marg{key}\marg{translation}]
+ \sinceversion{1.4}Provides a fallback translation. This command can only
+ be used in the preamble.
+ \command{DeclareTranslation}[\marg{lang}\marg{key}\marg{translation}]
+ Defines a translation of key \meta{key} for the language \meta{lang}.
+ No error will be raised if a translation of \meta{key} already exists.
+ This command can only be used in the preamble.
+ \command{DeclareTranslationFallback}[\marg{key}\marg{fallback}]
+ Declares a fallback translation. This command can only be used in the
+ preamble.
+ \command{definetranslation}[\marg{lang}\marg{key}\marg{translation}]
+ \sinceversion{1.4}A version of \cs{NewTranslation} that \emph{can} be used
+ after begin document.
+ \command{definetranslationfallback}[\marg{key}\marg{translation}]
+ \sinceversion{1.4}A version of \cs{NewTranslationFallback} that \emph{can}
+ be used after begin document.
+ \command{redefinetranslation}[\marg{lang}\marg{key}\marg{translation}]
+ \sinceversion{1.4}A version of \cs{RenewTranslation} that \emph{can} be
+ used after begin document.
+ \command{redefinetranslationfallback}[\marg{key}\marg{translation}]
+ \sinceversion{1.4}A version of \cs{RenewTranslationFallback} that
+ \emph{can} be used after begin document.
+ \command{addtranslation}[\marg{lang}\marg{key}\marg{translation}]
+ \sinceversion{1.4}A version of \cs{ProvideTranslation} that \emph{can} be
+ used after begin document.
+ \command{addtranslationfallback}[\marg{key}\marg{translation}]
+ \sinceversion{1.4}A version of \cs{ProvideTranslationFallback} that
+ \emph{can} be used after begin document.
+ \command{declaretranslation}[\marg{lang}\marg{key}\marg{translation}]
+ \sinceversion{1.4}A version of \cs{DeclareTranslation} that \emph{can} be
+ used after begin document.
+ \command{declaretranslationfallback}[\marg{key}\marg{translation}]
+ \sinceversion{1.4}A version of \cs{DeclareTranslationFallback} that
+ \emph{can} be used after begin document.
+ \expandable\command{IfTranslation}[\marg{lang}\marg{key}\marg{true}\marg{false}]
+ Checks\sinceversion{1.2d} if a translation for \meta{key} in language
+ \meta{lang} is defined or not and either leaves \meta{true} or
+ \meta{false} in the input stream.
+ \expandable\command{GetTranslationFor}[\marg{lang}\marg{key}]
+ Fetches and prints the translation of \meta{key} for the language
+ \meta{lang}. This command is expandable.
+ \expandable\command{GetTranslation}[\marg{key}]
+ Fetches and prints the translation of \meta{key} for the currently active
+ language (as for example set by \pkg{babel}). This command is expandable.
+ \expandable\command{GetLCTranslationFor}[\marg{lang}\marg{key}]
+ \sinceversion{1.1}Fetches and prints the translation of \meta{key} for
+ the language \meta{lang}. This command ensures that the fetched
+ translation is set lowercase. This command is expandable (well, sort
+ of: in an \cs*{edef} it leaves \cs*{lowercase}\marg{translation} in the
+ input stream where \meta{translation} is what \cs{GetTranslationFor} would
+ expand to).
+ \expandable\command{GetLCTranslation}[\marg{key}]
+ \sinceversion{1.1}Fetches and prints the translation of \meta{key} for
+ the currently active language (as for example set by \pkg{babel}). This
+ command ensures that the fetched translation is set lowercase. This
+ command is expandable (well, sort of: in an \cs*{edef} it leaves
+ \cs*{lowercase}\marg{translation} in the input stream where
+ \meta{translation} is what \cs{GetTranslation} would expand to).
+ \command{GetTranslationForWarn}[\marg{lang}\marg{key}]
+ \sinceversion{1.0}Fetches and prints the translation of \meta{key} for
+ the language \meta{lang}. Issues a warning if no translation is
+ available at the cost of expandability.
+ \command{GetTranslationWarn}[\marg{key}]
+ \sinceversion{1.0}Fetches and prints the translation of \meta{key} for
+ the currently active language (as for example set by \pkg{babel}).
+ Issues a warning if no translation is available at the cost of
+ expandability.
+ \command{GetLCTranslationForWarn}[\marg{lang}\marg{key}]
+ \sinceversion{1.1}Fetches and prints the translation of \meta{key} for
+ the language \meta{lang}. This command ensures that the fetched
+ translation is set lowercase. Issues a warning if no translation is
+ available at the cost of expandability.
+ \command{GetLCTranslationWarn}[\marg{key}]
+ \sinceversion{1.1}Fetches and prints the translation of \meta{key} for
+ the currently active language (as for example set by \pkg{babel}). This
+ command ensures that the fetched translation is set lowercase. Issues a
+ warning if no translation is available at the cost of expandability.
+ \command{SaveTranslationFor}[\marg{cmd}\marg{lang}\marg{key}]
+ Fetches and saves the translation of \meta{key} for the language
+ \meta{lang} in the macro \meta{cmd}.
+ \command{SaveTranslation}[\marg{cmd}\marg{key}]
+ Fetches and saves the translation of \meta{key} for the currently active
+ language (as for example set by \pkg{babel}) in the macro \meta{cmd}.
+ \command{LoadDictionary}[\marg{name}]
+ Loads a file named \code{\meta{name}-\meta{lang}.trsl} where \meta{lang}
+ corresponds to the lowercase name of the current language as defined with
+ \cs{DeclareLanguage}. This file should contain the translations for the
+ specified language.
+ \command{LoadDictionaryFor}[\marg{lang}\marg{name}]
+ Loads a file named \code{\meta{name}-\meta{lang}.trsl}.
+ \command{NewDictTranslation}[\marg{key}\marg{translation}]
+ \sinceversion{0.10}This command is to be used in a dictionary file and
+ picks up the language of that file. Issues an error if either the
+ translation for the \meta{key} or the dictionary entry for the \meta{key}
+ already exists.
+ \command{RenewDictTranslation}[\marg{key}\marg{translation}]
+ \sinceversion{0.10}This command is to be used in a dictionary file and
+ picks up the language of that file. Issues an error if either the
+ translation for the \meta{key} or the dictionary entry for the \meta{key}
+ doesn't exist.
+ \command{ProvideDictTranslation}[\marg{key}\marg{translation}]
+ \sinceversion{0.10}This command is to be used in a dictionary file and
+ picks up the language of that file. Only defines the translation and adds
+ a corresponding dictionary entry if they don't exist yet. This command is
+ used in the dictionaries that a part of \translations.
+ \command{DeclareDictTranslation}[\marg{key}\marg{translation}]
+ This command is to be used in a dictionary file and picks up the language
+ of that file, see \cref{sec:dictionaries} for an example. Defines the
+ translation and adds a dictionary entry regardless if they exist or not.
+ \command{ProvideDictionaryFor}[\marg{lang}\marg{name}\oarg{date}]
+ Needs to be in a dictionary file. This command tells \translations\ that
+ the file indeed is a dictionary and also sets the language for the
+ dictionary which is used by \cs{DeclareDictTranslation}.
+ \expandable\command{PrintDictionaryFor}%
+ [\marg{lang}\marg{name}\marg{pre}\marg{mid}\marg{post}]
+ \sinceversion{1.0}Prints all entries of dictionary \meta{name} in
+ language \meta{lang} in the order the entries have been declared. For
+ every entry the code\par
+ \meta{pre}\meta{key}\meta{mid}\meta{translation}\meta{post}\par
+ is printed. The dictionary must have been loaded of course. There is
+ probably only a very limited number of use cases for this command. (It
+ was for example used to print \cref{tab:dict}.)
+ \expandable\command{baselanguage}[\marg{lang}]
+ \changedversion{1.2a}Returns the (internal) base name of the given language,
+ language alias or language dialect. For a dialect this expands to the
+ name of language it is a dialect of. For a base language (see
+ section~\ref{ssec:languages:base}) this usually simply is the lowercase
+ version of the name.\par
+ \verbcode+\baselanguage{English}+ $\Rightarrow$ \code{english}\\
+ \verbcode+\baselanguage{American}+ $\Rightarrow$ \code{english}
+ \expandable\command{ifcurrentlanguage}[\marg{lang}\marg{true}\marg{false}]
+ \sinceversion{1.2}Places \meta{true} in the input stream if the current
+ language is \meta{lang}. Note: a dialect counts as a language of it's own
+ here. \cs{ifcurrentlanguage}\Marg{English} will for example be
+ \meta{false} if the current \pkg{babel} language is \code{american}.
+ \expandable\command{ifcurrentbaselanguage}[\marg{lang}\marg{true}\marg{false}]
+ \sinceversion{1.2}Places \meta{true} in the input stream if the current
+ language is \meta{lang}. Note: a dialect does notcount as a language of
+ it's own here. If the current \pkg{babel} language is \code{american}
+ then \cs{ifcurrentbaselanguage}\Marg{English} will be \meta{true}.
+\end{commands}
+
+\subsection{A Small Example}
+This section demonstrates with two short examples how the macros are used.
+The first example covers the basics: declaring of translations and then
+retrieving and typesetting them.
+
+\begin{example}
+ % in the preamble:
+ % \DeclareTranslation{English}{Kueche}{kitchen}
+ % \DeclareTranslation{German}{Kueche}{K\"uche}
+ % \DeclareTranslation{Spanish}{Kueche}{cocina}
+ % \DeclareTranslation{French}{Kueche}{cuisine}
+
+ \GetTranslation{Kueche}
+ \SaveTranslation\kitchen{Kueche}
+ \SaveTranslationFor\cuisine{french}{Kueche}
+
+ \selectlanguage{ngerman}
+ \GetTranslation{Kueche} \kitchen\ \GetTranslationFor{spanish}{Kueche}
+ \cuisine
+
+ \IfTranslation{German}{Kueche}{true}{false} \par
+ \IfTranslation{Danish}{Kueche}{true}{false}
+\end{example}
+
+The next example demonstrates the use of dialects and how they fall back to
+the translation for the main language if no extra translation was declared:
+
+\begin{example}
+ % in the preamble:
+ % \DeclareTranslation{English}{farbe}{color}
+ % \DeclareTranslation{British}{farbe}{colour}
+
+ \GetTranslationFor{English}{farbe}
+ \GetTranslationFor{British}{farbe}
+ \GetTranslationFor{American}{farbe}
+\end{example}
+
+\subsection{Usage in Packages}
+\subsubsection{Basic Structure}
+A typical usage in a package would look as follows:
+\begin{sourcecode}
+ \RequirePackage{translations}
+ \DeclareTranslationFallback{mypackage-title}{Nice Title}
+ \DeclareTranslation{English}{mypackage-title}{Nice Title}
+ \DeclareTranslation{French}{mypackage-title}{Beau Titre}
+ \DeclareTranslation{German}{mypackage-title}{Sch\"{o}ner Titel}
+ ...
+ \newcommand*\mypackage@title{\GetTranslation{mypackage-title}}
+\end{sourcecode}
+
+That is, a package defines some unique key for an expression and at least
+defines a fallback translation. Additionally translations for as many
+languages as the author wants are defined. A user then may add
+\cs{DeclareTranslation}\marg{language}\marg{translation} if they find their
+translation missing.
+
+\subsubsection{The `fallback' language}
+If a user has neither loaded \pkg{babel} nor \pkg{polyglossia} \translations\
+will use English as language and translate to English if the translation was
+provided. If the user \emph{has} loaded one of the language packages but has
+chosen a language for which no translation is defined the language `fallback'
+will be used, \ie, the translation provided with
+\cs{DeclareTranslationFallback}. If no fallback translation is provided
+either the translation will expand to the literal string.
+
+The following three examples should make this concept clear:
+
+\begin{example}[compile]
+ \documentclass[margin=5mm]{standalone}
+ \usepackage{translations}
+ \DeclareTranslation{German}{foo-literal}{foo-german}
+ \begin{document}
+ \GetTranslation{foo-literal} % foo-literal
+ \end{document}
+\end{example}
+
+\begin{example}[compile]
+ \documentclass[margin=5mm]{standalone}
+ \usepackage{translations}
+ \DeclareTranslationFallback{foo-literal}{foo}
+ \DeclareTranslation{German}{foo-literal}{foo-german}
+ \begin{document}
+ \GetTranslation{foo-literal} % foo
+ \end{document}
+\end{example}
+
+\begin{example}[compile]
+ \documentclass[margin=5mm]{standalone}
+ \usepackage[ngerman]{babel}
+ \usepackage{translations}
+ \DeclareTranslationFallback{foo-literal}{foo}
+ \DeclareTranslation{German}{foo-literal}{foo-german}
+ \begin{document}
+ \GetTranslation{foo-literal} % foo-german
+ \end{document}
+\end{example}
+
+\subsection{Dictionaries}\label{sec:dictionaries}
+\subsubsection{Background}
+\translations\ provides the means to write dictionary files that can be loaded
+by packages or in a document. Dictionaries can be loaded for the currently
+active language with \cs{LoadDictionary} or for a specific language with
+\cs{LoadDictionaryFor}.
+
+\begin{commands}
+ \command{LoadDictionary}[\marg{name}]
+ Loads a file named \code{\meta{name}-\meta{lang}.trsl} where \meta{lang}
+ corresponds to the lowercase name of the current language or base language
+ as defined with \cs{DeclareLanguage}. This file should contain the
+ translations for the specified language. This means if \meta{lang} is a
+ dialect and a dictionary exists the dictionary is used. If it doesn't
+ exist but there is a dictionary for the base language that one is used.
+ \command{LoadDictionaryFor}[\marg{lang}\marg{name}]
+ Loads a file named \code{\meta{name}-\meta{lang}.trsl} where \meta{lang}
+ corresponds to the lowercase name of the current language or base language
+ as defined with \cs{DeclareLanguage}. This file should contain the
+ translations for the specified language. This means if \meta{lang} is a
+ dialect and a dictionary exists the dictionary is used. If it doesn't
+ exist but there is a dictionary for the base language that one is used.
+ \command{LoadDictionaryForDialect}[\marg{lang}\marg{name}]
+ \sinceversion{1.3}Loads a file named \code{\meta{name}-\meta{lang}.trsl}
+ where \meta{lang} corresponds to the lowercase name of the current
+ language as defined with \cs{DeclareLanguage}. This file should contain
+ the translations for the specified language. This command \emph{does not
+ look} for a base language dictionary.
+\end{commands}
+
+A package could provide dictionary files for its language dependent settings
+and include the needed one at begin document. The basics for creating a
+dictionary file are explained in section~\ref{sec:own-dictionaries}.
+
+\translations\ already provides a few basic dictionary files. If the main
+document language fits to one of the provided files the corresponding basic
+dictionary is loaded at begin document by \translations, see
+section~\ref{sec:transl-basic-dict} for more on this.
+
+\subsubsection{Own Dictionaries}\label{sec:own-dictionaries}
+A typical dictionary file should look as follows:
+\begin{sourcecode}
+ % this is file housing-german.trsl
+ \ProvideDictionaryFor{German}{housing}[<version info>]
+ \ProvideDictTranslation{kitchen (housing)}{K\"uche}
+ \ProvideDictTranslation{bathroom (housing)}{Bad}
+ \ProvideDictTranslation{living room (housing)}{Wohnzimmer}
+ \ProvideDictTranslation{bedroom (housing)}{Schlafzimmer}
+ ...
+ \endinput
+\end{sourcecode}
+
+The usage is similar to the one in a package: unique keys are given
+translations, this time for the language the dictionary file is declared for
+only. Translations can be declared by one of the following commands:
+\begin{commands}
+ \command{NewDictTranslation}[\marg{key}\marg{translation}]
+ \sinceversion{0.10}This command is to be used in a dictionary file and
+ picks up the language of that file. Issues an error if either the
+ translation for the \meta{key} or the dictionary entry for the \meta{key}
+ already exists.
+ \command{RenewDictTranslation}[\marg{key}\marg{translation}]
+ \sinceversion{0.10}This command is to be used in a dictionary file and
+ picks up the language of that file. Issues an error if either the
+ translation for the \meta{key} or the dictionary entry for the \meta{key}
+ doesn't exist.
+ \command{ProvideDictTranslation}[\marg{key}\marg{translation}]
+ \sinceversion{0.10}This command is to be used in a dictionary file and
+ picks up the language of that file. Only defines the translation and adds
+ a corresponding dictionary entry if they don't exist yet. This command is
+ used in the dictionaries that a part of \translations.
+ \command{DeclareDictTranslation}[\marg{key}\marg{translation}]
+ This command is to be used in a dictionary file and picks up the language
+ of that file, see \cref{sec:dictionaries} for an example. Defines the
+ translation and adds a dictionary entry regardless if they exist or not.
+\end{commands}
+
+Every dictionary file \emph{must} contain the declaration
+\cs{ProvideDictionaryFor}:
+\begin{commands}
+ \command{ProvideDictionaryFor}[\marg{lang}\marg{name}\oarg{date}]
+ Needs to be in a dictionary file. This command tells \translations\ that
+ the file indeed is a dictionary and also sets the language for the
+ dictionary which is used by \cs{NewDictTranslation} or similar commands.
+\end{commands}
+
+\subsubsection{\translations' Basic Dictionaries}\label{sec:transl-basic-dict}
+\translations\ already provides a basic dictionary for the languages
+\begin{itemize}
+ \item Catalan,
+ \item English,
+ \item Dutch,
+ \item French,
+ \item German, and
+ \item Spanish.
+\end{itemize}
+The corresponding dictionary is loaded automatically if the document language
+is one of these languages. If you'd like to contribute and add the basic
+dictionary in your language this is more than welcome and highly appreciated!
+The easiest way to do this would be to copy one of the existing files
+\code{translations-basic-dictionary-\meta{lang}.trsl} and modify the file
+accordingly. You can then send me the file via email and I'll add it to
+\translations.
+
+\Cref{tab:dict} lists all words provided by the basic dictionary for German.
+
+\begin{longtable}{ll}
+ \caption{All entries of \translations' basic dictionary in German.\label{tab:dict}} \\
+ \toprule
+ \rmfamily\bfseries key & \bfseries translation \\
+ \midrule
+ \endfirsthead
+ \toprule
+ \rmfamily\bfseries key & \bfseries translation \\
+ \midrule
+ \endhead
+ \bottomrule
+ \endlastfoot
+ \midrule
+ & \hfill\emph{continues} \\
+ \endfoot
+ \PrintDictionaryFor{German}{translations-basic-dictionary}{\ttfamily}{&}{\\}
+\end{longtable}
+
+
+\section{Defined Languages}\label{sec:languages}
+\subsection{Base Languages}\label{ssec:languages:base}
+Quite a number of languages already are defined, either directly or via an
+alias. So, before you define a language you should take a look at the tables
+below if the language doesn't already exist. \Cref{tab:languages} lists all
+base languages, ``fallback'' being a dummy language used for fallback
+translations. \Cref{tab:languages,tab:dialects,tab:aliases} list \emph{all}
+language names known to \translations. However, they're not sorted
+alphabetically but listed in the order they have been defined. I tried to
+make the definitions in an alphabetical order but sometimes rather grouped
+related language names together.
+
+If you miss a language or recognize a language that has falsely been declared
+as an alias but should rather be a dialect or base language itself (or any
+variation of this theme) please let me know, preferably with a short
+explanation what's wrong and why.
+
+\newcounter{column}
+\def\seplang{%
+ \stepcounter{column}%
+ \ifnumless{\value{column}}{5}
+ {&}
+ {\\\setcounter{column}{0}}%
+}
+\def\do#1{#1\seplang}
+\makeatletter
+\begin{longtable}{lllll}
+ \caption{Base languages defined by \translations, from left to right in
+ the order of definition.\label{tab:languages}} \\
+ \toprule
+ \endfirsthead
+ \toprule
+ \endhead
+ \bottomrule
+ \endlastfoot
+ \midrule
+ &&&& \hfill\emph{continues} \\
+ \endfoot
+ \dolistloop\@trnslt@languages
+\end{longtable}
+\makeatother
+
+\subsection{Language Dialects}\label{ssec:languages:dialects}
+\translations\ also defines a few dialects of thebase languages. They are
+listed in \cref{tab:dialects}. The decision what is a dialect and what is an
+alias is not always clear. I am no linguist so I looked up information
+available on the internet. A language that was described as
+\enquote{standardized register} was always defined as a dialect. For some
+other languages it seemed to make sense, such as British or Austrian. The
+decisions are open for debate.
+
+\setcounter{column}{0}
+\gdef\seplang{%
+ \ifnumgreater{\value{column}}{3}
+ {\setcounter{column}{1}}
+ {\stepcounter{column}}%
+ \ifnumless{\value{column}}{4}
+ {&}
+ {\\}%
+}
+\def\aliases#1#2{#1\seplang #2\seplang}
+\def\do#1{\aliases#1}
+\makeatletter
+\begin{longtable}{ll@{\hspace*{4em}}ll}
+ \caption{All dialects defined by \translations, from left to right in the
+ order of definition.\label{tab:dialects}}\\
+ \toprule
+ \bfseries dialect & \bfseries language &
+ \bfseries dialect & \bfseries language \\
+ \midrule
+ \endfirsthead
+ \toprule
+ \bfseries dialect & \bfseries language &
+ \bfseries dialect & \bfseries language \\
+ \midrule
+ \endhead
+ \bottomrule
+ \endlastfoot
+ \midrule
+ &&& \hfill\emph{continues} \\
+ \endfoot
+ \dolistloop\@trnslt@dialects@pair
+\end{longtable}
+\makeatother
+
+\subsection{Language Aliases}\label{ssec:languages:aliases}
+To most of the base languages and dialects at least one alias exists, the
+uppercase variant. This is due to the fact that it is common to write
+language names uppercased. For a number of languages aliases were defined in
+order to match \pkg{babel}'s or \pkg{polyglossia}'s names for the
+languages. Others are defined because there apparently exist more than one
+name for the same language. The decisions are not consistent. For example it
+could be argued that \enquote{deutsch} is an alias of \enquote{German}. I am
+open to suggestions and improvements. All defined aliases are listed in
+\cref{tab:aliases}.
+
+\setcounter{column}{0}
+\makeatletter
+\begin{longtable}{ll@{\hspace*{4em}}ll}
+ \caption{All language aliases defined by \translations, from left to right
+ in the order of definition.\label{tab:aliases}}\\
+ \toprule
+ \bfseries alias & \bfseries language &
+ \bfseries alias & \bfseries language \\
+ \midrule
+ \endfirsthead
+ \toprule
+ \bfseries alias & \bfseries language &
+ \bfseries alias & \bfseries language \\
+ \midrule
+ \endhead
+ \bottomrule
+ \endlastfoot
+ \midrule
+ &&& \hfill\emph{continues} \\
+ \endfoot
+ \dolistloop\@trnslt@aliases@pair
+\end{longtable}
+\makeatother
+
+These languages \emph{should} cover all languages which are currently covered
+by \pkg{babel} and \pkg{polyglossia} but very likely this is not the
+case. Should you miss a language please send me an email so I can add it to
+\translations.
+
+% \section{Implementation}
+% \lstinputlisting[style=cnltx]{translations.sty}
+
+\end{document}