Goals
-----

The trunk/Translations directory exists to:

  * Organize translation files.

  * Organize translation templates used to produce translation files.

Description
-----------

When you create artwork for CentOS distribution you find that some artworks need to be created for different major releases of CentOS distribution and inside each major release they need to be created for different locales. To get an approximate idea of how many files we are talking about, consider the followig approximate statistic:

  * Inside CentOS distribution, there are around 30 images to rebrand. (This number is an approximate value and may change. It is mainly based on CentOS 5 rebranding experience.)

  * There are near to four major releases of CentOS distribution to rebrand in parallel development. (This value was taken from CentOS release schema.)

  * Each CentOS distribution in parallel development supports more than two hundreds locales. (This value was taken from the locale -a command's output.)

In order to aliviate maintainance of artwork production for such environment, we divided artwork production in three production lines:

 1. See trunk Identity Themes Models, to define artworks characteristics (e.g., dimensions, position on the screen, etc.).

 2. See trunk Identity Themes Motifs, to define artworks visual styles (e.g., the look and feel).

 3. Translations, to define which major releases and locales artworks are produced for.

Inside CentOS Artwork Repository, the artworks' translation production line is stored under trunk/Translations directory.

Inside trunk/Translations directory, we use ``translation entries'' to organize artworks' ``translation files'' and artworks' ``translation templates''.

Translation Entries
...................

Translation entries exists for each artwork you want to produce. Translation entries can be empty directories, or directories containing translation files and translation templates.

When translation entries are empty directories, the identity entry is used as reference to create file names and directories layout for rendered files.  In this case, the centos-art script takes one design template and outputs one non-translated file for each design template available.  This configuration is mainly used to produce non-translatable artworks like themes' backgrounds.

When translation entries contain translation files, the translation entry implements the CentOS release schema and is used as reference to create file names and directories layout for translated artworks. In this case, the centos-art script applies one translation file to one design template to create one translated instance which is used to output one translated file. When the translated file is rendered, the centos-art script remove the previous instance and takes the next file in the list of translation files to repate the whole process once again, and so on for all files in the list. This configuration is mainly used to produce translatable artworks like Anaconda's progress slide images.

To find out correspondence between translation entries and identity entries, you need to look the path of both translation entries and identity entries. For example, if you are using the Modern's artisitic motif, the identity entry for Anaconda progress artwork is:

trunk/Identity/Themes/Motifs/Modern/Distro/Anaconda/Progress

and its translation entry is:

trunk/Translations/Identity/Themes/Distro/Anaconda/Progress

Note how the Translations/ directory prefixes Identity/ directory, also how static values (e.g., Identity, Themes, Distro, etc.) in the identity's entry path remain in translation's entry path, and how variable values like theme names (e.g., Modern) are stript out from translation's entry path. The same convenction can be applied to other identity entries in order to determine their translation entries, or to other translation entries to determine their identity entries.

     Note Translation entries related to identity entries under trunk/Identity/Themes/Motifs do not use Motifs/ in the path.  We've done this because trunk/Identity/Themes/Models structure, the other structure under trunk/Identity/Themes, doesn't require translation paths so far. So in the sake of saving characters space when building translation entries for trunk/Identity/Themes/Motifs structure, we organize Motifs translation entries under trunk/Translations/Identity/Themes/ directly.

     If for some reason trunk/Identity/Themes/Models structure requires translation entries, we need to re-oraganize the current directory structure accordingly.

Translation entries, as described above, can be re-used by similar identity entries. For example the following identity entries:

trunk/Identity/Themes/Motifs/Modern/Distro/Anaconda/Progress/
trunk/Identity/Themes/Motifs/TreeFlower/Distro/Anaconda/Progress/
trunk/Identity/Themes/Motifs/Mettle/Distro/Anaconda/Progress/

are all valid identity entries able to re-use translation files inside Anaconda progress translation entry (the one shown in our example above). This way, you can create several identity entries and maintain just one translation entry for all of them.  Once you change the translation files inside the common translation entry, changes inside identity entries will take effect inside the next you render them.

Trying to make things plain and simple: inside CentOS Artwork Repository, graphic designers can concentrate their efforts in artworks look and feel (the identity entries), and translators in artworks translations (the translation entries).

Translation Markers
...................

Translation markers are used in ``Theme Model Designs'' and ``Translation Files'' as replacement patterns to commit content translation.  When you are rendering content using centos-art script inisde trunk/Identity structure, artistic motifs and translation files are applied to model designs to produce translated content as result. In order to have the appropriate translation in content rendered, markers defintion in translation files should match markers in model designs exactly.

Translation markers can be whatever text you want, but as convenction we use the following to represent releases of CentOS distribution:

=MINOR_RELEASE=
     Replace with minor release of CentOS distribution. In the schema M.N, the minor release is represented by the N letter.

=MAJOR_RELEASE=
     Replace with major release of CentOS distribution. In the schema M.N, the major release is represented by the M letter.

=RELEASE=
     Replace the full release of CentOS distribution. It is =MAJOR_RELEASE=.=MINOR_RELEASE= basically.

Specific translation markers convenctions are described inside specific translation entries. Read translation entries documentation to know more about supported translation markers.

Translation markers standardization creates a common point of reference for translators and graphic designers. To have translation markers well defined makes possible that translators and graphic designers can work together but independently one another.

Translation Files
.................

Translation files are text files with sed's commands inside, replacement commands mainly. As convenction, translation file names end in .sed. Translation files are used by centos-art script to produce translated artworks for specific major releases of CentOS Distribution. There are common translation files, specific translation, and template translation files.

For example, the Firstboot artwork of CentOS distribution uses the images splash-small.png and firstboot-left.png as based to control its visual style. The splash-small.png image contains, in its graphic design, the release number information of CentOS distribution. So the splash-small.png is release-specific. In the other hand, the firstboot-left.png doesn't contain release number information. So the firstboot-left.png is not release-specific.

If we want to produce Firstboot artwork for different major releases of CentOS distribution, using a monolithic visual identity, all Firstboot images should have the same visual style and, at the same time, the release-specific information in the release-specific images.

     Note The monolithic visual identity is implemented using theme models (see trunk Identity Themes Models) and artistic motifs (see trunk Identity Themes Motifs).

Assuming that both theme models and theme motifs are ready for using, the initial translation entry to produce Firstboot artworks would look like the following:

trunk/Translations/Identity/Themes/Distro/BootUp/Firstboot/
|-- Tpl
|   `-- splash-small.sed
`-- firstboot-left.sed

With the translation entry above, centos-art command is able to produce the image firstboot-left.png only. To produce splash-small.png images for major releases (e.g., 3, 4, 5, and 6) of CentOS distribution we need to produce the release-specific translation files using the centos-art script as following:

centos-art render --entry=/home/centos/artwork/trunk/Translations/Identity/Themes/BootUp/Firstboot --filter='3,4,5,6'

The above command produces the following translation entiry:

trunk/Translations/Identity/Themes/Distro/BootUp/Firstboot/
|-- 3
|   `-- splash-small.sed
|-- 4
|   `-- splash-small.sed
|-- 5
|   `-- splash-small.sed
|-- 6
|   `-- splash-small.sed
|-- Tpl
|   `-- splash-small.sed
`-- firstboot-left.sed

At this point centos-art is able to produce the Firstboot artwork images for major releases of CentOS distribution. To add new release-specific translation files, run the translation rendering command with the release number you want to produce translation files for in the --filter='release-number' argument.

Template Translation Files
..........................

Template translation files are translation files stored inside translation template directory. Template translation files are used by centos-art script to produce specific translation files only. Template translation files may be empty or contain sed's replacement commands. If template translation files are empty files, the final specifc translation file built from it contains release-specific replacement commands only. For example, see the following translation entry:

trunk/Translations/Identity/Themes/Distro/BootUp/Firstboot/
|-- 3
|   `-- splash-small.sed
|-- 4
|   `-- splash-small.sed
|-- 5
|   `-- splash-small.sed
|-- 6
|   `-- splash-small.sed
|-- Tpl
|   `-- splash-small.sed    <-- template translation file.
`-- firstboot-left.sed

In the above exmaple, the splash-small.sed file is a template translation file and looks like:

# -------------------------------------
# $Id: splash-small.sed 94 2010-09-18 10:59:42Z al $
# -------------------------------------

In the above template translation file there are three comments lines, but when you render it, the centos-art adds the release-specific replacement commands. In our Firstboot example, after rendering Firstboot translation entry, the splash-small.sed translation file specific to CentOS 5, looks like the following:

# Warning: Do not modify this file directly. This file is created
# automatically using 'centos-art' command line interface.  Any change
# you do in this file will be lost the next time you update
# translation files using 'centos-art' command line interface. If you
# want to improve the content of this translation file, improve its
# template file instead and run the 'centos-art' command line
# interface later to propagate your changes.
# -------------------------------------
# $Id: splash-small.sed 94 2010-09-18 10:59:42Z al $
# -------------------------------------

# Release number information.
s!=RELEASE=!=MAJOR_RELEASE=.=MINOR_RELEASE=!g
s!=MINOR_RELEASE=!0!g
s!=MAJOR_RELEASE=!5!g

If template translation files are not empty, replacement commands inside template translation files are preserved inside release-specific translation files.  For example, consider the English template translation file of Anaconda progress welcome slide.  The translation template directory structure looks like the following:

trunk/Translations/Identity/Themes/Distro/Anaconda/Progress/
`-- Tpl
    `-- en
        `-- 01-welcome.sed

and if we render translation files for CentOS 4 and CentOS 5 major releases, the translation entry would look like the following:

trunk/Translations/Identity/Themes/Distro/Anaconda/Progress/
|-- 4
|   `-- en
|       `-- 01-welcome.sed
|-- 5
|   `-- en
|       `-- 01-welcome.sed
`-- Tpl
    `-- en
        `-- 01-welcome.sed

     Note Release-specific translation directories preserve template translation directory structure and file names.

In the example above, the template translation file looks like the following:

# ------------------------------------------------------------
# $Id: 01-welcome.sed 94 2010-09-18 10:59:42Z al $
# ------------------------------------------------------------
s/=TITLE=/Welcome to CentOS =MAJOR_RELEASE= !/
s/=TEXT1=/Thank you for installing CentOS =MAJOR_RELEASE=./
s/=TEXT2=/CentOS is an enterprise-class Linux Distribution derived from sources freely provided to the public by a prominent North American Enterprise Linux vendor./
s/=TEXT3=/CentOS conforms fully with the upstream vendors redistribution policy and aims to be 100% binary compatible. CentOS mainly changes packages to remove upstream vendor branding and artwork./
s/=TEXT4=//
s/=TEXT5=//
s/=TEXT6=//
s!=URL=!http://www.centos.org/!

and, after render the translation entry, specific translation files look like the following:

# Warning: Do not modify this file directly. This file is created
# automatically using 'centos-art' command line interface.  Any change
# you do in this file will be lost the next time you update
# translation files using 'centos-art' command line interface. If you
# want to improve the content of this translation file, improve its
# template file instead and run the 'centos-art' command line
# interface later to propagate your changes.
# ------------------------------------------------------------
# $Id: 01-welcome.sed 94 2010-09-18 10:59:42Z al $
# ------------------------------------------------------------

s/=TITLE=/Welcome to CentOS =MAJOR_RELEASE= !/
s/=TEXT1=/Thank you for installing CentOS =MAJOR_RELEASE=./
s/=TEXT2=/CentOS is an enterprise-class Linux Distribution derived from sources freely provided to the public by a prominen t North American Enterprise Linux vendor./
s/=TEXT3=/CentOS conforms fully with the upstream vendors redistribution policy and aims to be 100% binary compatible. Cent OS mainly changes packages to remove upstream vendor branding and artwork./
s/=TEXT4=//
s/=TEXT5=//
s/=TEXT6=//
s!=URL=!http://www.centos.org/!

# Release number information.
s!=RELEASE=!=MAJOR_RELEASE=.=MINOR_RELEASE=!g
s!=MINOR_RELEASE=!0!g
s!=MAJOR_RELEASE=!5!g

In the example above, relevant lines begin with the s word followed by a separation character (e.g., /, !, etc.). These lines have the following format:

s/REGEXP/REPLACEMENT/FLAGS

The / characters may be uniformly replaced by any other single character within any given s command.  The / character (or whatever other character is used in its stead) can appear in the REGEXP or REPLACEMENT only if it is preceded by a \ character.

The s command is probably the most important in sed and has a lot of different options.  Its basic concept is simple: the s command attempts to match the pattern space against the supplied REGEXP; if the match is successful, then that portion of the pattern space which was matched is replaced with REPLACEMENT.

In the context of our translation files, the REGEXP is where you define translation markers and REPLACEMENT where you define the translation text you want to have after artworks rendering.  Sometimes we use the FLAG component with the g command to apply the replacements globally.

     Tip More information about how to use sed's replacement commands and flags is available in sed's documentation manual. To read sed's documentation manual type the following command:
     info sed

Inside translation files, you can use translation markers not only inside the REGEXP but in the REPLACEMENT too. In order for this configuration to work, the REPLACEMENT of translation markers needs to be define after its definition. For example, see in the release-specific translation file above, how the s!=MAJOR_RELASE=!5!g replacement command is defined after =MAJOR_RELASE= translation marker definition in the REPLACEMENT of =TITLE= translation marker replacement command.

Common Translation Files
........................

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

Translation entries, with common translation files inside, look like the following:

trunk/Translations/Identity/Themes/Distro/BootUp/Firstboot/
|-- 3
|   `-- splash-small.sed
|-- 4
|   `-- splash-small.sed
|-- 5
|   `-- splash-small.sed
|-- 6
|   `-- splash-small.sed
|-- Tpl
|   `-- splash-small.sed
`-- firstboot-left.sed      <-- common translation file.

Specific Translation Files
..........................

Specific translation files contain specific translations for their related artworks. Specific translation files are not in the root directory of the translation entry, but inside directories which describe the type of translation they are doing. Specific translation files are produced automatically using the centos-art script.

trunk/Translations/Identity/Themes/Distro/BootUp/Firstboot/
|-- 3
|   `-- splash-small.sed    <-- CentOS 3 specific translation file.
|-- 4
|   `-- splash-small.sed    <-- CentOS 4 specific translation file.
|-- 5
|   `-- splash-small.sed    <-- CentOS 5 specific translation file.
|-- 6
|   `-- splash-small.sed    <-- CentOS 6 specific translation file.
|-- Tpl
|   `-- splash-small.sed
`-- firstboot-left.sed

Translation Rendering
.....................

When rendering translations, the centos-art script checks the translation entry to verify that it has a translation template directory inside. The translation template directory (Tpl/) contains common translation files used to build release-specific translation files. If the translation template directory doesn't exist inside the translation entry the translation rendering fails. In this case the centos-art script outputs a message and quits script execution.

Translation (Pre-)Rendering Configuration Scripts
.................................................

When the centos-art script finds a translation template directory inside translation entry, it looks for translations pre-rendering configuration scripts for that translation entry. Translation pre-rendering configuration scripts let you extend translation's default functionality (described below).

Translation pre-rendering configuration scripts are stored under trunk/Scripts directory, specifically under the appropriate language implementation. If you are using centos-art Bash's implementation, the translation pre-rendering scripts are store in the trunk/Scripts/Bash/Config location; if you are using centos-art Python's implementation, then translation pre-rendering scripts are stored in the trunk/Scripts/Python/Config location, and so on for other implementations.

Bash's translation pre-rendering configuration scripts look like the following:

#!/bin/bash
#
# render_loadConfig.sh -- brief description here.
#
# Copyright (C) YEAR YOURNAME
#
# This program is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 2 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful, but
# WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
# General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
# USA.
#
# ----------------------------------------------------------------------
# $Id: splash-small.sed 94 2010-09-18 10:59:42Z al $
# ----------------------------------------------------------------------

function render_loadConfig {
...
}

Translation pre-rendering scripts are function scripts loaded and executed when rendering a translation entry. Translation pre-rendering scripts are loaded using the translation entry being rendered as reference. For example, suppose you are using the centos-art Bash's implementation, and you are rendering translations for CentOS brands, in this situation the translation entry would be:

trunk/Translations/Identity/Brands

and the entry inside the translation pre-rendering configuration structure would be:

trunk/Scripts/Bash/Config/Identity/Brands

Once the centos-art script detects that translation pre-rendering configuration directory exists, the centos-art script looks for the translation pre-rendering configuration file.  If the translation pre-rendering configuration file exists, it is loaded and executed.  Once the translation pre-rendering configuration file has been executed the translation rendering process is over, and so the script execution.

     Note Translation pre-rendering configuration files have the following form:
     render.conf.extension
     where extension refers the programming language implementation you are using. For example, sh for Bash's, py for Python's, pl for Perl's, and so on for other implementations.

As we are using Bash implementation to describe the translation pre-rendering configuration example, the translation pre-rendering configuration file that centos-art looks for, inside the above translation pre-rendering configuration directory, is render.conf.sh.

Translation Rendering Default Functionality
...........................................

In the other hand, if the translation pre-rendering configuration file doesn't exist, or it isn't written as function script, the centos-art script ignore translation pre-rendering configuration functionality and passes to render translation using default functionality instead.

The translation rendering default functionality takes template translation directory structure, duplicates it for each release number specified in the --filter='release-number' argument and produces release-specific directories. As part of template translation duplication process take place, the centos-art script adds release-specific replacement commands to each specific translation file inside release-specific directories. As result, specific translation files, inside release-specific directories, contain template translation replacement commands plus, release-specific replacement commands.

     Note Release-specific replacement commands are standardized inside centos-art script using predifined release translation markers. Release translation markers are described in the translation marker section (see Translation Markers).

Usage
-----

centos-art render --entry='path/to/dir'

     When path/to/dir refers one directory under trunk/Translations, this command orverwrites available translation files using translation templates.

centos-art render --entry='path/to/dir' --filter='pattern'

     When path/to/dir refers one directory under trunk/Translations, this command renders release-specific translation files as you specify in the --filter='pattern' argument. In this case, pattern not a regular expression but an number (e.g., 5) or a list of numbers separated by commas (e.g., 3,4,5,6) that specify the major release of CentOS distribution you want to render translations for.

See also
--------