% Part   : Concepts
% Chapter: Translations
% ------------------------------------------------------------
% $Id: translations.tex 6191 2010-08-02 02:36:14Z al $
% ------------------------------------------------------------

\begin{description} 
\item[framework:] trunk/Translations/
\end{description}

\noindent Here is where translators locale images.  Image localization
is defined inside \texttt{.sed} files, also known as translation
files.  Translation files can be common or specific.  The given
organization of translation files defines the translation path.

\section{Common Translations}
\hypertarget{sec:Concepts:Translations:Common}{}

Common translation files contain common localization or no
localization at all for their related images.  They are in the root
directory of the translation path. Common translation files create
common images for all major releases of CentOS Distribution.

\section{Specific Translations}
\hypertarget{sec:Concepts:Translations:Specific}{}

Specific translation files contain specific localization for their
related images. Specific translation files are not in the root
directory of the translation path. Specific translation files are
inside directories which describe the type of translation they are
doing. 

\section{Translation Path}
\hypertarget{sec:Concepts:Translations:Path}{}

Translation path is where we organize common and specific translation
files. Translation path is also used as reference to build the path of
rendered images inside image directory (see
\hyperlink{sec:Concepts:Frameworks:Image}{Image Files}). 

When rendering images, if no REGEX argument is provided to
\texttt{render.sh} identity script, all translation files in the
translation path are read and applied one by one to its related design
template ---as defined in \texttt{getMatchingList} function--- to
produce a translated image. Images produced using the
\texttt{render.sh} identity script have the same name of its
translation file, but with the \texttt{.png} extension instead.

To control the number of images produced by \texttt{render.sh}
identity script, you need to look into the translation path and
provide a regular expression pattern that matches the translation
path, or paths, related to the image, or images, you want to produce.  

The regular expression pattern you provide to \texttt{render.sh}
identity script is applied to the translation path from its very
beginning.  It is not the same to say \texttt{5/es/01-welcome} that
\texttt{01-welcome}, the frist expression matches but the last one
does not.

When using REGEX you don't need to specify the file extension. It is
removed from translation path before applying the REGEX pattern, so it
doesn't count here.

\section{Translation Markers}
\hypertarget{sec:Concepts:Translations:Markers}{}

Translation markers are used in design templates and translation files
as replacement pattern to commit image translation.  When
\texttt{render.sh} identity script renders images, translation files
are applied to design templates to get a PNG translated image as
result.  In order to have the appropriate translation on the PNG
image, marker defintion in translation files should match markers in
design templates. 

Translation markers can be whatever text you want, but as convenction
we've defined those we use inside CentOS Artwork Repository. This
definition creates a common point of reference to translators and
graphic designers. To have a clean definition of translation markers
is what makes possible that translators and graphic designers can work
together but independently one another.

\section{Translation Rendering}
\hypertarget{sec:Concepts:Translations:Rendering}{}

Translation paths and files ---also known as the translation
structure--- are produced using the \texttt{render.sh} translation
script, available in the current translation directory.

The \texttt{render.sh} translation script combines the content of a
translation template directory ---holding common information--- with
the release-specific information you provide as argument when
executing the script. As result,  the \texttt{render.sh} translation
script produces the translation structure that \texttt{render.sh}
identity script needs to create translated images.

\section{Translation Rendering Script}
\hypertarget{sec:Concepts:Translations:RenderingScripts}{}

The \texttt{render.sh} translation script produces release-specific
translation directories.  Use the \texttt{render.sh} translation script
whenever you need to create a new release-specific translation
directory based on translation template directory.  The \texttt{render.sh}
translation script has the following syntax:

\begin{quote}
\texttt{./render.sh RELEASE ...}
\end{quote}

The RELEASE argument defines the release number used to create the
release-specific translation directory. You can pass many RELEASE
arguments, separated by one or more spaces, to \texttt{render.sh}
translation script in a single call.  If no RELEASE argument is passed
to \texttt{render.sh} translation script then all release-specific
translation directories, available in the current translation
directory, are updated using the translation template as reference.

Default behaviour of \texttt{render.sh} translation script may be
usefull if all your release-specific translation directories always
have the same information that translation template does.  If this is
the case, you only need to maintain the translation template and use
the \texttt{render.sh} translation script to propagate changes to each
release-specific translation directory.

In contrast, if you are using the \texttt{render.sh} translation
script to create release-specific translation directories that use
translation template as base to introduce non-reusable translations,
you should take care when executing the \texttt{render.sh} translation
script.  Otherwise, your non-reusable translations may be replaced
with those in template.

Inside CentOS Artwork Repository, all translation directories
(reusable and non-reusable) are versioned. If you accidentally
propagate template content to a non-reusable translation, you have the
Subversion's \texttt{revert} and \texttt{update} commands to undo the
mess.

As general rule, when you use the \texttt{render.sh} translations
script, take care of details and check twice before commit your
translation changes up to CentOS Artwork Repository.

\section{Translation Template Directory}
\hypertarget{sec:Concepts:Translations:TemplateDirectory}{}

The translation template directory is located in the current
translation directory and contains common translations for all
release-specific translation directories. It is also used as base to
build non-reusable translation.