summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/exsheets/translations_en.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/latex/exsheets/translations_en.tex')
-rw-r--r--Master/texmf-dist/doc/latex/exsheets/translations_en.tex99
1 files changed, 79 insertions, 20 deletions
diff --git a/Master/texmf-dist/doc/latex/exsheets/translations_en.tex b/Master/texmf-dist/doc/latex/exsheets/translations_en.tex
index 81dd771c158..5d7f0feaf46 100644
--- a/Master/texmf-dist/doc/latex/exsheets/translations_en.tex
+++ b/Master/texmf-dist/doc/latex/exsheets/translations_en.tex
@@ -131,8 +131,8 @@
\DeclareTranslation{German}{Kueche}{K\"uche}
\DeclareTranslation{Spanish}{Kueche}{cocina}
\DeclareTranslation{French}{Kueche}{cuisine}
-\DeclareTranslation{English}{foo}{foo}
-\DeclareTranslation{British}{foo}{bar}
+\DeclareTranslation{English}{farbe}{color}
+\DeclareTranslation{British}{farbe}{colour}
% ----------------------------------------------------------------------------
% custom commands
@@ -187,12 +187,17 @@
\begin{document}
\section{Motivation}\secidx{Motivation}
-I wrote this package when I was in need for an expandable version of
-\paket*{translator}'s \cmd{translate}. If you don't need that then there is
-very likely no need whatsoever for this package as \paket*{translator} from the
-\paket{beamer} bundle provides very similar functionality \translations does
-(except for: \paket{translator}'s \cmd{translate} isn't expandable,
-\cmd{GetTranslation} is.).
+This package provides means for package authors to have an easy interface for
+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 distinguish
+between British, Australian, Canadian and US English, say.
\secidx*{Motivation}
\section{License and Requirements}\label{sec:license}\secidx{Requirements}
@@ -261,11 +266,14 @@ means that the command is expandable, \unexpsign{} means that it isn't.
of that file, see section~\ref{sec:dictionaries} for an example.
\end{beschreibung}
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 in \code{translations.sty}
-if the language doesn't already exist.
+So, before you define a language you should take a look at
+section~\ref{sec:languages} if the language doesn't already exist.
\subsection{A Small Example}
-Here is a small example of usage:
+This section demonstrates with two short examples how the macros are used.
+The first example covers the basics: dlaring of translations and then
+retrieving and typesetting them.
+
\begin{beispiel}
% in the preamble:
% \DeclareTranslation{English}{Kueche}{kitchen}
@@ -282,18 +290,21 @@ Here is a small example of usage:
\cuisine
\end{beispiel}
-There is also support for dialects:
+The next example demonstrates the use of dialects and how they fall back to
+the translation for the main language if no extra translation was declared:
+
\begin{beispiel}
% in the preamble:
- % \DeclareTranslation{English}{foo}{foo}
- % \DeclareTranslation{British}{foo}{bar}
- \GetTranslationFor{English}{foo} \\
- \GetTranslationFor{British}{foo} \\
- \GetTranslationFor{American}{foo}
+ % \DeclareTranslation{English}{farbe}{color}
+ % \DeclareTranslation{British}{farbe}{colour}
+
+ \GetTranslationFor{English}{farbe} \\
+ \GetTranslationFor{British}{farbe} \\
+ \GetTranslationFor{American}{farbe}
\end{beispiel}
\subsection{Usage in Packages}
-In package a typical usage in a package would look as follows:
+A typical usage in a package would look as follows:
\begin{beispiel}[code only]
\RequirePackage{translations}
\DeclareTranslationFallback{mypackage-title}{Nice Title}
@@ -304,6 +315,11 @@ In package a typical usage in a package would look as follows:
\def\mypackage@title{\GetTranslation{mypackage-title}}
\end{beispiel}
+That is, a package defines some unique key for an expression and at least
+defines a fallback translation. Additionally translations for as many
+languages as the author wants are defined. A user then may add
+\cmd{DeclareTranslation}\ma{<language>}\ma{<translation>} if they find their
+translation missing.
\subsection{Dictionaries}\label{sec:dictionaries}
A typical dictionary file should look as follows:
@@ -318,9 +334,52 @@ A typical dictionary file should look as follows:
\endinput
\end{beispiel}
+The usage is similar to the one in a package: unique keys are given
+translations, this time for the language the dictionary file is declared for
+only.
+
\secidx*{Usage}
-\section{Implementation}
+\section{Defined Languages}\label{sec:languages}\secidx{Languages}
+\translations currently has these languages defined, ``fallback'' being a
+dummy language used for fallback translations:
+
+\begin{quote}
+ \makeatletter\raggedright
+ \def\comma{\gdef\comma{,\quad}}%
+ \def\do#1{\comma #1}%
+ \dolistloop\@trnslt@languages
+\end{quote}
+
+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. The defined aliases are these (in parentheses the base language
+name is given):
+
+\begin{quote}
+ \makeatletter\raggedright
+ \def\comma{\gdef\comma{,\quad}}
+ \def\aliases#1#2{\comma #1 (#2)}
+ \def\do#1{\aliases#1}
+ \dolistloop\@trnslt@aliases@pair
+\end{quote}
+
+\translations also defines a few dialects. The language to which the dialect
+belongs to is given in paretheses:
+
+\begin{quote}
+ \makeatletter\raggedright
+ \def\comma{\gdef\comma{,\quad}}
+ \def\aliases#1#2{\comma #1 (#2)}
+ \def\do#1{\aliases#1}
+ \dolistloop\@trnslt@dialects@pair
+\end{quote}
+\secidx*{Languages}
+
+These languages should cover all languages which are currently covered by
+\paket{babel} and \paket{polyglossia}.
+
+\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}.
@@ -332,4 +391,4 @@ license statement which has already been mentioned in section~\ref{sec:license}.
\printindex
-\end{document} \ No newline at end of file
+\end{document}