Blob Blame History Raw
<refentry id="scripts-bash-locale">

    <refmeta>
        <refentrytitle>locale</refentrytitle>
        <indexterm type="specific-function">
            <primary>Standardize translation tasks inside &TCAR;</primary>
        </indexterm>
    </refmeta>

    <refnamediv>
        <refname>locale</refname>
        <refpurpose>Standardize translation tasks inside &TCAR;</refpurpose>
    </refnamediv>

    <refsynopsisdiv>
    <para>
        The <varname>DIRECTORY</varname> parameter specifies the
        directory path, inside the working copy of &TCAR;, where the
        files you want to process are stored in.  This paramter can be
        provided more than once in order to process more than one
        directory path in a single command execution.  When this
        parameter is not provided, the current directory path where
        the command was called from is used instead.
    </para>
    </refsynopsisdiv>

    <refsection id="scripts-bash-locale-options">
    <title>Options</title>
    <para>
        The <function>locale</function> functionality accepts the
        following options: 
    </para>

    <variablelist>
    <varlistentry>
    <term><option>--quiet</option></term>
    <listitem>
    <para>
        Supress all output messages except error messages.  When this
        option is passed, all confirmation requests are supressed and
        a possitive answer is assumed for them, just as if the
        <option>--answer-yes</option> option would have been provided.
    </para>
    </listitem>
    </varlistentry>

    <varlistentry>
    <term><option>--answer-yes</option></term>
    <listitem>
    <para>
       Assume <emphasis>yes</emphasis> to all confirmation requests.
    </para>
    </listitem>
    </varlistentry>

    <varlistentry>
    <term><option>--filter="REGEX"</option></term>
    <listitem>
    <para>
        Reduce the list of files to process inside
        <varname>DIRECTORY</varname> using <varname>REGEX</varname> as
        pattern.  You can use this option to control the amount of
        files you want to locale.  The deeper you go into the
        directory structure the more specific you'll be about the
        files you want to locale.  When you cannot go deeper into the
        directory structure through <varname>DIRECTORY</varname>
        specification, use this option to reduce the list of files
        therein.
    </para>
    </listitem>
    </varlistentry>

    <varlistentry>
    <term><option>--synchronize</option></term>
    <listitem>
    <para>
        Synchronizes available changes between the working copy and
        the central repository.
    </para>
    </listitem>
    </varlistentry>

    <varlistentry>
    <term><option>--update</option></term>
    <listitem>
    <para>
        This option updates both POT and PO files related to source
        files.  Use this option everytime you change translatable
        strings inside the source files.
    </para>
    </listitem>
    </varlistentry>

    <varlistentry>
    <term><option>--edit</option></term>
    <listitem>
    <para>
        This option edits the portable object related to source files.
        When you provide this option, your default text editor is used
        to open the portable object you, as translator, need to change
        in order to keep source file messages consistent with their
        localized versions.  In the very specific case of shell
        scripts localization, this option takes care of updating the
        machine object (MO) file the shell script requires to
        displayed translation messages correctly when it is executed.
    </para>
    </listitem>
    </varlistentry>

    <varlistentry>
    <term><option>--delete</option></term>
    <listitem>
    <para>
        This option unlocalizes source files. When you provide this
        option, the localization directory related to source files is
        removed from the working copy in conjunction with all portable
        objects and machine objects inside it.
    </para>
    </listitem>
    </varlistentry>

    <varlistentry>
    <term><option>--dont-create-mo</option></term>
    <listitem>
    <para>
        This option suppresses machine objects creation when shell
        scripts are localized.
    </para>
    </listitem>
    </varlistentry>

    </variablelist>
    </refsection>

    <refsection id="scripts-bash-locale-description">
    <title>Description</title>

    <para>
        The localization process is very tied to the source files we
        want to provide localized messages for. Inside the working
        copy of &TCAR; it is possible to localize XML-based files
        (e.g., SVG and Docbook) and programs written in most popular
        programming languages (e.g., C, C++, C#, Shell Scripts,
        Python, Java, GNU awk, PHP, etc.).
    </para>

    <para>
        The localization process initiates by retriving translatable
        strings from source files.  When source files are XML-based
        files, the only requisite to retrive translatable strings
        correctly is that they be well-formed.  Beyond that, the
        <command>xml2po</command> command takes care of everything
        else.  When source files are Shell script files, it is
        necessary that you previously define what strings inside the
        script are considered as translatable strings in order for
        <command>xgettext</command> command to retrive them correctly.
        To define translatable strings inside shell scripts, you need
        to use either <command>gettext</command>,
        <command>ngettext</command>, <command>eval_gettext</command>
        or <command>eval_ngettext</command> command as it is following
        described:
    </para>

    <itemizedlist>
    <listitem>
    <para>
        Use the <command>gettext</command> command to display the
        native language translation of a textual message.
    </para>
    <screen>MESSAGE="`gettext "There is no entry to create."`"</screen>
    </listitem>

    <listitem>
    <para>
        Use the <command>ngettext</command> command to display the
        native language translation of a textual message whose
        grammatical form depends on a number.
    </para>
    <screen>MESSAGE="`ngettext "The following entry will be created" \
                   "The following entries will be created" \
                   $COUNT`:"</screen>
    </listitem>

    <listitem>
    <para>
        Use the <command>eval_gettext</command> command to display the
        native language translation of a textual message, performing
        dollar-substitution on the result.  Note that only shell
        variables mentioned in the message will be dollar-substituted
        in the result.
    </para>
    <screen>MESSAGE="`eval_gettext "The location \\\"\\\$LOCATION\\\" is not valid."`"</screen>
    </listitem>

    <listitem>
    <para>
        Use the <command>eval_ngettext</command> command to display
        the native language translation of a textual message whose
        grammatical form depends on a number, performing
        dollar-substitution on the result.  Note that only shell
        variables mentioned in messages will be dollar-substituted in
        the result.
    </para>
    <screen>MESSAGE="`eval_ngettext "The following entry will be created in \\\$LOCATION" \
                        "The following entries will be created in \\\$LOCATION" \
                        $COUNT`:"</screen>
    </listitem>
    </itemizedlist>

    <para>
        Once translatable strings are retrived, a portable object
        template (POT) file is created for storing them. Later, the
        POT file is used to create a portable object (PO). The
        portable object is the place where localization itself takes
        place, it is the file translators edit to localize messages.
        When translatable strings change inside source files, it is
        necessary that you update these POT and PO files in order to
        keep consistency between source file messages and their
        localized versions.
    </para>

    <para>
        Inside source files, translatable strings are always written
        in English language. In order to localize translatable strings
        from English language to another language, you need to be sure
        the <envar>LANG</envar> environment variable has been already
        set to the locale code you want to localize message for or see
        them printed out before running the
        <function>locale</function> functionality of
        <command>centos-art.sh</command> script.  Localizing English
        language to itself is not supported.
    </para>

    <para>
        To have a list of all locale codes you can have localized
        messages for, run the following command: <command>locale -a |
        less</command>.
    </para>
    </refsection>

    <refsection id="scripts-bash-locale-environment">
    <title>Function Specific Environment</title>
    <para>
        ...
    </para>
    </refsection>

    <refsection id="scripts-bash-locale-authors">
    <title>Authors</title>
    <para>
        The following people have worked in the
        <function>locale</function> functionality:
    </para>
    <itemizedlist>
    <listitem>
    <para>
        Alain Reguera Delgado &lt;<ulink url="mailto:alain.reguera@gmail.com">alain.reguera@gmail.com</ulink>&gt;, =COPYRIGHT_YEAR_LIST=
    </para>
    </listitem>
    </itemizedlist>
    </refsection>

    <refsection id="scripts-bash-locale-licence">
    <title>License</title>

    <para>
        Copyright &copy; =COPYRIGHT_YEAR_LIST= The CentOS Project
    </para>
 
    <para>
        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.
    </para>
 
    <para>
        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.
    </para>
 
    <para>
        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., 675 Mass Ave, Cambridge, MA 02139,
        USA.
    </para>
    </refsection>

</refentry>