Blame Manual/repository-latex/Concepts/translations.tex

4c79b5
% Part   : Concepts
4c79b5
% Chapter: Translations
4c79b5
% ------------------------------------------------------------
4c79b5
% $Id: translations.tex 6191 2010-08-02 02:36:14Z al $
4c79b5
% ------------------------------------------------------------
4c79b5
4c79b5
\begin{description} 
4c79b5
\item[framework:] trunk/Translations/
4c79b5
\end{description}
4c79b5
4c79b5
\noindent Here is where translators locale images.  Image localization
4c79b5
is defined inside \texttt{.sed} files, also known as translation
4c79b5
files.  Translation files can be common or specific.  The given
4c79b5
organization of translation files defines the translation path.
4c79b5
4c79b5
\section{Common Translations}
4c79b5
\hypertarget{sec:Concepts:Translations:Common}{}
4c79b5
4c79b5
Common translation files contain common localization or no
4c79b5
localization at all for their related images.  They are in the root
4c79b5
directory of the translation path. Common translation files create
4c79b5
common images for all major releases of CentOS Distribution.
4c79b5
4c79b5
\section{Specific Translations}
4c79b5
\hypertarget{sec:Concepts:Translations:Specific}{}
4c79b5
4c79b5
Specific translation files contain specific localization for their
4c79b5
related images. Specific translation files are not in the root
4c79b5
directory of the translation path. Specific translation files are
4c79b5
inside directories which describe the type of translation they are
4c79b5
doing. 
4c79b5
4c79b5
\section{Translation Path}
4c79b5
\hypertarget{sec:Concepts:Translations:Path}{}
4c79b5
4c79b5
Translation path is where we organize common and specific translation
4c79b5
files. Translation path is also used as reference to build the path of
4c79b5
rendered images inside image directory (see
4c79b5
\hyperlink{sec:Concepts:Frameworks:Image}{Image Files}). 
4c79b5
4c79b5
When rendering images, if no REGEX argument is provided to
4c79b5
\texttt{render.sh} identity script, all translation files in the
4c79b5
translation path are read and applied one by one to its related design
4c79b5
template ---as defined in \texttt{getMatchingList} function--- to
4c79b5
produce a translated image. Images produced using the
4c79b5
\texttt{render.sh} identity script have the same name of its
4c79b5
translation file, but with the \texttt{.png} extension instead.
4c79b5
4c79b5
To control the number of images produced by \texttt{render.sh}
4c79b5
identity script, you need to look into the translation path and
4c79b5
provide a regular expression pattern that matches the translation
4c79b5
path, or paths, related to the image, or images, you want to produce.  
4c79b5
4c79b5
The regular expression pattern you provide to \texttt{render.sh}
4c79b5
identity script is applied to the translation path from its very
4c79b5
beginning.  It is not the same to say \texttt{5/es/01-welcome} that
4c79b5
\texttt{01-welcome}, the frist expression matches but the last one
4c79b5
does not.
4c79b5
4c79b5
When using REGEX you don't need to specify the file extension. It is
4c79b5
removed from translation path before applying the REGEX pattern, so it
4c79b5
doesn't count here.
4c79b5
4c79b5
\section{Translation Markers}
4c79b5
\hypertarget{sec:Concepts:Translations:Markers}{}
4c79b5
4c79b5
Translation markers are used in design templates and translation files
4c79b5
as replacement pattern to commit image translation.  When
4c79b5
\texttt{render.sh} identity script renders images, translation files
4c79b5
are applied to design templates to get a PNG translated image as
4c79b5
result.  In order to have the appropriate translation on the PNG
4c79b5
image, marker defintion in translation files should match markers in
4c79b5
design templates. 
4c79b5
4c79b5
Translation markers can be whatever text you want, but as convenction
4c79b5
we've defined those we use inside CentOS Artwork Repository. This
4c79b5
definition creates a common point of reference to translators and
4c79b5
graphic designers. To have a clean definition of translation markers
4c79b5
is what makes possible that translators and graphic designers can work
4c79b5
together but independently one another.
4c79b5
4c79b5
\section{Translation Rendering}
4c79b5
\hypertarget{sec:Concepts:Translations:Rendering}{}
4c79b5
4c79b5
Translation paths and files ---also known as the translation
4c79b5
structure--- are produced using the \texttt{render.sh} translation
4c79b5
script, available in the current translation directory.
4c79b5
4c79b5
The \texttt{render.sh} translation script combines the content of a
4c79b5
translation template directory ---holding common information--- with
4c79b5
the release-specific information you provide as argument when
4c79b5
executing the script. As result,  the \texttt{render.sh} translation
4c79b5
script produces the translation structure that \texttt{render.sh}
4c79b5
identity script needs to create translated images.
4c79b5
4c79b5
\section{Translation Rendering Script}
4c79b5
\hypertarget{sec:Concepts:Translations:RenderingScripts}{}
4c79b5
4c79b5
The \texttt{render.sh} translation script produces release-specific
4c79b5
translation directories.  Use the \texttt{render.sh} translation script
4c79b5
whenever you need to create a new release-specific translation
4c79b5
directory based on translation template directory.  The \texttt{render.sh}
4c79b5
translation script has the following syntax:
4c79b5
4c79b5
\begin{quote}
4c79b5
\texttt{./render.sh RELEASE ...}
4c79b5
\end{quote}
4c79b5
4c79b5
The RELEASE argument defines the release number used to create the
4c79b5
release-specific translation directory. You can pass many RELEASE
4c79b5
arguments, separated by one or more spaces, to \texttt{render.sh}
4c79b5
translation script in a single call.  If no RELEASE argument is passed
4c79b5
to \texttt{render.sh} translation script then all release-specific
4c79b5
translation directories, available in the current translation
4c79b5
directory, are updated using the translation template as reference.
4c79b5
4c79b5
Default behaviour of \texttt{render.sh} translation script may be
4c79b5
usefull if all your release-specific translation directories always
4c79b5
have the same information that translation template does.  If this is
4c79b5
the case, you only need to maintain the translation template and use
4c79b5
the \texttt{render.sh} translation script to propagate changes to each
4c79b5
release-specific translation directory.
4c79b5
4c79b5
In contrast, if you are using the \texttt{render.sh} translation
4c79b5
script to create release-specific translation directories that use
4c79b5
translation template as base to introduce non-reusable translations,
4c79b5
you should take care when executing the \texttt{render.sh} translation
4c79b5
script.  Otherwise, your non-reusable translations may be replaced
4c79b5
with those in template.
4c79b5
4c79b5
Inside CentOS Artwork Repository, all translation directories
4c79b5
(reusable and non-reusable) are versioned. If you accidentally
4c79b5
propagate template content to a non-reusable translation, you have the
4c79b5
Subversion's \texttt{revert} and \texttt{update} commands to undo the
4c79b5
mess.
4c79b5
4c79b5
As general rule, when you use the \texttt{render.sh} translations
4c79b5
script, take care of details and check twice before commit your
4c79b5
translation changes up to CentOS Artwork Repository.
4c79b5
4c79b5
\section{Translation Template Directory}
4c79b5
\hypertarget{sec:Concepts:Translations:TemplateDirectory}{}
4c79b5
4c79b5
The translation template directory is located in the current
4c79b5
translation directory and contains common translations for all
4c79b5
release-specific translation directories. It is also used as base to
4c79b5
build non-reusable translation.