diff options
Diffstat (limited to 'Master/texmf-dist/doc/latex')
| -rw-r--r-- | Master/texmf-dist/doc/latex/translations/README | 2 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/latex/translations/translations_en.pdf | bin | 152864 -> 194428 bytes | |||
| -rw-r--r-- | Master/texmf-dist/doc/latex/translations/translations_en.tex | 219 |
3 files changed, 151 insertions, 70 deletions
diff --git a/Master/texmf-dist/doc/latex/translations/README b/Master/texmf-dist/doc/latex/translations/README index 56a547c7002..1b1a82fd8c1 100644 --- a/Master/texmf-dist/doc/latex/translations/README +++ b/Master/texmf-dist/doc/latex/translations/README @@ -1,5 +1,5 @@ -------------------------------------------------------------------------- -the TRANSLATIONS package v1.0 - 2013/07/16 +the TRANSLATIONS package v1.1 - 2013/08/05 a simple translator -------------------------------------------------------------------------- diff --git a/Master/texmf-dist/doc/latex/translations/translations_en.pdf b/Master/texmf-dist/doc/latex/translations/translations_en.pdf Binary files differindex 894f586651e..690067aac50 100644 --- a/Master/texmf-dist/doc/latex/translations/translations_en.pdf +++ b/Master/texmf-dist/doc/latex/translations/translations_en.pdf diff --git a/Master/texmf-dist/doc/latex/translations/translations_en.tex b/Master/texmf-dist/doc/latex/translations/translations_en.tex index 5a368411a0b..07a7e077e24 100644 --- a/Master/texmf-dist/doc/latex/translations/translations_en.tex +++ b/Master/texmf-dist/doc/latex/translations/translations_en.tex @@ -45,15 +45,15 @@ \docsetup{ pkg = {translations} , repo = github , - subtitle = {a simple translator} , + subtitle = {internationalization of \LaTeXe\ packages} , language = en , modules = true , code-box = { - backgroundcolor = gray!7!white , skipbelow = .6\baselineskip plus .5ex minus .5ex , skipabove = .6\baselineskip plus .5ex minus .5ex , innerleftmargin = 1.5em , - innerrightmargin = 2.5em + innerrightmargin = 2.5em , + roundcorner = 3pt } , gobble = 1 } @@ -67,6 +67,17 @@ \ChangeEmph{[}[,.02em]{]}[.055em,-.08em] \ChangeEmph{(}[-.01em,.04em]{)}[.04em,-.05em] \usepackage{microtype} +\SetTracking[spacing={75*,166,}]{ + encoding = *, + shape = sc , + family = rm* +}{75} +\SetTracking[spacing={50*,166,}]{ + encoding = *, + shape = sc , + family = sf* +}{50} + \usepackage[multiple]{fnpct} \renewcommand*\othersectionlevelsformat[3]{\textcolor{main}{#3\autodot}\enskip} @@ -79,6 +90,7 @@ \setkomafont{captionlabel}{\normalfont\footnotesize\sffamily\scshape} \usepackage{booktabs,array,ragged2e} +\usepackage[sort]{cleveref} % ---------------------------------------------------------------------------- % code examples @@ -144,8 +156,8 @@ \newlength\nodewidth \setlength\nodewidth{.375\linewidth} -\long\def\yes:{\textcolor{green}{\CheckmarkBold}\par} -\long\def\no:{\textcolor{red}{\XSolidBrush}\par} +\long\def\yes:{\centering\textcolor{green}{\CheckmarkBold}\par} +\long\def\no:{\centering\textcolor{red}{\XSolidBrush}\par} \protected\def\fnote#1{\textsuperscript{#1}} \pdfstringdefDisableCommands{\def\llap#1{#1\space}\def\bigstar{*}} @@ -158,12 +170,13 @@ internationalization of their packages. The functionality of this package is in many parts also covered by the package \paket*{translator} (part of the \paket{beamer} bundle). Internationalization is also possible with \paket{babel} and it's \cmd*{addto}\cmd{captions<language>} mechanism or -\KOMAScript's \cmd{providecaptionname}. However, I believe that -\translations\ is more flexible than all of these. Unlike \paket*{translator} -it detects the used (\paket{babel} or \paket{polyglossia}) language itself and -provides expandable retrieving of the translated key. \translations\ also -provides support for language dialects which means package authors can for -example distinguish between British, Australian, Canadian and US English. +\KOMAScript's \cmd{providecaptionname} and similar commands. However, I +believe that \translations\ is more flexible than all of these. Unlike +\paket*{translator} it detects the used (\paket{babel} or \paket{polyglossia}) +language itself and provides expandable retrieving of the translated key. +\translations\ also provides support for language dialects which means package +authors can for example distinguish between British, Australian, Canadian and +US English. The first draft of the package was written since I missed an expandable version of \paket{translator}'s \cmd{translate} command. Once I had the @@ -183,22 +196,22 @@ It has the status ``maintained.'' \section{Usage}\secidx{Usage} \subsection{Background}\secidx[Background]{Usage} The \translations\ package enables the author of a package or a class (or a -document) to declare translations in different languages of key words and +document) to declare translations of key words in different languages and fetch these translations in the document depending on the active language as set by \paket{babel} or \paket{polyglossia}. Since \translations\ checks -which language is active it is generally not necessary to specify the language -for which a translation should be fetched manually. +which language is active it is generally not necessary (although possible) to +specify the language for which a translation should be fetched manually. \translations\ knows of three types of languages: main languages (see -table~\ref{tab:languages} on page~\pageref{tab:languages}), language aliases -(see table~\ref{tab:aliases} on page~\pageref{tab:aliases}) and language -dialects (see table~\ref{tab:dialects} on page~\pageref{tab:dialects}). For -the commands declaring or fetching a translation base languages and language -aliases are equivalent. Dialects are similar to aliases but there are a few -important differences. +\cref{tab:languages} on \cpageref{tab:languages}), language dialects (see +\cref{tab:dialects} on \cpageref{tab:dialects}), and language aliases (see +\cref{tab:aliases} on \cpageref{tab:aliases}). For the commands declaring or +fetching a translation base languages and language aliases are equivalent. +Dialects are similar to aliases but there are important differences. An alias +can for example be an alias of a dialect. -Figure~\ref{fig:scheme} shows what happens if \translations\ is asked to fetch -a translation for a given key. +\Cref{fig:scheme} shows what happens if \translations\ is asked to fetch a +translation for a given key. \begin{figure}[htbp] \centering @@ -252,17 +265,19 @@ a translation for a given key. \label{fig:scheme} \end{figure} -What happens if you declare a translation? There are three cases: +What happens if you declare a translation? There are four cases: \begin{enumerate} \item You declare a translation for a base language: this is the normal case where an internal macro is defined which can be fetched by the - \cmd{GetTranslation} command (see section~\ref{ssec:commands}). + \cmd{GetTranslation} command (see \cref{ssec:commands}). \item You declare a translation for a language alias: this is the very same as the first case since the same internal macro is defined. \item You declare a translation for a dialect: this is two-fold. Either a translation for the base language exists so only the translation for the dialect is saved. If the translation for the base language does not exist it is defined to be the same as the one for the dialect. + \item You declare a translation for an alias of a dialect: this is the very + same as the third case as again the internal macros are the same. \end{enumerate} \subsection{Available Commands}\label{ssec:commands}\secidx[Commands]{Usage} @@ -271,18 +286,27 @@ Below the commands provided by \translations\ are explained. The symbol isn't. \begin{beschreibung} \Befehl{DeclareLanguage}{<lang>}\newline - Declare a language that can be used by \translations. If the language - already exists it will be silently redefined. This command can only be used - in the preamble. + Declare a language that can be used by \translations. If the language + already exists it will be silently redefined. This command can only be + used in the preamble. It should never be necessary to use this command as + \translations\ already declares loads of languages (\cref{sec:languages}). + Should you miss one please send me an email and I'll add it to + \translations. \Befehl{DeclareLanguageAlias}{<lang2>}\ma{<lang1>}\newline - Declares \code{<lang2>} to be an alias of \code{<lang1>}. If \code{<lang1>} - doesn't exist yet a warning will be raised and it will be defined. This - command can only be used in the preamble. + Declares \code{<lang2>} to be an alias of \code{<lang1>}. If \code{<lang1>} + doesn't exist yet a warning will be raised and it will be defined. This + command can only be used in the preamble. It should never be necessary to + use this command as \translations\ already declares loads of languages + (\cref{sec:languages}). Should you miss one please send me an email and + I'll add it to \translations. \Befehl{DeclareLanguageDialect}{<dialect>}\ma{<lang>}\newline - Declares \code{<dialect>} to be a dialect of language \code{<lang>}. If a + Declares \code{<dialect>} to be a dialect of language \code{<lang>}. If a translation for \code{<dialect>} is provided it is used by the translation - macros. If there is none the corresponding translation for \code{<lang>} is - used instead. + macros. If there is none the corresponding translation for \code{<lang>} + is used instead. It should never be necessary to use this command as + \translations\ already declares loads of languages (\cref{sec:languages}). + Should you miss one please send me an email and I'll add it to + \translations. \Befehl{NewTranslation}{<lang>}\ma{<key>}\ma{<translation>}\newline Defines a translation of key \code{<key>} for the language \code{<lang>}. An error will be raised if a translation of \code{<key>} already exists. @@ -305,15 +329,36 @@ isn't. \code{<lang>}. This command is expandable. \expandable\Befehl{GetTranslation}{<key>}\newline Fetches and prints the translation of \code{<key>} for the currently active - language (as for example set by \paket{babel}). This command is expandable. + language (as for example set by \paket{babel}). This command is + expandable. + \expandable\Befehl{GetLCTranslationFor}{<lang>}\ma{<key>}\newline + \sinceversion{1.1}Fetches and prints the translation of \code{<key>} for + the language \code{<lang>}. This command ensures that the fetched + translation is set lowercase. This command is expandable. + \expandable\Befehl{GetLCTranslation}{<key>}\newline + \sinceversion{1.1}Fetches and prints the translation of \code{<key>} for + the currently active language (as for example set by \paket{babel}). This + command ensures that the fetched translation is set lowercase. This + command is expandable. \Befehl{GetTranslationForWarn}{<lang>}\ma{<key>}\newline \sinceversion{1.0}Fetches and prints the translation of \code{<key>} for the language \code{<lang>}. Issues a warning if no translation is - available. + available at the cost of expandability. \Befehl{GetTranslationWarn}{<key>}\newline \sinceversion{1.0}Fetches and prints the translation of \code{<key>} for the currently active language (as for example set by \paket{babel}). - Issues a warning if no translation is available. + Issues a warning if no translation is available at the cost of + expandability. + \Befehl{GetLCTranslationForWarn}{<lang>}\ma{<key>}\newline + \sinceversion{1.1}Fetches and prints the translation of \code{<key>} for + the language \code{<lang>}. This command ensures that the fetched + translation is set lowercase. Issues a warning if no translation is + available at the cost of expandability. + \Befehl{GetLCTranslationWarn}{<key>}\newline + \sinceversion{1.1}Fetches and prints the translation of \code{<key>} for + the currently active language (as for example set by \paket{babel}). This + command ensures that the fetched translation is set lowercase. Issues a + warning if no translation is available at the cost of expandability. \Befehl{SaveTranslationFor}{<cmd>}\ma{<lang>}\ma{<key>}\newline Fetches and saves the translation of \code{<key>} for the language \code{<lang>} in the macro \code{<cmd>}. @@ -323,13 +368,13 @@ isn't. \Befehl{LoadDictionary}{<name>}\newline Loads a file named \code{<name>-<lang>.trsl} where \code{<lang>} corresponds to the lowercase name of the current language as defined with - \cmd{DeclareLanguage}. This file should contain the translations for the + \cmd{DeclareLanguage}. This file should contain the translations for the specified language. \Befehl{LoadDictionaryFor}{<lang>}\ma{<name>}\newline Loads a file named \code{<name>-<lang>.trsl}. \Befehl{DeclareDictTranslation}{<key>}\ma{<translation>}\newline This command is to be used in a dictionary file and picks up the language - of that file, see section~\ref{sec:dictionaries} for an example. + of that file, see \cref{sec:dictionaries} for an example. \Befehl{ProvideDictionaryFor}{<lang>}\ma{<name>}\oa{<date>}\newline Needs to be in a dictionary file. This command tells \translations\ that the file indeed is a dictionary and also sets the language for the @@ -339,12 +384,18 @@ isn't. language \code{<lang>} in the order the entries have been declared. For every entry the code\par \code{<pre><key><mid><translation><post>}\par - is printed. The dictionary must have been loaded of course. + is printed. The dictionary must have been loaded of course. This may be + of minor use but was used to print \cref{tab:dict}. + \expandable\Befehl{baselanguage}{<lang>}\newline + \sinceversion{1.1}Returns the (internal) base name of the given language, + language alias or language dialect. For a base language + (see section~\ref{ssec:languages:base}) this usually simply is the + lowercase version of the name. \end{beschreibung} \subsection{A Small Example}\secidx[Example]{Usage} This section demonstrates with two short examples how the macros are used. -The first example covers the basics: dlaring of translations and then +The first example covers the basics: declaring of translations and then retrieving and typesetting them. \begin{beispiel} @@ -461,8 +512,7 @@ files \code{translations-basic-dictionary-<lang>.trsl} and modify the file accordingly. You can then send me the file via email and I'll add it to \translations. -Table~\ref{tab:dict} lists all words provided by the basic dictionary for -German. +\Cref{tab:dict} lists all words provided by the basic dictionary for German. \begin{longtable}{ll} \caption{All entries of \translations' basic dictionary in German.\label{tab:dict}} \\ @@ -486,37 +536,55 @@ German. \secidx*{Usage} \section{Defined Languages}\label{sec:languages}\secidx{Languages} +\subsection{Base Languages}\label{ssec:languages:base} Quite a number of languages already are defined, either directly or via an alias. So, before you define a language you should take a look at the tables -below if the language doesn't already exist. Table~\ref{tab:languages} lists -all base languages, ``fallback'' being a dummy language used for fallback -translations. +below if the language doesn't already exist. \Cref{tab:languages} lists all +base languages, ``fallback'' being a dummy language used for fallback +translations. \Cref{tab:languages,tab:dialects,tab:aliases} list \emph{all} +language names known to \translations. However, they're not sorted +alphabetically but listed in the order they have been defined. I tried to +make the definitions in an alphabetical order but sometimes rather grouped +related language names together. + +If you miss a language or recognize a language that has falsely been declared +as an alias but should rather be a dialect or base language itself (or any +variation of this theme) please let me know, preferably with a short +explanation what's wrong and why. \newcounter{column} \gdef\seplang{% \stepcounter{column}% - \ifnumless{\value{column}}{4} + \ifnumless{\value{column}}{5} {&} {\\\setcounter{column}{0}}% } \def\do#1{#1\seplang} \makeatletter -\begin{longtable}{llll} - \caption{Base languages defines by \translations.\label{tab:languages}} \\ +\begin{longtable}{lllll} + \caption{Base languages defined by \translations, from left to right in + the order of definition.\label{tab:languages}} \\ + \toprule + \endfirsthead \toprule \endhead \bottomrule \endlastfoot \midrule - &&& \hfill\emph{continues} \\ + &&&& \hfill\emph{continues} \\ \endfoot \dolistloop\@trnslt@languages \end{longtable} \makeatother -To every one of these languages at least one alias exists, the uppercase -variant. This is due to the fact that it is common to write language names -uppercased. All defined aliases are listed in table~\ref{tab:aliases}. +\subsection{Language Dialects}\label{ssec:languages:dialects} +\translations\ also defines a few dialects of thebase languages. They are +listed in \cref{tab:dialects}. The decision what is a dialect and what is an +alias is not always clear. I am no linguist so I looked up information +available on the internet. A language that was described as +\enquote{standardized register} was always defined as a dialect. For some +other languages it seemed to make sense, such as British or Austrian. The +decisions are open for debate. \setcounter{column}{0} \gdef\seplang{% @@ -531,15 +599,16 @@ uppercased. All defined aliases are listed in table~\ref{tab:aliases}. \def\do#1{\aliases#1} \makeatletter \begin{longtable}{ll@{\hspace*{4em}}ll} - \caption{All language aliases defined by \translations.\label{tab:aliases}}\\ + \caption{All dialects defined by \translations, from left to right in the + order of definition.\label{tab:dialects}}\\ \toprule - \bfseries alias & \bfseries language & - \bfseries alias & \bfseries language \\ + \bfseries dialect & \bfseries language & + \bfseries dialect & \bfseries language \\ \midrule \endfirsthead \toprule - \bfseries alias & \bfseries language & - \bfseries alias & \bfseries language \\ + \bfseries dialect & \bfseries language & + \bfseries dialect & \bfseries language \\ \midrule \endhead \bottomrule @@ -547,24 +616,34 @@ uppercased. All defined aliases are listed in table~\ref{tab:aliases}. \midrule &&& \hfill\emph{continues} \\ \endfoot - \dolistloop\@trnslt@aliases@pair + \dolistloop\@trnslt@dialects@pair \end{longtable} \makeatother -\translations\ also defines a few dialects. They are listed in -table~\ref{tab:dialects}. +\subsection{Language Aliases}\label{ssec:languages:aliases} +To most of the base languages and dialects at least one alias exists, the +uppercase variant. This is due to the fact that it is common to write +language names uppercased. For a number of languages aliases were defined in +order to match \paket{babel}'s or \paket{polyglossia}'s names for the +languages. Others are defined because there apparently exist more than one +name for the same language. The decisions are not consistent. For example it +could be argued that \enquote{deutsch} is an alias of \enquote{German}. I am +open to suggestions and improvements. All defined aliases are listed in +\cref{tab:aliases}. +\setcounter{column}{0} \makeatletter \begin{longtable}{ll@{\hspace*{4em}}ll} - \caption{All dialects defined by \translations.\label{tab:dialects}}\\ + \caption{All language aliases defined by \translations, from left to right + in the order of definition.\label{tab:aliases}}\\ \toprule - \bfseries dialect & \bfseries language & - \bfseries dialect & \bfseries language \\ + \bfseries alias & \bfseries language & + \bfseries alias & \bfseries language \\ \midrule \endfirsthead \toprule - \bfseries dialect & \bfseries language & - \bfseries dialect & \bfseries language \\ + \bfseries alias & \bfseries language & + \bfseries alias & \bfseries language \\ \midrule \endhead \bottomrule @@ -572,18 +651,20 @@ table~\ref{tab:dialects}. \midrule &&& \hfill\emph{continues} \\ \endfoot - \dolistloop\@trnslt@dialects@pair + \dolistloop\@trnslt@aliases@pair \end{longtable} \makeatother \secidx*{Languages} -These languages should cover all languages which are currently covered by -\paket{babel} and \paket{polyglossia}. +These languages \emph{should} cover all languages which are currently covered +by \paket{babel} and \paket{polyglossia} but very likely this is not the +case. Should you miss a language please send me an email so I can add it to +\translations. \section{Implementation}\index{Implementation@\textbf{Implementation}} In the following code the lines 1--30 have been omitted. They only repeat the -license statement which has already been mentioned in section~\ref{sec:license}. +license statement which has already been mentioned in \cref{sec:license}. \implementation[linerange={31-1000},firstnumber=31] |