<?xml version="1.0" encoding="iso-8859-1"?>
<chapter id="coding_translating">
  <title>How to translate Moregroupware</title>
  
  <para>This document describes the way of localize moregroupware or special modules
    of moregroupware. It should give the reader the chance to add a complete new
    language to moregroupware or to a module within the moregroupware framework.
  </para>
  
  <section id="coding_translating_structure">
    <title>Structure of Moregroupware</title>
    
    <para>The graphic below demonstrates the directory structure of moregroupware. On the
      first level you have the modules, in the shown tree you can see the module "admin";
      and the module "calendar". There are also some folders which are on the first level
      which are not a module but other application based directories, but thats not the focus
      of the document. We will use the "calendar" module for a detailed explanation:
    </para>
    
    <figure>
      <title>Moregroupware Tree</title>
      <graphic fileref="images/coding_translating/mgwtree1.png"/>
    </figure>
    
    <para>The lang folder contains language files for a certain language.</para>
    <para>
      A moregoupware language file has the following file name: <filename>m.x.lang</filename>, where m = module name, x = international language code.
    </para>
    
    <important>
      <para>Each module has this language structure, or at least, it must have it to be moregroupware compliant.</para>
    </important>
    
  </section>
  
  <section id="coding_translating_langfiles">
    <title>Moregroupware lang-file</title>
    
    <para>The Moregroupware language file conists of 2 parts, the key and the text. The parts
      are seperated by an equal (=) sign. Below is a simple example of an english and a german
      language file:
    </para>
    
    <para>english lang-file from calendar module (calendar.en.lang)</para>
    <programlisting>collisionwith = collision with
      date = Date
      dateconflict = dateconflict
      desc = Description
      dobook = book
    </programlisting>
    
    <para>german lang-file from calendar module (calendar.de.lang)</para>
    <programlisting>collisionwith = kollidiert mit
      date = Datum
      dateconflict = Terminkonflikt
      desc = Beschreibung
      description = Beschreibung
      dobook = buchen
    </programlisting>
    
    <para>As you can see only the right side of the "=" sign will be modified. So if you want
      to create a new language file for a module or for all modules, you must copy an existent
      lang file you understand (i assume english) to a new file named calendar.it.lang, if you want
      to translate to italien, or to calendar.ru.lang if you want to translate to russian. Then
      modify the file and edit the text on the right of the "=" sign on each line.
    </para>
    
    <section id="coding_translating_newline">
      <title>Using newslines for long text</title>
      
      <para>As you can see, this is not very comfortable for long texts, because you may have
        to scroll to the right if you have two or more sentences. Because of this you can
        insert newline and continue your text on the next line, the following example
        demonstrates this:
      </para>
      
      <programlisting>collisionwith = collision with
        another appointment, and this is not all. There was also a collision with my
        car the morning before, but this is only important to mention because
        i want to insert a really long text for the keyword collisionwith
        date = Date
      </programlisting>
      <para>You can see that the key "collisionwith" has a very long text and in
        fact it doesnt matter, moregroupware will handle this situation without
        any problems.
      </para>
    </section>
    
    <section id="coding_translating_langvars">
      <title>Variables inside lang files</title>
      <para>The moregroupware framework is capable of having variables inside
        text. This is very important because when moregroupware wants to
        display something like: "User Thomas Smith found 10 Contacts from 122", the text
        consists of normal text which must be translated and of variable parts like
        username (Thomas Smith) and records found (10 and 122). In order to handle this, the
        lang file can look like the following example:
      </para>
      <programlisting>myheader = User &lt;$1&gt; found &lt;$2&gt; Contacts from &lt;$3&gt;</programlisting>
      <para>or the german one:</para>
      <programlisting>myheader = Benutzer &lt;$1&gt; hat &lt;$2&gt; Kontakte von &lt;$3&gt; gefunden</programlisting>
      <para>Here you can see that moregroupware has no problems with different sentence
        structures, because you can place the variables wherever you want.
      </para>
    </section>
  </section>
  
  <section id="coding_translating_testlocal">
    <title>Test new language</title>
    <para>If you have sucessfully translated a module for moregoupware, which means
      you have added a new file for example "calendar.it.lang" (italian) to the lang
      directory of a module (calendar). You can check out your translation by following the steps below:
    </para>
    
    <itemizedlist>
      <listitem>
        <para>run following SQL against your moregroupware database: </para>
      </listitem>
      <listitem>
        <para>INSERT INTO `mgw_languages` (`langcode`, `description`, `active`, `lu_user`, `lu_date`) VALUES ('it', 'Italian', '1', 'admin', NOW()) </para>
      </listitem>
      <listitem>
        <para>open moregroupware and go to "settings" and "personal settings"</para>
      </listitem>
      <listitem>
        <para>change your language to the one you just created (here italian)</para>
      </listitem>
      <listitem>
        <para>go to your translated module and check the results</para>
      </listitem>
    </itemizedlist>
  </section>
  
  <section id="coding_translating_commerrors">
    <title>Common Errors</title>
    <para>There are some things to mention when localizing moregroupware. These problems will
      not remain for years, but at the moment, you must watch out for the following:
    </para>
    
    <section id="coding_translating_firstlocale">
      <title>When adding a completely new language... </title>
      <para>your first module translation should be "settings". Because when you
        add a new language and you translate only a module like calendar, moregroupware
        will fail in the same second when you switch your personal language to the
        new one. This is because the switching itself occurs in the module "settings" and
        before you have the chance to change to your translated module, moregroupware will search
        for a translation of "settings".
      </para>
    </section>
  </section>
  
</chapter>
