translator (30nov17)

git-svn-id: svn://tug.org/texlive/trunk@45955 c570f23f-e606-0410-a88d-b1316a301751

3 files changed, 568 insertions, 0 deletions

diff --git a/Master/texmf-dist/doc/latex/translator/README.md b/Master/texmf-dist/doc/latex/translator/README.md
new file mode 100644
index 00000000000..43fcb59db08
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/translator/README.md
@@ -0,0 +1,10 @@
+# translator - Easy translation of strings in LaTeX
+
+The 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 figure into, say, the
+German word 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 translator package is not intended to be used to automatically
+translate more than a few words.
diff --git a/Master/texmf-dist/doc/latex/translator/translator.pdf b/Master/texmf-dist/doc/latex/translator/translator.pdf
new file mode 100644
index 00000000000..da67161dab6
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/translator/translator.pdf
diff --git a/Master/texmf-dist/doc/latex/translator/translator.tex b/Master/texmf-dist/doc/latex/translator/translator.tex
new file mode 100644
index 00000000000..f5efee131ae
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/translator/translator.tex
@@ -0,0 +1,558 @@
+% 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}%
+  \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}%
+  }%
+}
+
+\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