doc/html/ch04s04.html

   1 <html><head>
   2       <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
   3    <title>4.4. Translations and languages</title><link rel="stylesheet" type="text/css" href="style.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.1-RC2"><link rel="home" href="index.html" title="kivitendo 3.0.0: Installation, Konfiguration, Entwicklung"><link rel="up" href="ch04.html" title="Kapitel 4. Entwicklerdokumentation"><link rel="prev" href="ch04s03.html" title="4.3. SQL-Upgradedateien"><link rel="next" href="ch04s05.html" title="4.5. Die kivitendo-Test-Suite"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">4.4. Translations and languages</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ch04s03.html">Zurück</a>&nbsp;</td><th width="60%" align="center">Kapitel 4. Entwicklerdokumentation</th><td width="20%" align="right">&nbsp;<a accesskey="n" href="ch04s05.html">Weiter</a></td></tr></table><hr></div><div class="sect1" title="4.4. Translations and languages"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="translations-languages"></a>4.4. Translations and languages</h2></div></div></div><div class="sect2" title="4.4.1. Introduction"><div class="titlepage"><div><div><h3 class="title"><a name="translations-languages.introduction"></a>4.4.1. Introduction</h3></div></div></div><div class="note" title="Anmerkung" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Anmerkung]" src="system/docbook-xsl/images/note.png"></td><th align="left">Anmerkung</th></tr><tr><td align="left" valign="top"><p>Dieser Abschnitt ist in Englisch geschrieben, um
   4           internationalen Übersetzern die Arbeit zu erleichtern.</p></td></tr></table></div><p>This section describes how localization packages in kivitendo
   5         are built. Currently the only language fully supported is German, and
   6         since most of the internal messages are held in English the English
   7         version is usable too.</p><p>A stub version of French is included but not functunal at this
   8         point.</p></div><div class="sect2" title="4.4.2. File structure"><div class="titlepage"><div><div><h3 class="title"><a name="translations-languages.file-structure"></a>4.4.2. File structure</h3></div></div></div><p>The structure of locales in kivitendo is:</p><pre class="programlisting">kivitendo/locale/&lt;langcode&gt;/</pre><p>where &lt;langcode&gt; stands for an abbreviation of the
   9         language package. The builtin packages use two letter <a class="ulink" href="http://en.wikipedia.org/wiki/ISO_639-1" target="_top">ISO 639-1</a> codes,
  10         but the actual name is not relevant for the program and can easily be
  11         extended to <a class="ulink" href="http://en.wikipedia.org/wiki/IETF_language_tag" target="_top">IETF language
  12         tags</a> (i.e. "en_GB"). In fact the original language packages
  13         from SQL Ledger are named in this way.</p><p>In such a language directory the following files are
  14         recognized:</p><div class="variablelist"><dl><dt><span class="term">LANGUAGE</span></dt><dd><p>This file is mandatory.</p><p>The <code class="filename">LANGUAGE</code> file contains the self
  15               descripted name of the language. It should contain a native
  16               representation first, and in parenthesis an english translation
  17               after that. Example:</p><pre class="programlisting">Deutsch (German)</pre></dd><dt><span class="term">charset</span></dt><dd><p>This file should be present.</p><p>The <code class="filename">charset</code> file describes which
  18               charset a language package is written in and applies to all
  19               other language files in the package. It is possible to write
  20               some language packages without an explicit charset, but it is
  21               still strongly recommended. You'll never know in what
  22               environment your language package will be used, and neither
  23               UTF-8 nor Latin1 are guaranteed.</p><p>The whole content of this file is a string that can be
  24               recognized as a valid charset encoding. Example:</p><pre class="programlisting">UTF-8</pre></dd><dt><span class="term">all</span></dt><dd><p>This file is mandatory.</p><p>The central translation file. It is essentially an inline
  25               Perl script autogenerated by <span class="command"><strong>locales.pl</strong></span>. To
  26               generate it, generate the directory and the two files mentioned
  27               above, and execute the following command:</p><pre class="programlisting">scripts/locales.pl &lt;langcode&gt;</pre><p>Otherwise you can simply copy one of the other languages.
  28               You will be told how many are missing like this:</p><pre class="programlisting">$ scripts/locales.pl en
  29 English - 0.6% - 2015/2028 missing</pre><p>A file named "<code class="filename">missing</code>" will be
  30               generated and can be edited. You can also edit the
  31               "<code class="filename">all</code>" file directly. Edit everything you
  32               like to fit the target language and execute
  33               <span class="command"><strong>locales.pl</strong></span> again. See how the missing words
  34               get fewer.</p></dd><dt><span class="term">Num2text</span></dt><dd><p>Legacy code from SQL Ledger. It provides a means for
  35               numbers to be converted into natural language, like
  36               <code class="literal">1523 =&gt; one thousand five hundred twenty
  37               three</code>. If you want to provide it, it must be inlinable
  38               Perl code which provides a <code class="function">num2text</code> sub. If
  39               an <code class="function">init</code> sub exists it will be executed
  40               first.</p><p>Only used in the check and receipt printing module.</p></dd><dt><span class="term">special_chars</span></dt><dd><p>kivitendo comes with a lot of interfaces to different
  41               formats, some of which are rather picky with their accepted
  42               charset. The <code class="filename">special_chars</code> file contains a
  43               listing of chars not suited for different file format and
  44               provides substitutions. It is written in "Simple Ini" style,
  45               containing a block for every file format.</p><p>First entry should be the order of substitution for
  46               entries as a whitespace separated list. All entries are
  47               interpolated, so <code class="literal">\n</code>, <code class="literal">\x20</code>
  48               and <code class="literal">\\</code> all work.</p><p>After that every entry is a special char that should be
  49               translated when writing text into such a file.</p><p>Example:</p><pre class="programlisting">[Template/XML]
  50 order=&amp; &lt; &gt; \n
  51 &amp;=&amp;amp;
  52 &lt;=&amp;lt;
  53 &gt;=&amp;gt;
  54 \n=&lt;br&gt;</pre><p>Note the importance of the order in this example.
  55               Substituting &lt; and &gt; befor &amp; would lead to $gt; become
  56               &amp;amp;gt;</p><p>For a list of valid formats, see the German
  57               <code class="filename">special_chars</code> entry. As of this writing the
  58               following are recognized:</p><pre class="programlisting">HTML
  59 URL@HTML
  60 Template/HTML
  61 Template/XML
  62 Template/LaTeX
  63 Template/OpenDocument
  64 filenames</pre><p>The last of which is very machine dependant. Remember that
  65               a lot of characters are forbidden by some filesystems, for
  66               exmaple MS Windows doesn't like ':' in its files where Linux
  67               doesn't mind that. If you want the files created with your
  68               language pack to be portable, find all chars that could cause
  69               trouble.</p></dd><dt><span class="term">missing</span></dt><dd><p>This file is not a part of the language package
  70               itself.</p><p>This is a file generated by
  71               <span class="command"><strong>scripts/locales.pl</strong></span> while processing your
  72               locales. It's only to have the missing entries singled out and
  73               does not belong to a language package.</p></dd><dt><span class="term">lost</span></dt><dd><p>This file is not a part of the language package
  74               itself.</p><p>Another file generated by
  75               <span class="command"><strong>scripts/locales.pl</strong></span>. If for any reason a
  76               translation does not appear anymore and can be deleted, it gets
  77               moved here. The last 50 or so entries deleted are saved here in
  78               case you made a typo, so that you don't have to translate
  79               everything again. If a tranlsation is missing, the lost file is
  80               checked first. If you maintain a language package, you might
  81               want to keep this safe somewhere.</p></dd></dl></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch04s03.html">Zurück</a>&nbsp;</td><td width="20%" align="center"><a accesskey="u" href="ch04.html">Nach oben</a></td><td width="40%" align="right">&nbsp;<a accesskey="n" href="ch04s05.html">Weiter</a></td></tr><tr><td width="40%" align="left" valign="top">4.3. SQL-Upgradedateien&nbsp;</td><td width="20%" align="center"><a accesskey="h" href="index.html">Zum Anfang</a></td><td width="40%" align="right" valign="top">&nbsp;4.5. Die kivitendo-Test-Suite</td></tr></table></div></body></html>