summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/translator/translator.tex
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/translator/translator.tex')
-rw-r--r--macros/latex/contrib/translator/translator.tex560
1 files changed, 560 insertions, 0 deletions
diff --git a/macros/latex/contrib/translator/translator.tex b/macros/latex/contrib/translator/translator.tex
new file mode 100644
index 0000000000..9bc754603d
--- /dev/null
+++ b/macros/latex/contrib/translator/translator.tex
@@ -0,0 +1,560 @@
+% 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} \ No newline at end of file