@subheading Name

The @code{locale} functionlity is part of @command{centos-art.sh}
script and standardizes localization tasks inside the working copy of
CentOS Artwork Repository.

@subheading Synopsis

@command{centos-art locale [OPTIONS] path/to/dir}

The @file{path/to/dir} parameter specifies what directory structure
inside the working copy of CentOS Artwork Repository you want to
create translation messages for.

The @code{locale} functionality of @command{centos-art.sh} script
accepts the following options:

@table @option
@item --quiet

Supress all output messages except error messages.  When this option
is passed, all confirmation requests are supressed as well and a
possitive answer is assumed for them, just as if the
@option{--answer-yes} option had been provided.

@item --answer-yes

Assume `yes' to all confirmation requests.

@item --filter="REGEX"

Reduce the list of files to process using @samp{REGEX} as pattern.
You can use this option in combination with @file{path/to/dir} in
order to control the amount of files you want to produce as
base-rendition.  The deeper you go into the directory structure the
more specific you'll be about the component you want to produce. When
you cannot go deeper into the directory structure, you can use
@option{--filter} option to reduce the list of files.

@item --dont-commit-changes

Supress all commit and update actions realized over files, before and
after the action itself had took place over files in the working copy.

@item --update

This option extracts translatable strings from both XML-based files
(using @command{xml2po}) and shell scripts (using @command{xgettext})
under @file{path/to/dir}. Translatable strings are initially stored in
portable objects templates (.pot) which are later merged into portable
objects (.po) in order to be converted as machine objects (.mo).

Use this option each time you change translatable stirngs inside
design models and script files.

@item --edit

This option edits the portable object related to @file{path/to/dir}
location.

Use this option after updating portable objects (through
@option{--update} option) in order to change the language-specific
information of translatable strings.

@item --dont-create-mo

This option supresses the creation of machine objects.

@end table

@subheading Description

The CentOS Artwork Repository exists to cover the visual needs of The
CentOS Project Corporate Identity. The CentOS Project is an
internationl project and sometimes requires contents in different
languages. So, in that sake, the CentOS Artwork Repository is designed
to produce content in as many locales as supported by The CentOS
Distribution, the platform that supports the whole CentOS Artwork
Repository, both in workstations and server.

@quotation
@strong{Tip} To know what locales are supported by The CentOS
Distribution you are currently using, run the following command:

@verbatim
locale -a | less
@end verbatim
@end quotation

The localization process is very tied to the input files we want to
provide localized messages for. Inside the CentOS Artwork Repository,
it is possible to localize XML files (e.g., SVG, XHTML, Docbook) and
programs written in most popular programming languages (e.g., C, C++,
C#, Shell Scripts, Python, Java, GNU awk, PHP, etc.).

@subsubheading Design models localization

Design models are used as input to produce most images and some other
contents as well. Design models are always XML-based files (e.g., SVG,
XHTML, Docbook), so the @code{locale} functionality uses the
@command{xml2po} program to create protable objects from them under
@file{trunk/Locales/Models} directory. Portable objects contain the
relation between message id and message translation, as translator,
need to take care of.

Thanks to @command{xml2po}, it is possible for the @code{locale}
functionality to separate designing tasks from the translating tasks.
It is possible for graphic designers to concentrate their efforts on
designing models in English language while translators take care of
their localization using the @option{--update} and @option{--edit}
options as much as it be needed.

Once design models have been localized, rendering them in different
language is a matter using the @code{render} functionality of
@command{centos-art.sh} script. @xref{Directories trunk Scripts
Functions Render}, for more information about it.

@subsubheading Shell script localization

The @code{locale} functionality is used to localize the
@command{centos-art.sh} script itself. The @command{centos-art.sh}
script is a shell script written in Bash, so the @code{locale}
functionality uses the @command{gettext} tools to retrive translatable
strings, create portable objects and machine objects.

Thanks to @command{gettext}, it is possible for the @code{locale}
functionality to separate programming tasks from the translating
tasks. It is possible for programmer to concentrate their efforts in
programming output messages in English language while translators take
care of their localization using the @option{--update} and
@option{--edit} options as much as it be needed.

Once @command{centos-art.sh} script has been localized, the translated
messages should be immediatly visible to you, the next time you
execute the @command{centos-art.sh} script

@quotation
@strong{Note} 
In order to localize translatable strings from English language to
another language you need to be sure the @env{LANG} environment
variable has been already set to the locale code you want to localize
message for or see them printed out before running the
@command{centos-art.sh} script.  Localizing English language to itself
is not supported.
@end quotation

@subheading Examples

@table @command
@item centos-art locale --update trunk/Identity/Models/Default/Distro/5/Anaconda

This command updates portable objects related to Anaconda default
design models of The CentOS Distribution major release 5. The update
action consists on adding new translatable strings or removing old
translatable strings from portable objects in order to keep both the
portable object and the design model consistent.

This command is executed by translators once the graphic designers
have committed updates to Anaconda default design models (e.g., slide
text changes).

@item centos-art locale --edit trunk/Identity/Models/Default/Distro/5/Anaconda

This command let translators to edit portable objects related to
Anaconda default design models of The CentOS Distribution major
release 5. The edit action is where the translator localize
translatable strings in English language to another language.

When portable objects for XML-base files are produced, there is no
need to retain the machine object format, so we the
@option{--dont-create-mo} is automatically assumed.

@item centos-art locale --update trunk/Scripts

This command updates portable objects related to
@command{centos-art.sh} script. The update action consists on adding
new translatable strings or removing old translatable strings from
portable objects in order to keep both the portable object and the
@command{centos-art.sh} script to be consistent one another.

This command is executed by translators once the programmers have
committed updates @command{centos-art.sh} script.

@item centos-art locale --edit trunk/Scripts

This command edits portable objects related to @command{centos-art.sh}
script in your prefered language.

@item centos-art locale --update trunk/Manual/repository.xhtml

This command updates portable objects for the XHTML output of the
repository documentation manual. The portable objects are created in
your prefered language and can be used to produced localized versions
of the manual in XHTML format.

The update action consists on adding new translatable strings to or
removing old translatable strings from the portable objects in order
to keep both the portable object and the manual XHTML output
consistent one another.

People execute this command after committing changes to the repository
documentation manual.

@item centos-art locale --edit trunk/Manual/repository.xhtml

This command takes all the repository documentation manual XHTML
output files, which have not been translated yet inside the
@file{trunk/Manual/repository.xhtml} directory, as input to produce
portable objects from them so as for you to localize translatable
strings to your prefered language (e.g., as specified by the
@env{LANG} environment variable).

Once the portable objects have been created they are used to produce
the translated version of the manual in XHTML format under the
@file{trunk/Manual/repository.xml/LANG} directory, where @samp{LANG}
refers your prefered language. The translated version of the XHTML
files is produced using the @code{render} functionality of
@command{centos-art.sh} script (@pxref{Directories trunk Scripts
Functions Render}).

When your prefered language is other but English, the
@command{centos-art.sh} script takes care of updating both the
portable objects and the translated version of files after you've
edited a manual documentation entry, using the @code{help}
functionality of @command{centos-art.sh} script (@pxref{Directories
trunk Scripts Functions Help}). In other situations, you need to do
these actions by yourself.

@end table

@subheading Author

Written by Alain Reguera Delgado.

@subheading Reporting bugs

Report bugs to @email{centos-artwork@@centos.org} mailing list.

@subheading Copyright

Copyright @copyright{}  2009, 2010, 2011 The CentOS Project.

This is free software.  You may redistribute copies of it under the
terms of the GNU General Public License (@pxref{GNU General Public
License}).  There is NO WARRANTY, to the extent permitted by law.

@subheading See also

@itemize
@item The GNU @command{gettext} tools documentation (@command{info gettext})
@item The @command{xml2po} command documentation (@command{man xml2po})
@item @ref{Directories trunk Scripts Functions}
@item @ref{Directories trunk Scripts}
@item @ref{Directories trunk}
@end itemize