Blame Manuals/Tcar-ug/Scripts/Bash/locale.docbook

e68d9f
<sect1 id="scripts-bash-locale">
655c5e
655c5e
    <title><function>locale</function> — Standardize Localization Tasks</title>
655c5e
655c5e
    <para>
655c5e
        The <function>locale</function> functionality is the
655c5e
        interface the <command>centos-art.sh</command> script provides
655c5e
        to standardize localization tasks inside the working copy.
655c5e
    </para>
655c5e
655c5e
    <screen>centos-art locale [OPTIONS] [DIRECTORY]</screen>
655c5e
655c5e
    <para>
655c5e
        The <varname>DIRECTORY</varname> parameter specifies the
655c5e
        directory path, inside the working copy of &TCAR;, where the
655c5e
        files you want to process are stored in.  This paramter can be
655c5e
        provided more than once in order to process more than one
655c5e
        directory path in a single command execution.  When this
655c5e
        parameter is not provided, the current directory path where
655c5e
        the command was called from is used instead.
655c5e
    </para>
655c5e
    <para>
655c5e
        The <function>locale</function> functionality accepts the
655c5e
        following options: 
655c5e
    </para>
655c5e
655c5e
    <variablelist>
655c5e
    <varlistentry>
655c5e
    <term><option>--quiet</option></term>
655c5e
    <listitem>
655c5e
    <para>
655c5e
        Supress all output messages except error messages.  When this
655c5e
        option is passed, all confirmation requests are supressed and
655c5e
        a possitive answer is assumed for them, just as if the
655c5e
        <option>--answer-yes</option> option would have been provided.
655c5e
    </para>
655c5e
    </listitem>
655c5e
    </varlistentry>
655c5e
655c5e
    <varlistentry>
655c5e
    <term><option>--answer-yes</option></term>
655c5e
    <listitem>
655c5e
    <para>
655c5e
       Assume <emphasis>yes</emphasis> to all confirmation requests.
655c5e
    </para>
655c5e
    </listitem>
655c5e
    </varlistentry>
655c5e
655c5e
    <varlistentry>
655c5e
    <term><option>--filter="REGEX"</option></term>
655c5e
    <listitem>
655c5e
    <para>
655c5e
        Reduce the list of files to process inside
655c5e
        <varname>DIRECTORY</varname> using <varname>REGEX</varname> as
655c5e
        pattern.  You can use this option to control the amount of
655c5e
        files you want to locale.  The deeper you go into the
655c5e
        directory structure the more specific you'll be about the
655c5e
        files you want to locale.  When you cannot go deeper into the
655c5e
        directory structure through <varname>DIRECTORY</varname>
655c5e
        specification, use this option to reduce the list of files
655c5e
        therein.
655c5e
    </para>
655c5e
    </listitem>
655c5e
    </varlistentry>
655c5e
655c5e
    <varlistentry>
655c5e
    <term><option>--dont-commit-changes</option></term>
655c5e
    <listitem>
655c5e
    <para>
655c5e
        Supress all commit and update actions realized over files,
655c5e
        before and after the actions themselves had took place over
655c5e
        files in the working copy.
655c5e
    </para>
655c5e
    </listitem>
655c5e
    </varlistentry>
655c5e
655c5e
    <varlistentry>
655c5e
    <term><option>--update</option></term>
655c5e
    <listitem>
655c5e
    <para>
655c5e
        This option updates both POT and PO files related to source
655c5e
        files.  Use this option everytime you change translatable
655c5e
        strings inside the source files.
655c5e
    </para>
655c5e
    </listitem>
655c5e
    </varlistentry>
655c5e
655c5e
    <varlistentry>
655c5e
    <term><option>--edit</option></term>
655c5e
    <listitem>
655c5e
    <para>
655c5e
        This option edits the portable object related to source files.
655c5e
        When you provide this option, your default text editor is used
655c5e
        to open the portable object you, as translator, need to change
655c5e
        in order to keep source file messages consistent with their
655c5e
        localized versions.  In the very specific case of shell
655c5e
        scripts localization, this option takes care of updating the
655c5e
        machine object (MO) file the shell script requires to
655c5e
        displayed translation messages correctly when it is executed.
655c5e
    </para>
655c5e
    </listitem>
655c5e
    </varlistentry>
655c5e
655c5e
    <varlistentry>
655c5e
    <term><option>--delete</option></term>
655c5e
    <listitem>
655c5e
    <para>
655c5e
        This option unlocalizes source files. When you provide this
655c5e
        option, the localization directory related to source files is
655c5e
        removed from the working copy in conjunction with all portable
655c5e
        objects and machine objects inside it.
655c5e
    </para>
655c5e
    </listitem>
655c5e
    </varlistentry>
655c5e
655c5e
    <varlistentry>
655c5e
    <term><option>--dont-create-mo</option></term>
655c5e
    <listitem>
655c5e
    <para>
