[Gforge-commits] gforge/docs/docbook/docbook/contribution_guide/include howto_localization.xml, 1.1, 1.2

[gsmet]

Update of /cvsroot/gforge/gforge/docs/docbook/docbook/contribution_guide/include
In directory db.perdue.net:/tmp/cvs-serv26422/docbook/contribution_guide/include

Modified Files:
        howto_localization.xml 
Log Message:
updated the contribution guide


Index: howto_localization.xml
===================================================================
RCS file: 
/cvsroot/gforge/gforge/docs/docbook/docbook/contribution_guide/include/howto_localization.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -d -r1.1 -r1.2
--- howto_localization.xml      2 Mar 2004 16:58:39 -0000       1.1
+++ howto_localization.xml      16 Mar 2004 10:03:21 -0000      1.2
@@ -1,9 +1,39 @@
 <section id="cg_howto_localization">
        <title>Localization howto</title>
        <section>
-               <title>Localizing Gforge</title>
+               <title>GForge localization system and status</title>
                <para>
-                       This short HOWTO explains how you can customize your 
local installation of Gforge.
+                       This short HOWTO explains how you can customize your 
local installation of GForge.
+               </para>
+               <para>
+                       First, a quick course on the internationalisation 
system present in GForge.
+               </para>
+               <para>
+                       The texts you can read on the web pages are not 
hard-coded.
+                       Instead, they are displayed as results of a function of 
several parameters.
+                       One of these parameters is the language in which you 
wish to display a piece of information, and another is some handle to identify 
the information you want to display.
+                       In GForge, this handle is made up of the <quote>page 
name</quote> and the <quote>category</quote> strings.
+               </para>
+               <para>
+                       Knowing all the needed info, the function displays the 
appropriate text. How appropriate is this text?  Well, that depends. First, a 
basic set of texts is loaded. Historically, this set is loaded in English. This 
set of texts makes the Base class, storing texts for all known 
<quote>handles</quote>.
+               </para>
+               <para>
+                       This set of texts can then be partially or completely 
overloaded, e.g. for other languages: the handles present in the language 
overwrite the Base handles, and the ones not found keep their values from the 
Base class.
+               </para>
+               <para>
+                       The language files are located in the 
<filename>www/include/languages</filename> directory.
+               </para>
+               <para>The following languages are available in GForge :</para>
+               <itemizedlist>
+                       <listitem><para>The English language, being the 
original one in which GForge was written, is obviously 
complete.</para></listitem>
+                       <listitem><para>The french translation is 
complete.</para></listitem>
+                       <listitem><para>The Spanish (Castillan) translation is 
complete. The Spanish (Catalan) one is a work in progress.</para></listitem>
+                       <listitem><para>The Korean translation used to be 
complete.</para></listitem>
+                       <listitem><para>The Dutch, Italian, Portuguese 
Brazilian and Swedish translations are pretty well advanced but not regularly 
updated.</para></listitem>
+                       <listitem><para>The German, Japanese and Simplified 
Chinese translations are 20-50% complete.</para></listitem>
+               </itemizedlist>
+               <para>
+                       You might consider translating GForge into your 
language. If you do so, please also consider submitting your translated file to 
us so that future releases of GForge include your translated file by default.
                </para>
        </section>
        <section>
@@ -18,17 +48,16 @@
                                </para>
 <programlisting>
 INSERT INTO supported_languages
