<?xml version="1.0"?>
<document>

  <properties>
  <author email="lolando@debian.org">Roland Mas</author>
  <author email="reinhard@spisser.it">Reinhard Spisser</author>
    <title>Gforge: Localization</title>
  </properties>

  <body>


<section name="Localizing Gforge">
<p>
This short HOWTO explains how you can customise your local
installation of Gforge.
<p/>
It was written by Roland Mas &lt;lolando@debian.org&gt;.



</p>
</section>
<section name="Adding a new language">
<p>
These are the steps to add a new language:
<ol>
<li>add a row in the <code> supported_languages</code> table in the gforge database:<p/>
<code>

INSERT INTO SUPPORTED_LANGUAGES (language_id, name, filename, classname, language_code)   VALUES (NEXTVAL('"supported_langu_language_id_seq"'::text), 'German (Austria)', 'Austrian.class', 'Austrian', 'AT');

</code>
<br/>
Note that the language_code should follow the international language codings.
</li>
<li>Copy the file Base.tab to  Austrian.tab and place it in the
<code>www/languages/include</code> folder

</li>
<li>Translate the document</li>
<li>Submit the translation to the gforge project</li>

</ol>

</p>
</section>


<section name="What is there to customise?">

  I'm afraid there isn't much space for customisation in Gforge
yet.  For now, two main areas exist:
<ul>
<li>look;</li>
<li> text content.</li>
</ul>

  The look of your Gforge site is customisable via the
theme system (read the README.Themes file fo more information on
this).

  The text content can be somewhat customised.  The Gforge
internationalisation system already provides a way to have different
texts depending on user choice. 

</section>
<section name="How do i customise texts?">
<p>
  First, a quick course on the internationalisation system present in
Gforge.
<p/>
  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.  
<p/>
In Gforge, this handle is made up of the
"page name" and the "category" 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 "handles".  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.
<p/>
The language files are located in the <code>www/include/languages</code> directory.
  To localize Gforge in a new language, copy Base.tab in &amp;lt;yourlanguage&amp;gt;.tab.If you wish to add Foobaric language, run the following command
<source><![CDATA[
cp Base.tab Foobaric.tab
]]></source>

<p/>
</p>
</section>
<section name="Format of the *.tab files">
<p>
  The *.tab files are in a fairly straightforward format.  Lines
starting with a '#' character are ignored, other lines must be in the
following format:
<source><![CDATA[
,----
| <pagename> TAB <category> TAB <data>
`---
]]></source>

  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 <code>getText('&lt;pagename&gt;','&lt;category'&gt;)</code> string in the scripts
contained in the <code>www/</code> and <code>common/</code>.  This is not
always easy to do.

  Your best bet is to guess the meaning of the $1, $2, etc. variables
from the non-customised text (either Base.tab or Foobaric.tab if it is
defined).
</p>
</section>
<section name="How to do it - really">
<p>
The way I usually go when I have to customise some text is simply the
following:
<p/>
<ol>
<li> Find the bit of text I want to customise (in either Base.tab or
   Foobaric.tab);</li>
<li> Copy and paste the appropriate line (including the "handle" -- the
   first two fields) in Foobaric.tab;</li>
<li> Read it to find out about the $n variables;</li>
<li> Replace the third field with my own customised version.</li>
</ol>
</p>
</section>
<section name="Why Customise">
<p>
There are two main reasons you would want to use the process described
in this section.
<p/>
  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.
<p/>
  Second, localisation.  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 obviously
complete.  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 <a hre="http://gforge.org/">Gforge.org</a> for info on how
to do that.
</p>
</section>
</body>
</document>