655c5e
        This option suppresses machine objects creation when shell
655c5e
        scripts are localized.
655c5e
    </para>
655c5e
    </listitem>
655c5e
    </varlistentry>
655c5e
655c5e
    </variablelist>
655c5e
655c5e
    <para>
655c5e
        The localization process is very tied to the source files we
655c5e
        want to provide localized messages for. Inside the working
655c5e
        copy of &TCAR; it is possible to localize XML-based files
655c5e
        (e.g., SVG and Docbook) and programs written in most popular
655c5e
        programming languages (e.g., C, C++, C#, Shell Scripts,
655c5e
        Python, Java, GNU awk, PHP, etc.).
655c5e
    </para>
655c5e
655c5e
    <para>
655c5e
        The localization process initiates by retriving translatable
655c5e
        strings from source files.  When source files are XML-based
655c5e
        files, the only requisite to retrive translatable strings
655c5e
        correctly is that they be well-formed.  Beyond that, the
655c5e
        <command>xml2po</command> command takes care of everything
655c5e
        else.  When source files are Shell script files, it is
655c5e
        necessary that you previously define what strings inside the
655c5e
        script are considered as translatable strings in order for
655c5e
        <command>xgettext</command> command to retrive them correctly.
655c5e
        To define translatable strings inside shell scripts, you need
655c5e
        to use either <command>gettext</command>,
655c5e
        <command>ngettext</command>, <command>eval_gettext</command>
655c5e
        or <command>eval_ngettext</command> command as it is following
655c5e
        described:
655c5e
    </para>
655c5e
655c5e
    <itemizedlist>
655c5e
    <listitem>
655c5e
    <para>
655c5e
        Use the <command>gettext</command> command to display the
655c5e
        native language translation of a textual message.
655c5e
    </para>
655c5e
    <screen>MESSAGE="`gettext "There is no entry to create."`"</screen>
655c5e
    </listitem>
655c5e
655c5e
    <listitem>
655c5e
    <para>
655c5e
        Use the <command>ngettext</command> command to display the
655c5e
        native language translation of a textual message whose
655c5e
        grammatical form depends on a number.
655c5e
    </para>
655c5e
    <screen>MESSAGE="`ngettext "The following entry will be created" \
655c5e
                   "The following entries will be created" \
655c5e
                   $COUNT`:"</screen>
655c5e
    </listitem>
655c5e
655c5e
    <listitem>
655c5e
    <para>
655c5e
        Use the <command>eval_gettext</command> command to display the
655c5e
        native language translation of a textual message, performing
655c5e
        dollar-substitution on the result.  Note that only shell
655c5e
        variables mentioned in the message will be dollar-substituted
655c5e
        in the result.
655c5e
    </para>
655c5e
    <screen>MESSAGE="`eval_gettext "The location \\\"\\\$LOCATION\\\" is not valid."`"</screen>
655c5e
    </listitem>
655c5e
655c5e
    <listitem>
655c5e
    <para>
655c5e
        Use the <command>eval_ngettext</command> command to display
655c5e
        the native language translation of a textual message whose
655c5e
        grammatical form depends on a number, performing
655c5e
        dollar-substitution on the result.  Note that only shell
655c5e
        variables mentioned in messages will be dollar-substituted in
655c5e
        the result.
655c5e
    </para>
655c5e
    <screen>MESSAGE="`eval_ngettext "The following entry will be created in \\\$LOCATION" \
655c5e
                        "The following entries will be created in \\\$LOCATION" \
655c5e
                        $COUNT`:"</screen>
655c5e
    </listitem>
655c5e
    </itemizedlist>
655c5e
655c5e
    <para>
655c5e
        Once translatable strings are retrived, a portable object
655c5e
        template (POT) file is created for storing them. Later, the
655c5e
        POT file is used to create a portable object (PO). The
655c5e
        portable object is the place where localization itself takes
655c5e
        place, it is the file translators edit to localize messages.
655c5e
        When translatable strings change inside source files, it is
655c5e
        necessary that you update these POT and PO files in order to
655c5e
        keep consistency between source file messages and their
655c5e
        localized versions.
655c5e
    </para>
655c5e
655c5e
    <para>
655c5e
        Inside source files, translatable strings are always written
655c5e
        in English language. In order to localize translatable strings
655c5e
        from English language to another language, you need to be sure
655c5e
        the <envar>LANG</envar> environment variable has been already
655c5e
        set to the locale code you want to localize message for or see
655c5e
        them printed out before running the
655c5e
        <function>locale</function> functionality of
655c5e
        <command>centos-art.sh</command> script.  Localizing English
655c5e
        language to itself is not supported.
655c5e
    </para>
655c5e
655c5e
    <para>
655c5e
        To have a list of all locale codes you can have localized
655c5e
        messages for, run the following command: <command>locale -a |
655c5e
        less</command>.
655c5e
    </para>
655c5e
e68d9f
</sect1>