doc/html/ch04s05.html

   1 <html><head>
   2       <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
   3    <title>4.5. 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.6.0: Installation, Konfiguration, Entwicklung"><link rel="up" href="ch04.html" title="Kapitel 4. Entwicklerdokumentation"><link rel="prev" href="ch04s04.html" title="4.4. SQL-Upgradedateien"><link rel="next" href="ch04s06.html" title="4.6. 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.5. Translations and languages</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ch04s04.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="ch04s06.html">Weiter</a></td></tr></table><hr></div><div class="sect1" title="4.5. Translations and languages"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="translations-languages"></a>4.5. Translations and languages</h2></div></div></div><div class="sect2" title="4.5.1. Introduction"><div class="titlepage"><div><div><h3 class="title"><a name="translations-languages.introduction"></a>4.5.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.5.2. Character set"><div class="titlepage"><div><div><h3 class="title"><a name="translations-languages.character-set"></a>4.5.2. Character set</h3></div></div></div><p>All files included in a language pack must use UTF-8 as their
   8         encoding.</p></div><div class="sect2" title="4.5.3. File structure"><div class="titlepage"><div><div><h3 class="title"><a name="translations-languages.file-structure"></a>4.5.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
   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">all</span></dt><dd><p>This file is mandatory.</p><p>The central translation file. It is essentially an inline
  18               Perl script autogenerated by <span class="command"><strong>locales.pl</strong></span>. To
  19               generate it, generate the directory and the two files mentioned
  20               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.
  21               You will be told how many are missing like this:</p><pre class="programlisting">$ scripts/locales.pl en
  22 English - 0.6% - 2015/2028 missing</pre><p>A file named "<code class="filename">missing</code>" will be
  23               generated and can be edited. You can also edit the
  24               "<code class="filename">all</code>" file directly. Edit everything you
  25               like to fit the target language and execute
  26               <span class="command"><strong>locales.pl</strong></span> again. See how the missing words
  27               get fewer.</p></dd><dt><span class="term">Num2text</span></dt><dd><p>Legacy code from SQL Ledger. It provides a means for
  28               numbers to be converted into natural language, like
  29               <code class="literal">1523 =&gt; one thousand five hundred twenty
  30               three</code>. If you want to provide it, it must be inlinable
  31               Perl code which provides a <code class="function">num2text</code> sub. If
  32               an <code class="function">init</code> sub exists it will be executed
  33               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
  34               formats, some of which are rather picky with their accepted
  35               charset. The <code class="filename">special_chars</code> file contains a
  36               listing of chars not suited for different file format and
  37               provides substitutions. It is written in "Simple Ini" style,
  38               containing a block for every file format.</p><p>First entry should be the order of substitution for
  39               entries as a whitespace separated list. All entries are
  40               interpolated, so <code class="literal">\n</code>, <code class="literal">\x20</code>
  41               and <code class="literal">\\</code> all work.</p><p>After that every entry is a special char that should be
  42               translated when writing text into such a file.</p><p>Example:</p><pre class="programlisting">[Template/XML]
  43 order=&amp; &lt; &gt; \n
  44 &amp;=&amp;amp;
  45 &lt;=&amp;lt;
  46 &gt;=&amp;gt;
  47 \n=&lt;br&gt;</pre><p>Note the importance of the order in this example.
  48               Substituting &lt; and &gt; befor &amp; would lead to $gt; become
  49               &amp;amp;gt;</p><p>For a list of valid formats, see the German
  50               <code class="filename">special_chars</code> entry. As of this writing the
  51               following are recognized:</p><pre class="programlisting">HTML
  52 URL@HTML
  53 Template/HTML
  54 Template/XML
  55 Template/LaTeX
  56 Template/OpenDocument
  57 filenames</pre><p>The last of which is very machine dependent. Remember that
  58               a lot of characters are forbidden by some filesystems, for
  59               example MS Windows doesn't like ':' in its files where Linux
  60               doesn't mind that. If you want the files created with your
  61               language pack to be portable, find all chars that could cause
  62               trouble.</p></dd><dt><span class="term">missing</span></dt><dd><p>This file is not a part of the language package
  63               itself.</p><p>This is a file generated by
  64               <span class="command"><strong>scripts/locales.pl</strong></span> while processing your
  65               locales. It's only to have the missing entries singled out and
  66               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
  67               itself.</p><p>Another file generated by
  68               <span class="command"><strong>scripts/locales.pl</strong></span>. If for any reason a
  69               translation does not appear anymore and can be deleted, it gets
  70               moved here. The last 50 or so entries deleted are saved here in
  71               case you made a typo, so that you don't have to translate
  72               everything again. If a tranlsation is missing, the lost file is
  73               checked first. If you maintain a language package, you might
  74               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
  75               itself.</p><p>If the directory more exists and contains a file called
  76               all it will be parsed in addition to the mandatory all (see
  77               above). The file is useful if you want to change some
  78               translations for the current installation without conflicting
  79               further upgrades. The file is not autogenerated and has the same
  80               format as the all, but needs another key (more_texts). See the
  81               german translation for an example or copy the following code:
  82               </p><pre class="programlisting">
  83 #!/usr/bin/perl
  84 # -*- coding: utf-8; -*-
  85 # vim: fenc=utf-8
  86
  87 use utf8;
  88
  89 # These are additional texts for custom translations.
  90 # The format is the same as for the normal file all, only
  91 # with another key (more_texts instead of texts).
  92 # The file has the form of 'english text'  =&gt; 'foreign text',
  93
  94 $self-&gt;{more_texts} = {
  95
  96   'Ship via'                    =&gt; 'Terms of delivery',
  97   'Shipping Point'              =&gt; 'Delivery time',
  98 }
  99               </pre><p>
 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="ch04s04.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="ch04s06.html">Weiter</a></td></tr><tr><td width="40%" align="left" valign="top">4.4. 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.6. Die kivitendo-Test-Suite</td></tr></table></div></body></html>