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.3.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></div><div class="sect2" title="4.4.2. Character set"><div class="titlepage"><div><div><h3 class="title"><a name="translations-languages.character-set"></a>4.4.2. Character set</h3></div></div></div><p>All files included in a language pack must use UTF-8 as their encoding.</p></div><div class="sect2" title="4.4.3. File structure"><div class="titlepage"><div><div><h3 class="title"><a name="translations-languages.file-structure"></a>4.4.3. 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
   8         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,
   9         but the actual name is not relevant for the program and can easily be
  10         extended to <a class="ulink" href="http://en.wikipedia.org/wiki/IETF_language_tag" target="_top">IETF language
  11         tags</a> (i.e. "en_GB"). In fact the original language packages
  12         from SQL Ledger are named in this way.</p><p>In such a language directory the following files are
  13         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
  14               descripted name of the language. It should contain a native
  15               representation first, and in parenthesis an english translation
  16               after that. Example:</p><pre class="programlisting">Deutsch (German)</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
  17               Perl script autogenerated by <span class="command"><strong>locales.pl</strong></span>. To
  18               generate it, generate the directory and the two files mentioned
  19               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.
  20               You will be told how many are missing like this:</p><pre class="programlisting">$ scripts/locales.pl en
  21 English - 0.6% - 2015/2028 missing</pre><p>A file named "<code class="filename">missing</code>" will be
  22               generated and can be edited. You can also edit the
  23               "<code class="filename">all</code>" file directly. Edit everything you
  24               like to fit the target language and execute
  25               <span class="command"><strong>locales.pl</strong></span> again. See how the missing words
  26               get fewer.</p></dd><dt><span class="term">Num2text</span></dt><dd><p>Legacy code from SQL Ledger. It provides a means for
  27               numbers to be converted into natural language, like
  28               <code class="literal">1523 =&gt; one thousand five hundred twenty
  29               three</code>. If you want to provide it, it must be inlinable
  30               Perl code which provides a <code class="function">num2text</code> sub. If
  31               an <code class="function">init</code> sub exists it will be executed
  32               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
  33               formats, some of which are rather picky with their accepted
  34               charset. The <code class="filename">special_chars</code> file contains a
  35               listing of chars not suited for different file format and
  36               provides substitutions. It is written in "Simple Ini" style,
  37               containing a block for every file format.</p><p>First entry should be the order of substitution for
  38               entries as a whitespace separated list. All entries are
  39               interpolated, so <code class="literal">\n</code>, <code class="literal">\x20</code>
  40               and <code class="literal">\\</code> all work.</p><p>After that every entry is a special char that should be
  41               translated when writing text into such a file.</p><p>Example:</p><pre class="programlisting">[Template/XML]
  42 order=&amp; &lt; &gt; \n
  43 &amp;=&amp;amp;
  44 &lt;=&amp;lt;
  45 &gt;=&amp;gt;
  46 \n=&lt;br&gt;</pre><p>Note the importance of the order in this example.
  47               Substituting &lt; and &gt; befor &amp; would lead to $gt; become
  48               &amp;amp;gt;</p><p>For a list of valid formats, see the German
  49               <code class="filename">special_chars</code> entry. As of this writing the
  50               following are recognized:</p><pre class="programlisting">HTML
  51 URL@HTML
  52 Template/HTML
  53 Template/XML
  54 Template/LaTeX
  55 Template/OpenDocument
  56 filenames</pre><p>The last of which is very machine dependant. Remember that
  57               a lot of characters are forbidden by some filesystems, for
  58               exmaple MS Windows doesn't like ':' in its files where Linux
  59               doesn't mind that. If you want the files created with your
  60               language pack to be portable, find all chars that could cause
  61               trouble.</p></dd><dt><span class="term">missing</span></dt><dd><p>This file is not a part of the language package
  62               itself.</p><p>This is a file generated by
  63               <span class="command"><strong>scripts/locales.pl</strong></span> while processing your
  64               locales. It's only to have the missing entries singled out and
  65               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
  66               itself.</p><p>Another file generated by
  67               <span class="command"><strong>scripts/locales.pl</strong></span>. If for any reason a
  68               translation does not appear anymore and can be deleted, it gets
  69               moved here. The last 50 or so entries deleted are saved here in
  70               case you made a typo, so that you don't have to translate
  71               everything again. If a tranlsation is missing, the lost file is
  72               checked first. If you maintain a language package, you might
  73               want to keep this safe somewhere.</p></dd><dt><span class="term">more/all</span></dt><dd><p>This subdir and file is not a part of the language package
  74               itself.</p><p>If the directory more exists and contains a file called all
  75               it will be parsed in addition to the mandatory all (see above).
  76               The file is useful if you want to change some translations for
  77               the current installation without conflicting further upgrades.
  78               The file is not autogenerated and has the same format as the all,
  79               but needs another key (more_texts). See the german translation
  80               for an example or copy the following code:
  81               </p><pre class="programlisting">
  82 #!/usr/bin/perl
  83 # -*- coding: utf-8; -*-
  84 # vim: fenc=utf-8
  85
  86 use utf8;
  87
  88 # These are additional texts for custom translations.
  89 # The format is the same as for the normal file all, only
  90 # with another key (more_texts instead of texts).
  91 # The file has the form of 'english text'  =&gt; 'foreign text',
  92
  93 $self-&gt;{more_texts} = {
  94
  95   'Ship via'                    =&gt; 'Terms of delivery',
  96   'Shipping Point'              =&gt; 'Delivery time',
  97 }
  98               </pre><p>
  99
 100                      </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>