-       (language_id, name, filename, classname, language_code)
-       VALUES (NEXTVAL('"supported_langu_language_id_seq"'::text),
-               'German (Austria)',
+       (name, filename, classname, language_code)
+       VALUES ('German (Austria)',
                'Austrian.class',
                'Austrian',
-               'AT'
+               'at'
        );
 </programlisting>
                                <note>
                                        <para>
-                                               The language_code should follow 
the international language codings.
+                                               The language_code should follow 
the international language codings described in <ulink 
url="http://www.faqs.org/rfcs/rfc1766.html";>RFC 1766</ulink>. For example, 
Portuguese Brazilian code is pt-br and not pt_BR.
                                        </para>
                                </note>
                        </listitem>
@@ -40,87 +69,67 @@
                        <listitem>
                                <para>Translate the document</para>
                                <warning>
-                                       <para>If you are not going to translate 
the entire document, please just override strings you translate.</para>
+                                       <para>If you are not going to translate 
the entire document, <emphasis>please just override strings you 
translate</emphasis>.</para>
                                </warning>
                        </listitem>
                        <listitem>
-                               <para>Submit the translation to the gforge 
project</para>
+                               <para>Submit the translation to the GForge 
project</para>
                        </listitem>
                </orderedlist>
        </section>
        <section>
-               <title>What is there to customize?</title>
+               <title>Format of the *.tab files</title>
                <para>
-                       I'm afraid there isn't much space for customisation in 
Gforge yet.  For now, two main areas exist:
+                       The *.tab files are in a fairly straightforward format. 
 Lines starting with a '#' character are ignored, other lines must be in the 
following format:
                </para>
-               <itemizedlist>
-                       <listitem><para>look</para></listitem>
-                       <listitem><para>text content</para></listitem>
-               </itemizedlist>
+<programlisting><![CDATA[<pagename> TAB <category> TAB 
<data>]]></programlisting>
+               <warning>
+                       <para>Please be careful to use <keycap>TAB</keycap> and 
not <keycap>SPACE</keycap>.</para>
+               </warning>
                <para>
-                       The look of your Gforge site is customisable via the 
theme system (read the README.Themes file fo more information on this).
+                       The &lt;data&gt; field can use variables in the form 
$1, $2, etc.  These variables are defined by the script and there's no simple 
way of knowing what they are apart from looking at the script itself.  To find 
out exactly what these variables are filled out with, search for the 
<methodname>getText('&lt;pagename&gt;','&lt;category'&gt;)</methodname> string 
in the scripts contained in the <filename>www/</filename> and 
<filename>common/</filename>.  This is not always easy to do.
                </para>
                <para>
-                       The text content can be somewhat customized. The Gforge 
internationalisation system already provides a way to have different texts 
depending on user choice.
+                       Your best bet is to guess the meaning of the $1, $2, 
etc. variables from the non-customized text (either Base.tab or Foobaric.tab if 
it is defined).
                </para>
+               <warning>
+                       <para>*.tab files must be UTF-8 encoded.</para>
+               </warning>
        </section>
        <section>
-               <title>How do I customize texts?</title>
-               <para>
-                       First, a quick course on the internationalisation 
system present in Gforge.
-               </para>
+               <title>Updating a translation</title>
                <para>
-                       The texts you can read on the web pages are not 
hard-coded.  Well, some of them are, but we're working on them.  Instead, they 
are displayed as results of a function of several parameters.  One of these 
parameters is the language in which you wish to display a piece of information, 
and another is some handle to identify the information you want to display.
+                       GForge is constantly developed and so translation files 
are regularly outdated. Thus translations should be regularly updated to be 
uptodate.
                </para>
                <para>
-                       In Gforge, this handle is made up of the <quote>page 
name</quote> and the <quote>category</quote> strings.  Knowing all the needed 
info, the function displays the appropriate text.  How appropriate is this 
text?  Well, that depends.  First, a basic set of texts is loaded. 
Historically, this set is loaded in English.  This set of texts makes the Base 
class, storing texts for all known <quote>handles</quote>.  This set of texts 
can then be partially or completely overloaded, e.g. for other languages: the 
handles present in the language overwrite the Base handles, and the ones not 
found keep their values from the Base class.
+                       If you are maintaining a translation file, you may find 
useful <filename>language_file_merger.php</filename> script you can find in 
tools module (see <xref linkend="cg_cvs_repository" 
endterm="cg_cvs_repository.title" /> for more information).
                </para>
                <para>
-                       The language files are located in the 
<filename>www/include/languages</filename> directory.
+                       You can use the following command to merge your 
outdated language file with Base.tab :
                </para>
+               <programlisting role="shell"><![CDATA[php -q 
language_file_merger.php <your/gforge/install/root> <language> \
+1>merge.tab 2>merge.log]]></programlisting>
                <para>
-                       To localize Gforge in a new language, copy 
<filename>Base.tab</filename> in 
<filename><userinput>yourlanguage</userinput>.tab</filename>. If you wish to 
add Foobaric language, run the following command <command>cp Base.tab 
Foobaric.tab</command>.
+                       You have to check lines with #TO_TRANSLATE# and 
#TO_REMOVE# flags and respectively translate them and remove them. Lines are 
already sorted by alphabetical order so you just have to add header information 
found in the previous YourLanguage.tab file to merge.tab file and replace 
YourLanguage.tab by merge.tab.
                </para>
        </section>
        <section>
-               <title>Format of the *.tab files</title>
-               <para>
-                       The *.tab files are in a fairly straightforward format. 
 Lines starting with a '#' character are ignored, other lines must be in the 
following format:
-               </para>
-<programlisting><![CDATA[
-,----
-| <pagename> TAB <category> TAB <data>
-`---
-]]></programlisting>
+               <title>Text content customization</title>
                <para>
-                       The &lt;data&gt; field can use variables in the form 
$1, $2, etc.  These variables are defined by the script and there's no simple 
way of knowing what they are apart from looking at the script itself.  To find 
out exactly what these variables are filled out with, search for the 
<methodname>getText('&lt;pagename&gt;','&lt;category'&gt;)</methodname> string 
in the scripts contained in the <filename>www/</filename> and 
<filename>common/</filename>.  This is not always easy to do.
+                       The text content can be somewhat customized. The GForge 
internationalisation system already provides a way to have different texts 
depending on user choice.
                </para>
                <para>
-                       Your best bet is to guess the meaning of the $1, $2, 
etc. variables from the non-customized text (either Base.tab or Foobaric.tab if 
it is defined).
+                       You might want to change page footers, or contact 
pages, or host names, or whatever you need to integrate your GForge your target 
audience (company, organisation, or even your own personal GForge).
                </para>
-       </section>
-       <section>
-               <title>How to do it - really</title>
                <para>
-                       The way I usually go when I have to customize some text 
is simply the following:
+                       The way you should usually go when you have to 
customize some text is the following:
                </para>
                <orderedlist>
-                       <listitem><para>Find the bit of text I want to 
customize (in either Base.tab or Foobaric.tab);</para></listitem>
-                       <listitem><para>Copy and paste the appropriate line 
(including the <quote>handle</quote> -- the first two fields) in 
Foobaric.tab;</para></listitem>
+                       <listitem><para>Find the bit of text you want to 
customize in <filename>Foobaric.tab</filename>;</para></listitem>
+                       <listitem><para>Copy and paste the appropriate line 
(including the <quote>handle</quote> -- the first two fields) in 
<filename>/etc/gforge/languages-local/Foobaric.tab</filename> or for theme 
specific customization in 
<filename>/etc/gforge/languages-local/&lt;theme&gt;/Foobaric.tab</filename>;</para></listitem>
                        <listitem><para>Read it to find out about the $n 
variables;</para></listitem>
                        <listitem><para>Replace the third field with my own 
customized version.</para></listitem>
+                       <listitem><para>If you use the localization caching 
system, remove cache files.</para></listitem>
                </orderedlist>
        </section>
-       <section>
-               <title>Why customize</title>
-               <para>
-                       There are two main reasons you would want to use the 
process described in this section.
-               </para>
-               <para>
-                       First, local policy.  You might want to change page 
footers, or contact pages, or host names, or whatever you need to integrate 
your Gforge your target audience (company, organisation, or even your own 
personal GForge). This document is for you.
-               </para>
-               <para>
-                       Second, localization.  This is not something completely 
done in Gforge yet, and you might (will?) find huge gaps in the translation of 
Gforge into your language.  The English language, being the original one in 
which Gforge was written, is obviouslycomplete. Soon-Son Kwon has provided a 
full Korean translation, and I strive to make the French translation complete 
too, but other languages are far from finished.  You might then consider 
translating Gforge into your language.  If you do so, please also consider 
submitting your translated file to us so that future releases of Gforge include 
your translated file by default. Please refer to <ulink 
url="http://gforge.org/";>gforge.org</ulink> for info on how to do that.
-               </para>
-       </section>
-</section>
+</section>
\ No newline at end of file