From 2568ba5fe39456a77b0d8c0004bedb4216df342e Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Thu, 30 Nov 2017 21:55:26 +0000 Subject: translator (30nov17) git-svn-id: svn://tug.org/texlive/trunk@45955 c570f23f-e606-0410-a88d-b1316a301751 --- Master/texmf-dist/doc/latex/translator/README.md | 10 + .../texmf-dist/doc/latex/translator/translator.pdf | Bin 0 -> 193263 bytes .../texmf-dist/doc/latex/translator/translator.tex | 558 +++++++++++++++++++++ 3 files changed, 568 insertions(+) create mode 100644 Master/texmf-dist/doc/latex/translator/README.md create mode 100644 Master/texmf-dist/doc/latex/translator/translator.pdf create mode 100644 Master/texmf-dist/doc/latex/translator/translator.tex (limited to 'Master/texmf-dist/doc') 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 Binary files /dev/null and b/Master/texmf-dist/doc/latex/translator/translator.pdf differ 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 -- cgit v1.2.3