Debian Codegraph @

texmf-dist/doc/latex/translator/translator.tex

raw
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}