summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/translations
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2014-01-10 23:26:30 +0000
committerKarl Berry <karl@freefriends.org>2014-01-10 23:26:30 +0000
commit01fb7e7a68abc42696057c8522cd90d8e7bbf14d (patch)
tree791ffc6d0160af438caa7cc6473316ae7c0daef2 /Master/texmf-dist/doc/latex/translations
parent1a6ebf01dcfbaa320337c0dd0242ec7064b21a6b (diff)
translations (10jan14)
git-svn-id: svn://tug.org/texlive/trunk@32632 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/latex/translations')
-rw-r--r--Master/texmf-dist/doc/latex/translations/README4
-rw-r--r--Master/texmf-dist/doc/latex/translations/translations_en.pdfbin525149 -> 545580 bytes
-rw-r--r--Master/texmf-dist/doc/latex/translations/translations_en.tex404
3 files changed, 258 insertions, 150 deletions
diff --git a/Master/texmf-dist/doc/latex/translations/README b/Master/texmf-dist/doc/latex/translations/README
index 3879148bda4..5f3ea1f9a87 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.1a - 2013/09/30
+the TRANSLATIONS package v1.2 - 2013/01/10
a simple translator
--------------------------------------------------------------------------
@@ -7,7 +7,7 @@ Clemens Niederberger
Web: https://github.com/cgnieder/translations/
E-Mail: contact@mychemistry.eu
--------------------------------------------------------------------------
-Copyright 2011-2013 Clemens Niederberger
+Copyright 2011-2014 Clemens Niederberger
This work may be distributed and/or modified under the
conditions of the LaTeX Project Public License, either version 1.3
diff --git a/Master/texmf-dist/doc/latex/translations/translations_en.pdf b/Master/texmf-dist/doc/latex/translations/translations_en.pdf
index a15a4d684b8..92502d730b5 100644
--- a/Master/texmf-dist/doc/latex/translations/translations_en.pdf
+++ b/Master/texmf-dist/doc/latex/translations/translations_en.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/latex/translations/translations_en.tex b/Master/texmf-dist/doc/latex/translations/translations_en.tex
index a7ed58655cc..51fc69d6412 100644
--- a/Master/texmf-dist/doc/latex/translations/translations_en.tex
+++ b/Master/texmf-dist/doc/latex/translations/translations_en.tex
@@ -1,4 +1,4 @@
-% arara: pdflatex
+% arara: pdflatex: { shell: on }
% arara: biber
% arara: pdflatex
% arara: pdflatex
@@ -12,7 +12,7 @@
% Web: https://github.com/cgnieder/translations/
% E-Mail: contact@mychemistry.eu
% --------------------------------------------------------------------------
-% Copyright 2011-2013 Clemens Niederberger
+% Copyright 2011-2014 Clemens Niederberger
%
% This work may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either version 1.3
@@ -41,6 +41,8 @@
url = https://github.com/cgnieder/translations/ ,
info = {Internationalization of \LaTeXe\ Packages} ,
add-cmds = {
+ baselanguage,
+ baselanguagename,
DeclareDictTranslation,
DeclareLanguage,
DeclareLanguageAlias,
@@ -53,6 +55,7 @@
LoadDictionaryFor,
NewTranslation,
ProvideDictionaryFor,
+ ProvideDictTranslation,
RenewTranslation,
SaveTranslation,
SaveTranslationFor
@@ -106,16 +109,17 @@
\section{Motivation}
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 \pkg{translator} (part of the
-\pkg*{beamer} bundle). Internationalization is also possible with
-\pkg{babel}~\cite{pkg:babel} and it's \cs*{addto}\cs*{captions\meta{language}}
-mechanism or \KOMAScript's \cs*{providecaptionname} and similar commands.
-However, I believe that \translations\ is more flexible than all of these.
-Unlike \pkg{translator} it detects the used (\pkg{babel} or
-\pkg{polyglossia}~\cite{pkg: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.
+in many parts also covered by the package
+\pkg{translator}~\cite{pkg:translator} (part of the \pkg*{beamer} bundle).
+Internationalization is also possible with \pkg{babel}~\cite{pkg:babel} and
+it's \cs*{addto}\cs*{captions\meta{language}} mechanism or \KOMAScript's
+\cs*{providecaptionname} and similar commands. However, I believe that
+\translations\ is more flexible than all of these. Unlike \pkg{translator} it
+detects the used (\pkg{babel} or \pkg{polyglossia}~\cite{pkg: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 \pkg{translator}'s \cs*{translate} command. Once I had the
@@ -126,9 +130,9 @@ extended to the needs I faced there.
\section{License and Requirements}\label{sec:license}
\license
-\translations\ requires the packages
-\needpackage{etoolbox}~\cite{pkg:etoolbox} and \pkg*{scrlfile} (part of the
-\KOMAScript\ bundle\footnote{\CTANurl{koma-script}}~\cite{pkg:koma-script}).
+\translations\ requires the packages \pkg{cnltx-base} from the \bnd{cnltx}
+bundle~\cite{bnd:cnltx} and \pkg{scrlfile} (part of the \KOMAScript\
+bundle~\cite{bnd:koma-script}).
\section{Usage}
@@ -167,33 +171,33 @@ translation for a given key.
\node {check if any\fnote{a} translation is defined in given language}
child {
node[text width=\nodewidth]
- {\yes\ check if language is a dialect}
+ {\yes check if language is a dialect}
child {
node[text width=\nodewidth/2]
- {\yes\ check if dialect translation is given}
+ {\yes check if dialect translation is given}
child {
node[text width=\nodewidth/2.75]
- {\yes\ use dialect translation}
+ {\yes use dialect translation}
}
child {
node[text width=\nodewidth/2.75]
- {\no\ use lan\-guage\fnote{b} translation}
+ {\no use lan\-guage\fnote{b} translation}
}
}
child {
node[text width=\nodewidth/2]
- {\no\ use translation}}
+ {\no use translation}}
}
child {
node[text width=\nodewidth]
- {\no\ check if fallback translation is given}
+ {\no check if fallback translation is given}
child {
node[text width=\nodewidth/2.75]
- {\yes\ use fallback translation}
+ {\yes use fallback translation}
}
child {
node[text width=\nodewidth/2.75]
- {\no\ use literal key}
+ {\no use literal key}
}
} ;
\end{tikzpicture}
@@ -224,112 +228,158 @@ Below the commands provided by \translations\ are explained. The symbol
Commands without the marker aren't expandable.
\begin{commands}
- \command{DeclareLanguage}[\marg{lang}]
- 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.
- \command{DeclareLanguageAlias}[\marg{lang2}\marg{lang1}]
- Declares \meta{lang2} to be an alias of \meta{lang1}. If \meta{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.
- \command{DeclareLanguageDialect}[\marg{dialect}\marg{lang}]
- Declares \meta{dialect} to be a dialect of language \meta{lang}. If a
- translation for \meta{dialect} is provided it is used by the translation
- macros. If there is none the corresponding translation for \meta{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.
- \command{NewTranslation}[\marg{lang}\marg{key}\marg{translation}]
- Defines a translation of key \meta{key} for the language \meta{lang}.
- An error will be raised if a translation of \meta{key} already exists.
- This command can only be used in the preamble.
- \command{RenewTranslation}[\marg{lang}\marg{key}\marg{translation}]
- Redefines a translation of key \meta{key} for the language \meta{lang}.
- An error will be raised if no translation of \meta{key} exists.
- This command can only be used in the preamble.
- \command{DeclareTranslation}[\marg{lang}\marg{key}\marg{translation}]
- Defines a translation of key \meta{key} for the language \meta{lang}.
- No error will be raised if a translation of \meta{key} already exists.
- This command can only be used in the preamble.
- \command{DeclareTranslationFallback}[\marg{key}\marg{fallback}]
- Defines a fallback translation for key \meta{key} that is used in case no
- translation of \meta{key} for the currently active language has been
- provided. No error will be raised if a fallback for \meta{key} already
- exists. This command can only be used in the preamble.
- \expandable\command{GetTranslationFor}[\marg{lang}\marg{key}]
- Fetches and prints the translation of \meta{key} for the language
- \meta{lang}. This command is expandable.
- \expandable\command{GetTranslation}[\marg{key}]
- Fetches and prints the translation of \meta{key} for the currently active
- language (as for example set by \pkg{babel}). This command is expandable.
- \expandable\command{GetLCTranslationFor}[\marg{lang}\marg{key}]
- \sinceversion{1.1}Fetches and prints the translation of \meta{key} for
- the language \meta{lang}. This command ensures that the fetched
- translation is set lowercase. This command is expandable.
- \expandable\command{GetLCTranslation}[\marg{key}]
- \sinceversion{1.1}Fetches and prints the translation of \meta{key} for
- the currently active language (as for example set by \pkg{babel}). This
- command ensures that the fetched translation is set lowercase. This
- command is expandable.
- \command{GetTranslationForWarn}[\marg{lang}\marg{key}]
- \sinceversion{1.0}Fetches and prints the translation of \meta{key} for
- the language \meta{lang}. Issues a warning if no translation is
- available at the cost of expandability.
- \command{GetTranslationWarn}[\marg{key}]
- \sinceversion{1.0}Fetches and prints the translation of \meta{key} for
- the currently active language (as for example set by \pkg{babel}).
- Issues a warning if no translation is available at the cost of
- expandability.
- \command{GetLCTranslationForWarn}[\marg{lang}\marg{key}]
- \sinceversion{1.1}Fetches and prints the translation of \meta{key} for
- the language \meta{lang}. This command ensures that the fetched
- translation is set lowercase. Issues a warning if no translation is
- available at the cost of expandability.
- \command{GetLCTranslationWarn}[\marg{key}]
- \sinceversion{1.1}Fetches and prints the translation of \meta{key} for
- the currently active language (as for example set by \pkg{babel}). This
- command ensures that the fetched translation is set lowercase. Issues a
- warning if no translation is available at the cost of expandability.
- \command{SaveTranslationFor}[\marg{cmd}\marg{lang}\marg{key}]
- Fetches and saves the translation of \meta{key} for the language
- \meta{lang} in the macro \meta{cmd}.
- \command{SaveTranslation}[\marg{cmd}\marg{key}]
- Fetches and saves the translation of \meta{key} for the currently active
- language (as for example set by \pkg{babel}) in the macro \meta{cmd}.
- \command{LoadDictionary}[\marg{name}]
- Loads a file named \code{\meta{name}-\meta{lang}.trsl} where \meta{lang}
- corresponds to the lowercase name of the current language as defined with
- \cs{DeclareLanguage}. This file should contain the translations for the
- specified language.
- \command{LoadDictionaryFor}[\marg{lang}\marg{name}]
- Loads a file named \code{\meta{name}-\meta{lang}.trsl}.
- \command{DeclareDictTranslation}[\marg{key}\marg{translation}]
- This command is to be used in a dictionary file and picks up the language
- of that file, see \cref{sec:dictionaries} for an example.
- \command{ProvideDictionaryFor}[\marg{lang}\marg{name}\oarg{date}]
- 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
- dictionary which is used by \cs{DeclareDictTranslation}.
- \expandable\command{PrintDictionaryFor}%
- [\marg{lang}\marg{name}\marg{pre}\marg{mid}\marg{post}]
- \sinceversion{1.0}Prints all entries of dictionary \meta{name} in
- language \meta{lang} in the order the entries have been declared. For
- every entry the code\par
- \meta{pre}\meta{key}\meta{mid}\meta{translation}\meta{post}\par
- 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\command{baselanguage}[\marg{lang}]
- \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.
+ \command{DeclareLanguage}[\marg{lang}]
+ 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.
+ \command{DeclareLanguageAlias}[\marg{lang2}\marg{lang1}]
+ Declares \meta{lang2} to be an alias of \meta{lang1}. If \meta{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.
+ \command{DeclareLanguageDialect}[\marg{dialect}\marg{lang}]
+ Declares \meta{dialect} to be a dialect of language \meta{lang}. If a
+ translation for \meta{dialect} is provided it is used by the translation
+ macros. If there is none the corresponding translation for \meta{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.
+ \command{NewTranslation}[\marg{lang}\marg{key}\marg{translation}]
+ Defines a translation of key \meta{key} for the language \meta{lang}.
+ An error will be raised if a translation of \meta{key} already exists.
+ This command can only be used in the preamble.
+ \command{RenewTranslation}[\marg{lang}\marg{key}\marg{translation}]
+ Redefines a translation of key \meta{key} for the language \meta{lang}.
+ An error will be raised if no translation of \meta{key} exists.
+ This command can only be used in the preamble.
+ \command{ProvideTranslation}[\marg{lang}\marg{key}\marg{translation}]
+ \sinceversion{1.2}Provides a translation of key \meta{key} for the
+ language \meta{lang}. If a translation of \meta{key} already exists it
+ won't be overwritten and no error will be raised. This command can only
+ be used in the preamble.
+ \command{DeclareTranslation}[\marg{lang}\marg{key}\marg{translation}]
+ Defines a translation of key \meta{key} for the language \meta{lang}.
+ No error will be raised if a translation of \meta{key} already exists.
+ This command can only be used in the preamble.
+ \command{DeclareTranslationFallback}[\marg{key}\marg{fallback}]
+ Defines a fallback translation for key \meta{key} that is used in case no
+ translation of \meta{key} for the currently active language has been
+ provided. No error will be raised if a fallback for \meta{key} already
+ exists. This command can only be used in the preamble.
+ \expandable\command{GetTranslationFor}[\marg{lang}\marg{key}]
+ Fetches and prints the translation of \meta{key} for the language
+ \meta{lang}. This command is expandable.
+ \expandable\command{GetTranslation}[\marg{key}]
+ Fetches and prints the translation of \meta{key} for the currently active
+ language (as for example set by \pkg{babel}). This command is expandable.
+ \expandable\command{GetLCTranslationFor}[\marg{lang}\marg{key}]
+ \sinceversion{1.1}Fetches and prints the translation of \meta{key} for
+ the language \meta{lang}. This command ensures that the fetched
+ translation is set lowercase. This command is expandable (well, sort
+ of: in an \cs*{edef} it leaves \cs*{lowercase}\marg{translation} in the
+ input stream where \meta{translation} is what \cs{GetTranslationFor} would
+ expand to).
+ \expandable\command{GetLCTranslation}[\marg{key}]
+ \sinceversion{1.1}Fetches and prints the translation of \meta{key} for
+ the currently active language (as for example set by \pkg{babel}). This
+ command ensures that the fetched translation is set lowercase. This
+ command is expandable (well, sort of: in an \cs*{edef} it leaves
+ \cs*{lowercase}\marg{translation} in the input stream where
+ \meta{translation} is what \cs{GetTranslation} would expand to).
+ \command{GetTranslationForWarn}[\marg{lang}\marg{key}]
+ \sinceversion{1.0}Fetches and prints the translation of \meta{key} for
+ the language \meta{lang}. Issues a warning if no translation is
+ available at the cost of expandability.
+ \command{GetTranslationWarn}[\marg{key}]
+ \sinceversion{1.0}Fetches and prints the translation of \meta{key} for
+ the currently active language (as for example set by \pkg{babel}).
+ Issues a warning if no translation is available at the cost of
+ expandability.
+ \command{GetLCTranslationForWarn}[\marg{lang}\marg{key}]
+ \sinceversion{1.1}Fetches and prints the translation of \meta{key} for
+ the language \meta{lang}. This command ensures that the fetched
+ translation is set lowercase. Issues a warning if no translation is
+ available at the cost of expandability.
+ \command{GetLCTranslationWarn}[\marg{key}]
+ \sinceversion{1.1}Fetches and prints the translation of \meta{key} for
+ the currently active language (as for example set by \pkg{babel}). This
+ command ensures that the fetched translation is set lowercase. Issues a
+ warning if no translation is available at the cost of expandability.
+ \command{SaveTranslationFor}[\marg{cmd}\marg{lang}\marg{key}]
+ Fetches and saves the translation of \meta{key} for the language
+ \meta{lang} in the macro \meta{cmd}.
+ \command{SaveTranslation}[\marg{cmd}\marg{key}]
+ Fetches and saves the translation of \meta{key} for the currently active
+ language (as for example set by \pkg{babel}) in the macro \meta{cmd}.
+ \command{LoadDictionary}[\marg{name}]
+ Loads a file named \code{\meta{name}-\meta{lang}.trsl} where \meta{lang}
+ corresponds to the lowercase name of the current language as defined with
+ \cs{DeclareLanguage}. This file should contain the translations for the
+ specified language.
+ \command{LoadDictionaryFor}[\marg{lang}\marg{name}]
+ Loads a file named \code{\meta{name}-\meta{lang}.trsl}.
+ \command{NewDictTranslation}[\marg{key}\marg{translation}]
+ \sinceversion{0.10}This command is to be used in a dictionary file and
+ picks up the language of that file. Issues an error if either the
+ translation for the \meta{key} or the dictionary entry for the \meta{key}
+ already exists.
+ \command{RenewDictTranslation}[\marg{key}\marg{translation}]
+ \sinceversion{0.10}This command is to be used in a dictionary file and
+ picks up the language of that file. Issues an error if either the
+ translation for the \meta{key} or the dictionary entry for the \meta{key}
+ doesn't exist.
+ \command{ProvideDictTranslation}[\marg{key}\marg{translation}]
+ \sinceversion{0.10}This command is to be used in a dictionary file and
+ picks up the language of that file. Only defines the translation and adds
+ a corresponding dictionary entry if they don't exist yet. This command is
+ used in the dictionaries that a part of \translations.
+ \command{DeclareDictTranslation}[\marg{key}\marg{translation}]
+ This command is to be used in a dictionary file and picks up the language
+ of that file, see \cref{sec:dictionaries} for an example. Defines the
+ translation and adds a dictionary entry regardless if they exist or not.
+ \command{ProvideDictionaryFor}[\marg{lang}\marg{name}\oarg{date}]
+ 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
+ dictionary which is used by \cs{DeclareDictTranslation}.
+ \expandable\command{PrintDictionaryFor}%
+ [\marg{lang}\marg{name}\marg{pre}\marg{mid}\marg{post}]
+ \sinceversion{1.0}Prints all entries of dictionary \meta{name} in
+ language \meta{lang} in the order the entries have been declared. For
+ every entry the code\par
+ \meta{pre}\meta{key}\meta{mid}\meta{translation}\meta{post}\par
+ is printed. The dictionary must have been loaded of course. There is
+ probably only a very limited number of use cases for this command. (It
+ was for example used to print \cref{tab:dict}.)
+ \expandable\command{baselanguage}[\marg{lang}]
+ \sinceversion{1.1}Returns the (internal) base name of the given language,
+ language alias or language dialect. This does \emph{not} give the base
+ language for a dialect! For a base language (see
+ section~\ref{ssec:languages:base}) this usually simply is the lowercase
+ version of the name. The choice for the command name is not a good one in
+ retrospect but is kept for compatibility reasons.\par
+ \verbcode+\baselanguage{English}+ $\Rightarrow$ \code{english}\\
+ \verbcode+\baselanguage{American}+ $\Rightarrow$ \code{american}
+ \expandable\command{baselanguagename}[\marg{lang}]
+ \sinceversion{1.2}The same as \cs{baselanguage} but alse gives the base
+ language name of a dialect.\par
+ \verbcode+\baselanguagename{English}+ $\Rightarrow$ \code{english}\\
+ \verbcode+\baselanguagename{American}+ $\Rightarrow$ \code{english}
+ \expandable\command{ifcurrentlanguage}[\marg{lang}\marg{true}\marg{false}]
+ \sinceversion{1.2}Places \meta{true} in the input stream if the current
+ language is \meta{lang}. Note: a dialect counts as a language of it's own
+ here. \cs{ifcurrentlanguage}\Marg{English} will for example be
+ \meta{false} if the current \pkg{babel} language is \code{american}.
+ \expandable\command{ifcurrentbaselanguage}[\marg{lang}\marg{true}\marg{false}]
+ \sinceversion{1.2}Places \meta{true} in the input stream if the current
+ language is \meta{lang}. Note: a dialect does notcount as a language of
+ it's own here. If the current \pkg{babel} language is \code{american}
+ then \cs{ifcurrentbaselanguage}\Marg{English} will be \meta{true}.
\end{commands}
\subsection{A Small Example}
@@ -396,51 +446,109 @@ either the translation will expand to the literal string.
The following three examples should make this concept clear:
-\begin{sourcecode}
- \documentclass{article}
+\begin{example}[compile]
+ \documentclass[margin=5mm]{standalone}
+ \usepackage{translations}
\DeclareTranslation{German}{foo-literal}{bar}
\begin{document}
- \GetTranslation{foo-literal} => `foo-literal'
+ \GetTranslation{foo-literal} % foo-literal
\end{document}
-\end{sourcecode}
+\end{example}
-\begin{sourcecode}
- \documentclass{article}
+\begin{example}[compile]
+ \documentclass[margin=5mm]{standalone}
+ \usepackage{translations}
\DeclareTranslationFallback{foo-literal}{foo}
\DeclareTranslation{German}{foo-literal}{bar}
\begin{document}
- \GetTranslation{foo-literal} => `foo'
+ \GetTranslation{foo-literal} % foo
\end{document}
-\end{sourcecode}
+\end{example}
-\begin{sourcecode}
- \documentclass{article}
+\begin{example}[compile]
+ \documentclass[margin=5mm]{standalone}
\usepackage[ngerman]{babel}
+ \usepackage{translations}
\DeclareTranslation{German}{foo-literal}{bar}
\begin{document}
- \GetTranslation{foo-literal} => `bar'
+ \GetTranslation{foo-literal} % bar
\end{document}
-\end{sourcecode}
+\end{example}
\subsection{Dictionaries}\label{sec:dictionaries}
-\subsubsection{Own Dictionaries}
+\subsubsection{Background}
+\translations\ provides the means to write dictionary files that can be loaded
+by packages or in a document. Dictionaries can be loaded for the currently
+active language with \cs{LoadDictionary} or for a specific language with
+\cs{LoadDictionaryFor}.
+
+\begin{commands}
+ \command{LoadDictionary}[\marg{name}]
+ Loads a file named \code{\meta{name}-\meta{lang}.trsl} where \meta{lang}
+ corresponds to the lowercase name of the current language as defined with
+ \cs{DeclareLanguage}. This file should contain the translations for the
+ specified language.
+ \command{LoadDictionaryFor}[\marg{lang}\marg{name}]
+ Loads a file named \code{\meta{name}-\meta{lang}.trsl}.
+\end{commands}
+
+A package could provide dictionary files for its language dependent settings
+and include the needed one at begin document. The basics for creating a
+dictionary file are explained in section~\ref{sec:own-dictionaries}.
+
+\translations\ already provides a few basic dictionary files. If the main
+document language fits to one of the provided files the corresponding basic
+dictionary is loaded at begin document by \translations, see
+section~\ref{sec:transl-basic-dict} for more on this.
+
+\subsubsection{Own Dictionaries}\label{sec:own-dictionaries}
A typical dictionary file should look as follows:
\begin{sourcecode}
% this is file housing-german.trsl
\ProvideDictionaryFor{German}{housing}[<version info>]
- \DeclareDictTranslation{kitchen (housing)}{K\"uche}
- \DeclareDictTranslation{bathroom (housing)}{Bad}
- \DeclareDictTranslation{living room (housing)}{Wohnzimmer}
- \DeclareDictTranslation{bedroom (housing)}{Schlafzimmer}
+ \ProvideDictTranslation{kitchen (housing)}{K\"uche}
+ \ProvideDictTranslation{bathroom (housing)}{Bad}
+ \ProvideDictTranslation{living room (housing)}{Wohnzimmer}
+ \ProvideDictTranslation{bedroom (housing)}{Schlafzimmer}
...
\endinput
\end{sourcecode}
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.
+only. Translations can be declared by one of the following commands:
+\begin{commands}
+ \command{NewDictTranslation}[\marg{key}\marg{translation}]
+ \sinceversion{0.10}This command is to be used in a dictionary file and
+ picks up the language of that file. Issues an error if either the
+ translation for the \meta{key} or the dictionary entry for the \meta{key}
+ already exists.
+ \command{RenewDictTranslation}[\marg{key}\marg{translation}]
+ \sinceversion{0.10}This command is to be used in a dictionary file and
+ picks up the language of that file. Issues an error if either the
+ translation for the \meta{key} or the dictionary entry for the \meta{key}
+ doesn't exist.
+ \command{ProvideDictTranslation}[\marg{key}\marg{translation}]
+ \sinceversion{0.10}This command is to be used in a dictionary file and
+ picks up the language of that file. Only defines the translation and adds
+ a corresponding dictionary entry if they don't exist yet. This command is
+ used in the dictionaries that a part of \translations.
+ \command{DeclareDictTranslation}[\marg{key}\marg{translation}]
+ This command is to be used in a dictionary file and picks up the language
+ of that file, see \cref{sec:dictionaries} for an example. Defines the
+ translation and adds a dictionary entry regardless if they exist or not.
+\end{commands}
+
+Every dictionary file \emph{must} contain the declaration
+\cs{ProvideDictionaryFor}:
+\begin{commands}
+ \command{ProvideDictionaryFor}[\marg{lang}\marg{name}\oarg{date}]
+ 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
+ dictionary which is used by \cs{NewDictTranslation} or similar commands.
+\end{commands}
-\subsubsection{\translations' Basic Dictionaries}
+\subsubsection{\translations' Basic Dictionaries}\label{sec:transl-basic-dict}
\translations\ already provides a basic dictionary for the languages English,
French, German and Spanish. This dictionary is loaded automatically if the
document language is one of these four. If you'd like to contribute and add