| 1 |
% Copyright 2007 by Till Tantau |
| 2 |
% Copyright 2010 by Vedran Mileti\'c |
| 3 |
% Copyright 2013,2015 by Vedran Mileti\'c, Joseph Wright |
| 4 |
% Copyright 2017 Joseph Wright |
| 5 |
% |
| 6 |
% This file may be distributed and/or modified |
| 7 |
% |
| 8 |
% 1. under the LaTeX Project Public License and/or |
| 9 |
% 2. under the GNU Public License. |
| 10 |
% |
| 11 |
% See the documentation file for more details. |
| 12 |
|
| 13 |
\documentclass{ltxdoc} |
| 14 |
|
| 15 |
% The next line is needed so that \GetFileInfo will be able to pick up |
| 16 |
% version data. |
| 17 |
\usepackage{translator} |
| 18 |
|
| 19 |
\usepackage{csquotes} |
| 20 |
|
| 21 |
\usepackage{xparse} |
| 22 |
\NewDocumentCommand{\pkg}{m}{\textsf{#1}} |
| 23 |
\newbox{\syntaxbox} |
| 24 |
\NewDocumentEnvironment{syntax}{} |
| 25 |
{\begin{lrbox}{\syntaxbox}} |
| 26 |
{% |
| 27 |
\end{lrbox}% |
| 28 |
\noindent |
| 29 |
\usebox{\syntaxbox}\\ |
| 30 |
} |
| 31 |
\usepackage{hypdoc} |
| 32 |
|
| 33 |
\begin{document} |
| 34 |
|
| 35 |
\GetFileInfo{translator.sty} |
| 36 |
|
| 37 |
\title{% |
| 38 |
\pkg{translator} -- Easy translation of strings in LaTeX% |
| 39 |
\thanks{This file describes \fileversion, |
| 40 |
last revised \filedate.}% |
| 41 |
} |
| 42 |
|
| 43 |
\author{% |
| 44 |
Joseph Wright% |
| 45 |
\thanks{% |
| 46 |
E-mail: |
| 47 |
\href{mailto:[email protected]} |
| 48 |
{[email protected]}% |
| 49 |
}% |
| 50 |
} |
| 51 |
|
| 52 |
\date{Released \filedate} |
| 53 |
|
| 54 |
\maketitle |
| 55 |
|
| 56 |
\tableofcontents |
| 57 |
|
| 58 |
\section{Translating Strings} |
| 59 |
|
| 60 |
\subsection{Introduction} |
| 61 |
|
| 62 |
The \pkg{translator} package is a \LaTeX{} package that provides a flexible |
| 63 |
mechanism for translating individual words into different languages. For |
| 64 |
example, it can be used to translate a word like \enquote{figure} into, say, |
| 65 |
the German word \enquote{Abbildung}. Such a translation mechanism is useful |
| 66 |
when the author of some package would like to localize the package such that |
| 67 |
texts are correctly translated into the language preferred by the user. The |
| 68 |
\pkg{translator} package is \emph{not} intended to be used to automatically |
| 69 |
translate more than a few words. |
| 70 |
|
| 71 |
You may wonder whether the \pkg{translator} package is really necessary since |
| 72 |
there is the (very nice) \pkg{babel} package available for \LaTeX{}. This |
| 73 |
package already provides translations for words like \enquote{figure}. |
| 74 |
Unfortunately, the architecture of the \pkg{babel} package was designed in such |
| 75 |
a way that there is no way of adding translations of new words to the (very |
| 76 |
short) list of translations directly built into \pkg{babel}. |
| 77 |
|
| 78 |
The \pkg{translator} package was specifically designed to allow an easy |
| 79 |
extension of the vocabulary. It is both possible to add new words that should |
| 80 |
be translated and translations of these words. |
| 81 |
|
| 82 |
The \pkg{translator} package can be used together with \pkg{babel}. In this |
| 83 |
case, babel is used for language-specific things like special quotation marks |
| 84 |
and input short-cuts, while \pkg{translator} is used for the translation of |
| 85 |
words. |
| 86 |
|
| 87 |
\subsection{Basic Concepts} |
| 88 |
|
| 89 |
\subsubsection{Keys} |
| 90 |
|
| 91 |
The main purpose of the \pkg{translator} package is to provide translations for |
| 92 |
\emph{keys}. Typically, a key is an English word like |Figure| and the German |
| 93 |
translation for this key is \enquote{Abbildung}. |
| 94 |
|
| 95 |
For a concept like \enquote{figures} a single key typically is not enough: |
| 96 |
\begin{enumerate} |
| 97 |
\item It is sometimes necessary to translate a group of words like |
| 98 |
\enquote{Table of figures} as a whole. While these are three words in |
| 99 |
English,the German translation in just a single word: |
| 100 |
\enquote{Abbildungsverzeichnis}. |
| 101 |
\item Uppercase and lowercase letters may cause problems. Suppose we provide |
| 102 |
a translation for the key |Figure|. Then what happens when we want to use |
| 103 |
this word in normal text, spelled with a lowercase first letter? We could |
| 104 |
use \TeX{}'s functions to turn the translation into lowercase, but that |
| 105 |
would be wrong with the German translation \enquote{Abbildung}, which is |
| 106 |
always spelled with a capital letter. |
| 107 |
\item Plurals may also cause problems. If we know the translation for |
| 108 |
\enquote{Figure}, that does not mean that we know the translation for |
| 109 |
\enquote{Figures} (which is \enquote{Abbildungen} in German). |
| 110 |
\end{enumerate} |
| 111 |
|
| 112 |
Because of these problems, there are many keys for the single concept of |
| 113 |
\enquote{figures}: |Figure|, |figure|, |Figures|, and |figures|. The first key |
| 114 |
is used for translations of \enquote{figure} when used in a headline in |
| 115 |
singular. The last key is used for translations of \enquote{figure} when used |
| 116 |
in normal text in plural. |
| 117 |
|
| 118 |
A key may contain spaces, so |Table of figures| is a permissible key. |
| 119 |
|
| 120 |
Keys are normally English texts whose English translation is the same as the |
| 121 |
key, but this need not be the case. Theoretically, a key could be anything. |
| 122 |
However, since the key is used as a last fall-back when no translation |
| 123 |
whatsoever is available, a key should be readable by itself. |
| 124 |
|
| 125 |
\subsubsection{Language Names} |
| 126 |
|
| 127 |
The \pkg{translator} package uses names for languages that are different from |
| 128 |
the names used by other packages like \pkg{babel}. The reason for this is that |
| 129 |
the names used by \pkg{babel} are a bit of a mess, so Till decided to clean |
| 130 |
things up for the \pkg{translator} package. However, mappings from \pkg{babel} |
| 131 |
names to \pkg{translator} names are provided. |
| 132 |
|
| 133 |
The names used by the \pkg{translator} package are the English names commonly |
| 134 |
used for these languages. Thus, the name for the English language is |English|, |
| 135 |
the name for German is |German|. |
| 136 |
|
| 137 |
Variants of a language get their own name: The British version of English is |
| 138 |
called |BritishEnglish|, the US-version is called |AmericanEnglish|. |
| 139 |
|
| 140 |
For German there is the special problem of pre-1998 as opposed to the current |
| 141 |
(not yet fixed) spelling. The language |German| reflects the current official |
| 142 |
spelling, but |German1997| refers to the spelling used in 1997. |
| 143 |
|
| 144 |
\subsubsection{Language Paths} |
| 145 |
|
| 146 |
When you request a translation for a key, the \pkg{translator} package will try |
| 147 |
to provide the translation for the current \emph{language}. Examples of |
| 148 |
languages are German or English. |
| 149 |
|
| 150 |
When the \pkg{translator} looks up the translation for the given key in the |
| 151 |
current language, it may fail to find a translation. In this case, the |
| 152 |
\pkg{translator} will try a fall-back strategy: it keeps track of a |
| 153 |
\emph{language path} and successively tries to find translations for each |
| 154 |
language on this path. |
| 155 |
|
| 156 |
Language paths are not only useful for fall-backs. They are also used for |
| 157 |
situations where a language is a variant of another language. For example, when |
| 158 |
the \pkg{translator} looks for the translation for a key in Austrian, the |
| 159 |
language path starts with Austrian, followed by German. Then, a dictionary for |
| 160 |
Austrian only needs to provide translations for those keys where Austrian |
| 161 |
differs from German. |
| 162 |
|
| 163 |
\subsubsection{Dictionaries} |
| 164 |
|
| 165 |
The translations of keys are typically provided by \emph{dictionaries}. A |
| 166 |
dictionary contains the translations of a specific set of keys into a specific |
| 167 |
language. For example, a dictionary might contain the translations of the names |
| 168 |
of months into the language German. Another dictionary might contain the |
| 169 |
translations of the numbers into French. |
| 170 |
|
| 171 |
\subsection{Usage} |
| 172 |
|
| 173 |
\subsubsection{Basic Usage} |
| 174 |
\label{section-translator-basic-usage} |
| 175 |
Here is a typical example of how to use the package: |
| 176 |
\begin{verbatim} |
| 177 |
\documentclass[german]{article} |
| 178 |
\usepackage{babel} |
| 179 |
\usepackage{some-package-that-uses-translator} |
| 180 |
\begin{document} |
| 181 |
... |
| 182 |
\end{document} |
| 183 |
\end{verbatim} |
| 184 |
|
| 185 |
As can be seen, things really happen behind the scenes, so, typically, you do |
| 186 |
not really need to do anything. It is the job of other package to load the |
| 187 |
\pkg{translator} package, to load the dictionaries and to request translations |
| 188 |
of keys. |
| 189 |
|
| 190 |
\subsubsection{Providing Translations} |
| 191 |
|
| 192 |
There are several commands to tell the \pkg{translator} package what the |
| 193 |
translation of a given key is. As said before, as a normal author you typically |
| 194 |
need not provide such translations explicitly, they are loaded automatically. |
| 195 |
However, there are two situations in which you need to provide translations: |
| 196 |
\begin{enumerate} |
| 197 |
\item You do not like the existing translation and you would |
| 198 |
like to provide a new one. |
| 199 |
\item You are writing a dictionary. |
| 200 |
\end{enumerate} |
| 201 |
|
| 202 |
\DescribeMacro{\newtranslation} |
| 203 |
\begin{syntax} |
| 204 |
\cs{newtranslation}\oarg{options}\marg{key}\marg{translation} |
| 205 |
\end{syntax} |
| 206 |
This command defines the translation of \meta{key} to be \meta{translation} in |
| 207 |
the language specified by the \meta{options}. |
| 208 |
|
| 209 |
You can only use this command if the translation is really \enquote{new} in the |
| 210 |
sense that no translation for the keys has yet been given for the language. If |
| 211 |
there is already a translation, an error message will be printed. |
| 212 |
|
| 213 |
The following \meta{options} may be given: |
| 214 |
\begin{itemize} |
| 215 |
\item \texttt{to = \meta{language}} |
| 216 |
|
| 217 |
This options tells the \pkg{translator} that |
| 218 |
the \meta{translation} of \meta{keys} applies to the \meta{language}. |
| 219 |
|
| 220 |
Inside a dictionary file (see Section~\ref{section-dictionaries}), this |
| 221 |
option is set automatically to the language of the dictionary. |
| 222 |
\end{itemize} |
| 223 |
|
| 224 |
For example, one might use |
| 225 |
\begin{verbatim} |
| 226 |
\newtranslation[to = German]{figure}{Abbildung} |
| 227 |
\newtranslation[to = German]{Figures}{Abbildungen} |
| 228 |
\end{verbatim} |
| 229 |
in a document to define these translations where they are not already |
| 230 |
available. |
| 231 |
|
| 232 |
\DescribeMacro{\renewtranslation} |
| 233 |
\begin{syntax} |
| 234 |
\cs{renewtranslation}\oarg{options}\marg{key}\marg{translation} |
| 235 |
\end{syntax} |
| 236 |
This command works like \cs{newtranslation}, only it will redefine an existing |
| 237 |
translation. |
| 238 |
|
| 239 |
\DescribeMacro{\providetranslation} |
| 240 |
\begin{syntax} |
| 241 |
\cs{providetranslation}\oarg{options}\marg{key}\marg{translation} |
| 242 |
\end{syntax} |
| 243 |
This command works like \cs{newtranslation}, but no error message will be printed |
| 244 |
if the translation already exists. It this case, the existing translation is |
| 245 |
not changed. |
| 246 |
|
| 247 |
This command should be used by dictionary authors since their translations |
| 248 |
should not overrule any translations given by document authors or other |
| 249 |
dictionary authors. |
| 250 |
|
| 251 |
\DescribeMacro{\deftranslation} |
| 252 |
\begin{syntax} |
| 253 |
\cs{deftranslation}\oarg{options}\marg{key}\marg{translation} |
| 254 |
\end{syntax} |
| 255 |
This command defines the translation \enquote{no matter what}. An existing |
| 256 |
translation will be overwritten. |
| 257 |
|
| 258 |
This command should typically used by document authors to install their |
| 259 |
preferred translations. |
| 260 |
|
| 261 |
Here is an example where a translation is provided by a document author: |
| 262 |
\begin{verbatim} |
| 263 |
\documentclass[ngerman]{article} |
| 264 |
\usepackage{babel} |
| 265 |
\usepackage{some-package-that-uses-translator} |
| 266 |
\deftranslation[to=German]{Sketch of proof}{Beweisskizze} |
| 267 |
\begin{document} |
| 268 |
... |
| 269 |
\end{document} |
| 270 |
\end{verbatim} |
| 271 |
|
| 272 |
\subsubsection{Creating and Using Dictionaries} |
| 273 |
\label{section-dictionaries} |
| 274 |
|
| 275 |
Two kind of people will create \emph{dictionaries}: First, package authors will |
| 276 |
create dictionaries containing translations for the (new) keys used in the |
| 277 |
package. Second, document authors can create their own private dictionaries |
| 278 |
that overrule settings from other dictionaries or that provide missing |
| 279 |
translations. |
| 280 |
|
| 281 |
There is not only one dictionary per language. Rather, many different |
| 282 |
dictionaries may be used by \pkg{translator} when it tries to find a |
| 283 |
translation. This makes it easy to add new translations: instead of having to |
| 284 |
change \pkg{translator}'s main dictionaries (which involves, among other |
| 285 |
things, the release of a new version of the \pkg{translator} package), package |
| 286 |
authors can just add a new dictionary containing just the keys needed for the |
| 287 |
package. |
| 288 |
|
| 289 |
Dictionaries are named according to the following rule: the name of the |
| 290 |
dictionary must start with its \emph{kind}. The kind tells \pkg{translator} |
| 291 |
which kind of keys the dictionary contains. For example, the dictionaries of |
| 292 |
the kind |translator-months-dictionary| contain keys like |January| (note that |
| 293 |
this is a key, not a translation). Following the kind, the name of a dictionary |
| 294 |
must have a dash. Then comes the language for which the dictionary file |
| 295 |
provides translations. Finally, the file name must end with |.dict|. |
| 296 |
|
| 297 |
To continue the example of the month dictionary, for the German language the |
| 298 |
dictionary is called |translator-months-dictionary-German.dict| |
| 299 |
Its contents is the following: |
| 300 |
\begin{verbatim} |
| 301 |
\ProvidesDictionary{translator-months-dictionary}{German} |
| 302 |
|
| 303 |
\providetranslation{January}{Januar} \providetranslation{February}{Februar} |
| 304 |
\providetranslation{March}{M\"arz} \providetranslation{April}{April} |
| 305 |
\providetranslation{May}{Mai} \providetranslation{June}{Juni} |
| 306 |
\providetranslation{July}{Juli} \providetranslation{August}{August} |
| 307 |
\providetranslation{September}{September} \providetranslation{October}{Oktober} |
| 308 |
\providetranslation{November}{November} \providetranslation{December}{Dezember} |
| 309 |
\end{verbatim} |
| 310 |
Note that the \cs{providetranslation} command does not need the option |
| 311 |
|[to = German]|. Inside a dictionary file \pkg{translator} will always set the |
| 312 |
default translation language to the language provided by the dictionary. |
| 313 |
However, you can still specify the language, if you prefer. |
| 314 |
|
| 315 |
\DescribeMacro{\ProvidesDictionary} |
| 316 |
\begin{syntax} |
| 317 |
\cs{ProvidesDictionary}\marg{kind}\marg{language}\oarg{version} |
| 318 |
\end{syntax} |
| 319 |
This command currently only prints a message in the |.log| file. The format is |
| 320 |
the same as for \LaTeX{}'s |\ProvidesPackage| command. |
| 321 |
|
| 322 |
Dictionaries are stored in a decentralized manner: a special dictionary for a |
| 323 |
package will typically be stored somewhere in the vicinity of the package. For |
| 324 |
this reasons, \pkg{translator} needs to be told which \emph{kinds} of |
| 325 |
dictionaries should be loaded and which \emph{languages} should be used. This |
| 326 |
is accomplished using the following two commands. |
| 327 |
|
| 328 |
\DescribeMacro{\usedictionary} |
| 329 |
\begin{syntax} |
| 330 |
\cs{usedictionary}\marg{kind} |
| 331 |
\end{syntax} |
| 332 |
This command tells the \pkg{translator} package, that at the beginning of the |
| 333 |
document it should load all dictionaries of kind \meta{kind} for the languages |
| 334 |
used in the document. Note that the dictionaries are not loaded immediately, |
| 335 |
but only at the beginning of the document. |
| 336 |
|
| 337 |
If no dictionary of the given \emph{kind} exists for one of the language, |
| 338 |
nothing bad happens. |
| 339 |
|
| 340 |
Invocations of this command accumulate, that is, you can call it multiple times |
| 341 |
for different dictionaries. |
| 342 |
|
| 343 |
\DescribeMacro{\uselanguage} |
| 344 |
\begin{syntax} |
| 345 |
\cs{uselanguage}\marg{languages} |
| 346 |
\end{syntax} |
| 347 |
This command tells the \pkg{translator} package that it should load the |
| 348 |
dictionaries for all of the \meta{languages}. The dictionaries are loaded at |
| 349 |
the beginning of the document. |
| 350 |
|
| 351 |
Here is an example of how all of this works. Suppose you wish to create a new |
| 352 |
package for drawing, say, chess boards. Let us call this package \pkg{chess}. In |
| 353 |
the file |chess.sty| we could now write the following: |
| 354 |
\begin{verbatim} |
| 355 |
\RequirePackage{translator} |
| 356 |
\usedictionary{chess} |
| 357 |
... |
| 358 |
|
| 359 |
\newcommand\MoveKnight[2]{% |
| 360 |
... |
| 361 |
\translate{knight} |
| 362 |
... |
| 363 |
} |
| 364 |
\end{verbatim} |
| 365 |
|
| 366 |
Now we create dictionaries |chess-German.dict| |
| 367 |
\begin{verbatim} |
| 368 |
\ProvidesDictionary{chess}{German} |
| 369 |
|
| 370 |
\providetranslation{chess}{Schach} |
| 371 |
\providetranslation{knight}{Springer} |
| 372 |
\providetranslation{bishop}{L\"aufer} |
| 373 |
... |
| 374 |
\end{verbatim} |
| 375 |
and |chess-English.dict| |
| 376 |
\begin{verbatim} |
| 377 |
\ProvidesDictionary{chess}{English} |
| 378 |
|
| 379 |
\providetranslation{chess}{chass} |
| 380 |
\providetranslation{knight}{knight} |
| 381 |
\providetranslation{bishop}{bishop} |
| 382 |
... |
| 383 |
\end{verbatim} |
| 384 |
|
| 385 |
Here are a few things to note: |
| 386 |
\begin{itemize} |
| 387 |
\item The package |chess.sty| does not use the command \cs{uselanguage}. |
| 388 |
After all, the package does not know (or care) about the language used in |
| 389 |
the final document. It only needs to tell the \pkg{translator} package |
| 390 |
that it will use the dictionary |chess|. |
| 391 |
\item You may wonder why we need an English dictionary. After all, the keys |
| 392 |
themselves are the ultimate fall-backs if no other translation is available. |
| 393 |
The answer to this question is that, first of all, English should be treated |
| 394 |
like any other language. Second, there are some situations in which there is |
| 395 |
a \enquote{better} English translation than the key itself. An example is |
| 396 |
explained next. |
| 397 |
\item The keys we chose may not be optimal. What happens, if some other |
| 398 |
package, perhaps on medieval architecture, also needs translations of |
| 399 |
knights and bishops. However, in this different context, the translations |
| 400 |
of knight and bishop are totally different, namely |Ritter| and |Bischof|. |
| 401 |
|
| 402 |
Thus, it might be a good idea to add something to the key to make it clear |
| 403 |
that the \enquote{chess bishop} is meant: |
| 404 |
\begin{verbatim} |
| 405 |
\providetranslation{knight (chess)}{Springer} |
| 406 |
\providetranslation{bishop (chess)}{L\"aufer} |
| 407 |
\end{verbatim} |
| 408 |
for German and |
| 409 |
\begin{verbatim} |
| 410 |
\providetranslation{knight (chess)}{knight} |
| 411 |
\providetranslation{bishop (chess)}{bishop} |
| 412 |
\end{verbatim} |
| 413 |
for English. |
| 414 |
\end{itemize} |
| 415 |
|
| 416 |
\subsubsection{Creating a User Dictionary} |
| 417 |
|
| 418 |
There are two ways of creating a personal set of translations. First, you can |
| 419 |
simply add commands like |
| 420 |
\begin{verbatim} |
| 421 |
\deftranslation[to = German]{figure}{Figur} |
| 422 |
\end{verbatim} |
| 423 |
to your personal macro files. |
| 424 |
|
| 425 |
Second, you can create a personal dictionary file as follows: In your document |
| 426 |
you say |
| 427 |
\begin{verbatim} |
| 428 |
\documentclass[ngerman]{article} |
| 429 |
\usepackage{translator} |
| 430 |
\usedictionary{my-personal-dictionary} |
| 431 |
\end{verbatim} |
| 432 |
and then you create the following file somewhere where \TeX{} can find it: |
| 433 |
\begin{verbatim} |
| 434 |
\ProvidesDictionary{my-personal-dictionary}{German} |
| 435 |
|
| 436 |
\deftranslation{figure}{Figur} |
| 437 |
\end{verbatim} |
| 438 |
|
| 439 |
\subsubsection{Translating Keys} |
| 440 |
|
| 441 |
Once the dictionaries and languages have been setup, you can translate keys |
| 442 |
using the following commands. |
| 443 |
|
| 444 |
\DescribeMacro{\translate} |
| 445 |
\begin{syntax} |
| 446 |
\cs{translate}\oarg{options}\marg{key} |
| 447 |
\end{syntax} |
| 448 |
This command will insert the translation of the \meta{key} at the current |
| 449 |
position into the text. The command is robust. |
| 450 |
|
| 451 |
The translation process of \meta{key} works as follows: \pkg{translator} |
| 452 |
iterates over all languages on the current \emph{language path} (see |
| 453 |
Section~\ref{section-language-path}). For each language on the path, |
| 454 |
\pkg{translator} checks whether a translation is available for the \meta{key}. |
| 455 |
For the first language for which this is the case, the translation is used. If |
| 456 |
there is no translation available for any language on the path, the \meta{key} |
| 457 |
itself is used as the translation. |
| 458 |
|
| 459 |
The following options may be given: |
| 460 |
\begin{itemize} |
| 461 |
\item \texttt{to = \meta{language}} |
| 462 |
|
| 463 |
This option overrules the language path setting and installs |
| 464 |
\meta{language} as the target language(s) for which \pkg{translator} tries to |
| 465 |
find a translation. |
| 466 |
\end{itemize} |
| 467 |
|
| 468 |
\DescribeMacro{\translatelet} |
| 469 |
\begin{syntax} |
| 470 |
\cs{translatelet}\oarg{options}\marg{macro}\marg{key} |
| 471 |
\end{syntax} |
| 472 |
This command works like the \cs{translate} command, only it will not insert the |
| 473 |
translation into the text, but will set the macro \meta{macro} to the |
| 474 |
translation found by the \cs{translate} command. |
| 475 |
|
| 476 |
\subsubsection{Language Path and Language Substitution} |
| 477 |
\label{section-language-path} |
| 478 |
|
| 479 |
\DescribeMacro{\languagepath} |
| 480 |
\begin{syntax} |
| 481 |
\cs{languagepath}\marg{language path} |
| 482 |
\end{syntax} |
| 483 |
This command sets the language path that is searched when \pkg{translator} |
| 484 |
looks for a key. |
| 485 |
|
| 486 |
The default value of the language path is |\languagename,English|. The |
| 487 |
\cs{languagename} is the standard \TeX{} macro that expands to the current |
| 488 |
language. Typically, this is exactly what you want and there is no real need to |
| 489 |
change this default language path. |
| 490 |
|
| 491 |
There is a problem with the names used in the macro \cs{languagename}. These |
| 492 |
names, like |ngerman|, are not the ones used by \pkg{translator} and we somehow |
| 493 |
have to tell the \pkg{translator} about aliases for cryptic language names like |
| 494 |
|ngerman|. This is done using the following command: |
| 495 |
|
| 496 |
\DescribeMacro{\languagealias} |
| 497 |
\begin{syntax} |
| 498 |
\cs{languagealias}\marg{name}\marg{language list} |
| 499 |
\end{syntax} |
| 500 |
This command tells the \pkg{translator} that the language \meta{name} should be |
| 501 |
replaced by the language in the \meta{language list}, for example |
| 502 |
\begin{verbatim} |
| 503 |
\languagealias{ngerman}{German} |
| 504 |
\languagealias{german}{German1997,German} |
| 505 |
\end{verbatim} |
| 506 |
|
| 507 |
For the languages used by the \pkg{babel} package, the aliases are automatically |
| 508 |
set up, so you typically do not need to call either \cs{languagepath} or |
| 509 |
\cs{languagealias}. |
| 510 |
|
| 511 |
\subsubsection{Package Loading Process} |
| 512 |
|
| 513 |
The \pkg{translator} package is loaded \enquote{in stages}: |
| 514 |
\begin{enumerate} |
| 515 |
\item First, some package or the document author requests the |
| 516 |
\pkg{translator} package is loaded. |
| 517 |
\item The \pkg{translator} package allows options like |ngerman| to be |
| 518 |
given. These options cause the necessary aliases and the correct |
| 519 |
\pkg{translator} languages to be requested. |
| 520 |
\item During the preamble, packages and the document author request creating |
| 521 |
dictionary kinds and certain languages to be used. There requests are |
| 522 |
stored for loading later. |
| 523 |
\item At the beginning of the document the requested dictionary--language |
| 524 |
pairs are loaded. |
| 525 |
\end{enumerate} |
| 526 |
|
| 527 |
The first thing that needs to be done is to load the package. Typically, this |
| 528 |
is done automatically by some other package, but you may wish to include it |
| 529 |
directly: |
| 530 |
|
| 531 |
When you load the package, you can specify (multiple) \pkg{babel} languages as |
| 532 |
\meta{options}. The effect of giving such an option is the following: It causes |
| 533 |
the \pkg{translator} package to call \cs{uselanguage} for the appropriate |
| 534 |
translation of the \pkg{babel} language names to \pkg{translator}'s language names. |
| 535 |
It also causes \cs{languagealias} to be called for the languages. |
| 536 |
|
| 537 |
\section{Contributing} |
| 538 |
|
| 539 |
Since this package is about internationalization, it needs input from people |
| 540 |
who can contribute translations to their native tongue. |
| 541 |
|
| 542 |
In order to submit dictionaries, please do the following: |
| 543 |
\begin{enumerate} |
| 544 |
\item Read this manual and make sure you understand the basic concepts. |
| 545 |
\item Find out whether the translations should be part of the |
| 546 |
\pkg{translator} package or part of another package. In general, submit |
| 547 |
translations and new keys to the \pkg{translator} project only if they are |
| 548 |
of public interest. |
| 549 |
|
| 550 |
For example, translations for keys like |figure| should be send to the |
| 551 |
\pkg{translator} project. Translations for keys that are part of a special |
| 552 |
package should be send to the author of the package. |
| 553 |
\item If you are sure that the translations should go to the \pkg{translator} |
| 554 |
package, create a dictionary of the correct name (see this documentation |
| 555 |
once more). |
| 556 |
\item Finally, submit the dictionary on the development site: |
| 557 |
\url{https://github.com/josephwright/translator}. |
| 558 |
\end{enumerate} |
| 559 |
|
| 560 |
\end{document} |