path: root/macros/latex/contrib/translator/translator.tex

% Copyright 2007 by Till Tantau
% Copyright 2010 by Vedran Mileti\'c
% Copyright 2013,2015 by Vedran Mileti\'c, Joseph Wright
% Copyright 2017 Joseph Wright
%
% This file may be distributed and/or modified
%
% 1. under the LaTeX Project Public License and/or
% 2. under the GNU Public License.
%
% See the documentation file for more details.

\documentclass{ltxdoc}

% The next line is needed so that \GetFileInfo will be able to pick up
% version data.
\usepackage{translator}

\usepackage{csquotes}

\usepackage{xparse}
\NewDocumentCommand{\pkg}{m}{\textsf{#1}}
\newbox{\syntaxbox}
\NewDocumentEnvironment{syntax}{}
  {\begin{lrbox}{\syntaxbox}}
  {%
    \end{lrbox}%
    \noindent
    \usebox{\syntaxbox}\\
  }
\usepackage{hypdoc}

\begin{document}

\GetFileInfo{translator.sty}

\title{%
  \pkg{translator} -- Easy translation of strings in LaTeX%
  \thanks{This file describes \fileversion,
    last revised \filedate.}%
}

\author{%
  Joseph Wright%
  \thanks{%
    E-mail:
    \href{mailto:joseph.wright@morningstar2.co.uk}
      {joseph.wright@morningstar2.co.uk}%
  }%
}

\date{Released \filedate}

\maketitle

\tableofcontents

\section{Translating Strings}

\subsection{Introduction}

The \pkg{translator} package is a \LaTeX{} package that provides a flexible
mechanism for translating individual words into different languages. For
example, it can be used to translate a word like \enquote{figure} into, say,
the German word \enquote{Abbildung}. Such a translation mechanism is useful
when the author of some package would like to localize the package such that
texts are correctly translated into the language preferred by the user. The
\pkg{translator} package is \emph{not} intended to be used to automatically
translate more than a few words.

You may wonder whether the \pkg{translator} package is really necessary since
there is the (very nice) \pkg{babel} package available for \LaTeX{}. This
package already provides translations for words like \enquote{figure}.
Unfortunately, the architecture of the \pkg{babel} package was designed in such
a way that there is no way of adding translations of new words to the (very
short) list of translations directly built into \pkg{babel}.

The \pkg{translator} package was specifically designed to allow an easy
extension of the vocabulary. It is both possible to add new words that should
be translated and translations of these words.

The \pkg{translator} package can be used together with \pkg{babel}. In this
case, babel is used for language-specific things like special quotation marks
and input short-cuts, while \pkg{translator} is used for the translation of
words.

\subsection{Basic Concepts}

\subsubsection{Keys}

The main purpose of the \pkg{translator} package is to provide translations for
\emph{keys}. Typically, a key is an English word like |Figure| and the German
translation for this key is \enquote{Abbildung}.

For a concept like \enquote{figures} a single key typically is not enough:
\begin{enumerate}
  \item It is sometimes necessary to translate a group of words like
    \enquote{Table of figures} as a whole. While these are three words in
    English,the German translation in just a single word:
    \enquote{Abbildungsverzeichnis}.
  \item Uppercase and lowercase letters may cause problems. Suppose we provide
    a translation for the key |Figure|. Then what happens when we want to use
    this word in normal text, spelled with a lowercase first letter? We could
    use \TeX{}'s functions to turn the translation into lowercase, but that
    would be wrong with the German translation \enquote{Abbildung}, which is
    always spelled with a capital letter.
  \item Plurals may also cause problems. If we know the translation for
    \enquote{Figure}, that does not mean that we know the translation for
    \enquote{Figures} (which is \enquote{Abbildungen} in German).
\end{enumerate}

Because of these problems, there are many keys for the single concept of
\enquote{figures}: |Figure|, |figure|, |Figures|, and |figures|. The first key
is used for translations of \enquote{figure} when used in a headline in
singular. The last key is used for translations of \enquote{figure} when used
in normal text in plural.

A key may contain spaces, so |Table of figures| is a permissible key.

Keys are normally English texts whose English translation is the same as the
key, but this need not be the case. Theoretically, a key could be anything.
However, since the key is used as a last fall-back when no translation
whatsoever is available, a key should be readable by itself.

\subsubsection{Language Names}

The \pkg{translator} package uses names for languages that are different from
the names used by other packages like \pkg{babel}. The reason for this is that
the names used by \pkg{babel} are a bit of a mess, so Till decided to clean
things up for the \pkg{translator} package. However, mappings from \pkg{babel}
names to \pkg{translator} names are provided.

The names used by the \pkg{translator} package are the English names commonly
used for these languages. Thus, the name for the English language is |English|,
the name for German is |German|.

Variants of a language get their own name: The British version of English is
called |BritishEnglish|, the US-version is called |AmericanEnglish|.

For German there is the special problem of pre-1998 as opposed to the current
(not yet fixed) spelling. The language |German| reflects the current official
spelling, but |German1997| refers to the spelling used in 1997.

\subsubsection{Language Paths}

When you request a translation for a key, the \pkg{translator} package will try
to provide the translation for the current \emph{language}. Examples of
languages are German or English.

When the \pkg{translator} looks up the translation for the given key in the
current language, it may fail to find a translation. In this case, the
\pkg{translator} will try a fall-back strategy: it keeps track of a
\emph{language path} and successively tries to find translations for each
language on this path.

Language paths are not only useful for fall-backs. They are also used for
situations where a language is a variant of another language. For example, when
the \pkg{translator} looks for the translation for a key in Austrian, the
language path starts with Austrian, followed by German. Then, a dictionary for
Austrian only needs to provide translations for those keys where Austrian
differs from German.

\subsubsection{Dictionaries}

The translations of keys are typically provided by \emph{dictionaries}. A
dictionary contains the translations of a specific set of keys into a specific
language. For example, a dictionary might contain the translations of the names
of months into the language German. Another dictionary might contain the
translations of the numbers into French.

\subsection{Usage}

\subsubsection{Basic Usage}
\label{section-translator-basic-usage}
Here is a typical example of how to use the package:
\begin{verbatim}
\documentclass[german]{article}
\usepackage{babel}
\usepackage{some-package-that-uses-translator}
\begin{document}
...
\end{document}
\end{verbatim}

As can be seen, things really happen behind the scenes, so, typically, you do
not really need to do anything. It is the job of other package to load the
\pkg{translator} package, to load the dictionaries and to request translations
of keys.

\subsubsection{Providing Translations}

There are several commands to tell the \pkg{translator} package what the
translation of a given key is. As said before, as a normal author you typically
need not provide such translations explicitly, they are loaded automatically.
However, there are two situations in which you need to provide translations:
\begin{enumerate}
  \item You do not like the existing translation and you would
    like to provide a new one.
  \item You are writing a dictionary.
\end{enumerate}

\DescribeMacro{\newtranslation}
\begin{syntax}
  \cs{newtranslation}\oarg{options}\marg{key}\marg{translation}
\end{syntax}
This command defines the translation of \meta{key} to be \meta{translation} in
the language specified by the \meta{options}.

You can only use this command if the translation is really \enquote{new} in the
sense that no translation for the keys has yet been given for the language. If
there is already a translation, an error message will be printed.

The following \meta{options} may be given:
\begin{itemize}
  \item \texttt{to = \meta{language}}

    This options tells the \pkg{translator} that
    the \meta{translation} of \meta{keys} applies to the \meta{language}.

    Inside a dictionary file (see Section~\ref{section-dictionaries}), this
    option is set automatically to the language of the dictionary.
\end{itemize}

For example, one might use
\begin{verbatim}
\newtranslation[to = German]{figure}{Abbildung}
\newtranslation[to = German]{Figures}{Abbildungen}
\end{verbatim}
in a document to define these translations where they are not already
available.

\DescribeMacro{\renewtranslation}
\begin{syntax}
  \cs{renewtranslation}\oarg{options}\marg{key}\marg{translation}
\end{syntax}
This command works like \cs{newtranslation}, only it will redefine an existing
translation.

\DescribeMacro{\providetranslation}
\begin{syntax}
  \cs{providetranslation}\oarg{options}\marg{key}\marg{translation}
\end{syntax}
This command works like \cs{newtranslation}, but no error message will be printed
if the translation already exists. It this case, the existing translation is
not changed.

This command should be used by dictionary authors since their translations
should not overrule any translations given by document authors or other
dictionary authors.

\DescribeMacro{\deftranslation}
\begin{syntax}
  \cs{deftranslation}\oarg{options}\marg{key}\marg{translation}
\end{syntax}
This command defines the translation \enquote{no matter what}. An existing
translation will be overwritten.

This command should typically used by document authors to install their
preferred translations.

Here is an example where a translation is provided by a document author:
\begin{verbatim}
\documentclass[ngerman]{article}
\usepackage{babel}
\usepackage{some-package-that-uses-translator}
\deftranslation[to=German]{Sketch of proof}{Beweisskizze}
\begin{document}
...
\end{document}
\end{verbatim}

\subsubsection{Creating and Using Dictionaries}
\label{section-dictionaries}

Two kind of people will create \emph{dictionaries}: First, package authors will
create dictionaries containing translations for the (new) keys used in the
package. Second, document authors can create their own private dictionaries
that overrule settings from other dictionaries or that provide missing
translations.

There is not only one dictionary per language. Rather, many different
dictionaries may be used by \pkg{translator} when it tries to find a
translation. This makes it easy to add new translations: instead of having to
change \pkg{translator}'s main dictionaries (which involves, among other
things, the release of a new version of the \pkg{translator} package), package
authors can just add a new dictionary containing just the keys needed for the
package.

Dictionaries are named according to the following rule: the name of the
dictionary must start with its \emph{kind}. The kind tells \pkg{translator}
which kind of keys the dictionary contains. For example, the dictionaries of
the kind |translator-months-dictionary| contain keys like |January| (note that
this is a key, not a translation). Following the kind, the name of a dictionary
must have a dash. Then comes the language for which the dictionary file
provides translations. Finally, the file name must end with |.dict|.

To continue the example of the month dictionary, for the German language the
dictionary is called |translator-months-dictionary-German.dict|
Its contents is the following:
\begin{verbatim}
\ProvidesDictionary{translator-months-dictionary}{German}

\providetranslation{January}{Januar} \providetranslation{February}{Februar}
\providetranslation{March}{M\"arz} \providetranslation{April}{April}
\providetranslation{May}{Mai} \providetranslation{June}{Juni}
\providetranslation{July}{Juli} \providetranslation{August}{August}
\providetranslation{September}{September} \providetranslation{October}{Oktober}
\providetranslation{November}{November} \providetranslation{December}{Dezember}
\end{verbatim}
Note that the \cs{providetranslation} command does not need the option
|[to = German]|. Inside a dictionary file \pkg{translator} will always set the
default translation language to the language provided by the dictionary.
However, you can still specify the language, if you prefer.

\DescribeMacro{\ProvidesDictionary}
\begin{syntax}
  \cs{ProvidesDictionary}\marg{kind}\marg{language}\oarg{version}
\end{syntax}
This command currently only prints a message in the |.log| file. The format is
the same as for \LaTeX{}'s |\ProvidesPackage| command.

Dictionaries are stored in a decentralized manner: a special dictionary for a
package will typically be stored somewhere in the vicinity of the package. For
this reasons, \pkg{translator} needs to be told which \emph{kinds} of
dictionaries should be loaded and which \emph{languages} should be used. This
is accomplished using the following two commands.

\DescribeMacro{\usedictionary}
\begin{syntax}
  \cs{usedictionary}\marg{kind}
\end{syntax}
This command tells the \pkg{translator} package, that at the beginning of the
document it should load all dictionaries of kind \meta{kind} for the languages
used in the document. Note that the dictionaries are not loaded immediately,
but only at the beginning of the document.

If no dictionary of the given \emph{kind} exists for one of the language,
nothing bad happens.

Invocations of this command accumulate, that is, you can call it multiple times
for different dictionaries.

\DescribeMacro{\uselanguage}
\begin{syntax}
  \cs{uselanguage}\marg{languages}
\end{syntax}
This command tells the \pkg{translator} package that it should load the
dictionaries for all of the \meta{languages}. The dictionaries are loaded at
the beginning of the document.

Here is an example of how all of this works. Suppose you wish to create a new
package for drawing, say, chess boards. Let us call this package \pkg{chess}. In
the file |chess.sty| we could now write the following:
\begin{verbatim}
\RequirePackage{translator}
\usedictionary{chess}
...

\newcommand\MoveKnight[2]{%
  ...
  \translate{knight}
  ...
}
\end{verbatim}

Now we create dictionaries |chess-German.dict|
\begin{verbatim}
\ProvidesDictionary{chess}{German}

\providetranslation{chess}{Schach}
\providetranslation{knight}{Springer}
\providetranslation{bishop}{L\"aufer} 
... 
\end{verbatim}
and |chess-English.dict|
\begin{verbatim}
\ProvidesDictionary{chess}{English}

\providetranslation{chess}{chass}
\providetranslation{knight}{knight}
\providetranslation{bishop}{bishop}
...
\end{verbatim}

Here are a few things to note:
\begin{itemize}
  \item The package |chess.sty| does not use the command \cs{uselanguage}.
    After all, the package does not know (or care) about the language used in
    the final document. It only needs to tell the \pkg{translator} package
    that it will use the dictionary |chess|.
  \item You may wonder why we need an English dictionary. After all, the keys
    themselves are the ultimate fall-backs if no other translation is available.
    The answer to this question is that, first of all, English should be treated
    like any other language. Second, there are some situations in which there is
    a \enquote{better} English translation than the key itself. An example is
    explained next.
  \item The keys we chose may not be optimal. What happens, if some other
    package, perhaps on medieval architecture, also needs translations of
    knights and bishops. However, in this different context, the translations
    of knight and bishop are totally different, namely |Ritter| and |Bischof|.

    Thus, it might be a good idea to add something to the key to make it clear
    that the \enquote{chess bishop} is meant:
    \begin{verbatim}
\providetranslation{knight (chess)}{Springer}
\providetranslation{bishop (chess)}{L\"aufer}
    \end{verbatim}
    for German and
    \begin{verbatim}
\providetranslation{knight (chess)}{knight}
\providetranslation{bishop (chess)}{bishop}
    \end{verbatim}
    for English.
\end{itemize}

\subsubsection{Creating a User Dictionary}

There are two ways of creating a personal set of translations. First, you can
simply add commands like
\begin{verbatim}
\deftranslation[to = German]{figure}{Figur}
\end{verbatim}
to your personal macro files.

Second, you can create a personal dictionary file as follows: In your document
you say
\begin{verbatim}
\documentclass[ngerman]{article}
\usepackage{translator}
\usedictionary{my-personal-dictionary}
\end{verbatim}
and then you create the following file somewhere where \TeX{} can find it:
\begin{verbatim}
\ProvidesDictionary{my-personal-dictionary}{German}

\deftranslation{figure}{Figur}
\end{verbatim}

\subsubsection{Translating Keys}

Once the dictionaries and languages have been setup, you can translate keys
using the following commands.

\DescribeMacro{\translate}
\begin{syntax}
  \cs{translate}\oarg{options}\marg{key}
\end{syntax}
This command will insert the translation of the \meta{key} at the current
position into the text. The command is robust.

The translation process of \meta{key} works as follows: \pkg{translator}
iterates over all languages on the current \emph{language path} (see
Section~\ref{section-language-path}). For each language on the path,
\pkg{translator} checks whether a translation is available for the \meta{key}.
For the first language for which this is the case, the translation is used. If
there is no translation available for any language on the path, the \meta{key}
itself is used as the translation.

The following options may be given:
\begin{itemize}
  \item \texttt{to = \meta{language}}
  
  This option overrules the language path setting and installs
  \meta{language} as the target language(s) for which \pkg{translator} tries to
  find a translation.
\end{itemize}

\DescribeMacro{\translatelet}
\begin{syntax}
  \cs{translatelet}\oarg{options}\marg{macro}\marg{key}
\end{syntax}
This command works like the \cs{translate} command, only it will not insert the
translation into the text, but will set the macro \meta{macro} to the
translation found by the \cs{translate} command.

\subsubsection{Language Path and Language Substitution}
\label{section-language-path}

\DescribeMacro{\languagepath}
\begin{syntax}
  \cs{languagepath}\marg{language path}
\end{syntax}
This command sets the language path that is searched when \pkg{translator}
looks for a key.

The default value of the language path is |\languagename,English|. The
\cs{languagename} is the standard \TeX{} macro that expands to the current
language. Typically, this is exactly what you want and there is no real need to
change this default language path.

There is a problem with the names used in the macro \cs{languagename}. These
names, like |ngerman|, are not the ones used by \pkg{translator} and we somehow
have to tell the \pkg{translator} about aliases for cryptic language names like
|ngerman|. This is done using the following command:

\DescribeMacro{\languagealias}
\begin{syntax}
  \cs{languagealias}\marg{name}\marg{language list}
\end{syntax}
This command tells the \pkg{translator} that the language \meta{name} should be
replaced by the language in the \meta{language list}, for example
\begin{verbatim}
\languagealias{ngerman}{German}
\languagealias{german}{German1997,German}
\end{verbatim}

For the languages used by the \pkg{babel} package, the aliases are automatically
set up, so you typically do not need to call either \cs{languagepath} or
\cs{languagealias}.

\subsubsection{Package Loading Process}

The \pkg{translator} package is loaded \enquote{in stages}:
\begin{enumerate}
  \item First, some package or the document author requests the
    \pkg{translator} package is loaded.
  \item The \pkg{translator} package allows options like |ngerman| to be
    given. These options cause the necessary aliases and the correct
    \pkg{translator} languages to be requested.
  \item During the preamble, packages and the document author request creating
    dictionary kinds and certain languages to be used. There requests are
    stored for loading later.
  \item At the beginning of the document the requested dictionary--language
    pairs are loaded.
\end{enumerate}

The first thing that needs to be done is to load the package. Typically, this
is done automatically by some other package, but you may wish to include it
directly:

When you load the package, you can specify (multiple) \pkg{babel} languages as
\meta{options}. The effect of giving such an option is the following: It causes
the \pkg{translator} package to call \cs{uselanguage} for the appropriate
translation of the \pkg{babel} language names to \pkg{translator}'s language names.
It also causes \cs{languagealias} to be called for the languages.

\section{Contributing}

Since this package is about internationalization, it needs input from people
who can contribute translations to their native tongue.

In order to submit dictionaries, please do the following:
\begin{enumerate}
  \item Read this manual and make sure you understand the basic concepts.
  \item Find out whether the translations should be part of the
    \pkg{translator} package or part of another package. In general, submit
    translations and new keys to the \pkg{translator} project only if they are
    of public interest.

    For example, translations for keys like |figure| should be send to the
    \pkg{translator} project. Translations for keys that are part of a special
    package should be send to the author of the package.
  \item If you are sure that the translations should go to the \pkg{translator}
    package, create a dictionary of the correct name (see this documentation
    once more).
  \item Finally, submit the dictionary on the development site:
    \url{https://github.com/josephwright/translator}.
\end{enumerate}

\end{document}