Projekt

Allgemein

Profil

« Zurück | Weiter » 

Revision 42298d2c

Von Moritz Bunkus vor etwa 6 Jahren hinzugefügt

  • ID 42298d2ceb5206a3d8df0a5cd9989eff5ebb843e
  • Vorgänger 60b17b30
  • Nachfolger 822f5cf7

Dokumentation: HTML & PDF gebaut

Unterschiede anzeigen:

doc/html/ch04s04.html
<html><head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<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.5.3: 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
internationalen Übersetzern die Arbeit zu erleichtern.</p></td></tr></table></div><p>This section describes how localization packages in kivitendo
are built. Currently the only language fully supported is German, and
since most of the internal messages are held in English the English
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
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,
but the actual name is not relevant for the program and can easily be
extended to <a class="ulink" href="http://en.wikipedia.org/wiki/IETF_language_tag" target="_top">IETF language
tags</a> (i.e. "en_GB"). In fact the original language packages
from SQL Ledger are named in this way.</p><p>In such a language directory the following files are
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
descripted name of the language. It should contain a native
representation first, and in parenthesis an english translation
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
Perl script autogenerated by <span class="command"><strong>locales.pl</strong></span>. To
generate it, generate the directory and the two files mentioned
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.
You will be told how many are missing like this:</p><pre class="programlisting">$ scripts/locales.pl en
English - 0.6% - 2015/2028 missing</pre><p>A file named "<code class="filename">missing</code>" will be
generated and can be edited. You can also edit the
"<code class="filename">all</code>" file directly. Edit everything you
like to fit the target language and execute
<span class="command"><strong>locales.pl</strong></span> again. See how the missing words
get fewer.</p></dd><dt><span class="term">Num2text</span></dt><dd><p>Legacy code from SQL Ledger. It provides a means for
numbers to be converted into natural language, like
<code class="literal">1523 =&gt; one thousand five hundred twenty
three</code>. If you want to provide it, it must be inlinable
Perl code which provides a <code class="function">num2text</code> sub. If
an <code class="function">init</code> sub exists it will be executed
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
formats, some of which are rather picky with their accepted
charset. The <code class="filename">special_chars</code> file contains a
listing of chars not suited for different file format and
provides substitutions. It is written in "Simple Ini" style,
containing a block for every file format.</p><p>First entry should be the order of substitution for
entries as a whitespace separated list. All entries are
interpolated, so <code class="literal">\n</code>, <code class="literal">\x20</code>
and <code class="literal">\\</code> all work.</p><p>After that every entry is a special char that should be
translated when writing text into such a file.</p><p>Example:</p><pre class="programlisting">[Template/XML]
order=&amp; &lt; &gt; \n
&amp;=&amp;amp;
&lt;=&amp;lt;
&gt;=&amp;gt;
\n=&lt;br&gt;</pre><p>Note the importance of the order in this example.
Substituting &lt; and &gt; befor &amp; would lead to $gt; become
&amp;amp;gt;</p><p>For a list of valid formats, see the German
<code class="filename">special_chars</code> entry. As of this writing the
following are recognized:</p><pre class="programlisting">HTML
URL@HTML
Template/HTML
Template/XML
Template/LaTeX
Template/OpenDocument
filenames</pre><p>The last of which is very machine dependant. Remember that
a lot of characters are forbidden by some filesystems, for
example MS Windows doesn't like ':' in its files where Linux
doesn't mind that. If you want the files created with your
language pack to be portable, find all chars that could cause
trouble.</p></dd><dt><span class="term">missing</span></dt><dd><p>This file is not a part of the language package
itself.</p><p>This is a file generated by
<span class="command"><strong>scripts/locales.pl</strong></span> while processing your
locales. It's only to have the missing entries singled out and
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
itself.</p><p>Another file generated by
<span class="command"><strong>scripts/locales.pl</strong></span>. If for any reason a
translation does not appear anymore and can be deleted, it gets
moved here. The last 50 or so entries deleted are saved here in
case you made a typo, so that you don't have to translate
everything again. If a tranlsation is missing, the lost file is
checked first. If you maintain a language package, you might
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
itself.</p><p>If the directory more exists and contains a file called
all it will be parsed in addition to the mandatory all (see
above). The file is useful if you want to change some
translations for the current installation without conflicting
further upgrades. The file is not autogenerated and has the same
format as the all, but needs another key (more_texts). See the
german translation for an example or copy the following code:
</p><pre class="programlisting">
#!/usr/bin/perl
# -*- coding: utf-8; -*-
# vim: fenc=utf-8
<title>4.4. SQL-Upgradedateien</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.5.3: Installation, Konfiguration, Entwicklung"><link rel="up" href="ch04.html" title="Kapitel 4. Entwicklerdokumentation"><link rel="prev" href="ch04s03.html" title="4.3. Programmatische API-Aufrufe"><link rel="next" href="ch04s05.html" title="4.5. Translations and languages"></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. SQL-Upgradedateien</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. SQL-Upgradedateien"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="db-upgrade-files"></a>4.4. SQL-Upgradedateien</h2></div></div></div><div class="sect2" title="4.4.1. Einführung"><div class="titlepage"><div><div><h3 class="title"><a name="db-upgrade-files.introduction"></a>4.4.1. Einführung</h3></div></div></div><p>Datenbankupgrades werden über einzelne Upgrade-Scripte
gesteuert, die sich im Verzeichnis
<code class="filename">sql/Pg-upgrade2</code> befinden. In diesem Verzeichnis
muss pro Datenbankupgrade eine Datei existieren, die neben den
eigentlich auszuführenden SQL- oder Perl-Befehlen einige
Kontrollinformationen enthält.</p><p>Kontrollinformationen definieren Abhängigkeiten und Prioritäten,
sodass Datenbankscripte zwar in einer sicheren Reihenfolge ausgeführt
werden (z.B. darf ein <code class="literal">ALTER TABLE</code> erst ausgeführt
werden, wenn die Tabelle mit <code class="literal">CREATE TABLE</code> angelegt
wurde), diese Reihenfolge aber so flexibel ist, dass man keine
Versionsnummern braucht.</p><p>kivitendo merkt sich dabei, welches der Upgradescripte in
<code class="filename">sql/Pg-upgrade2</code> bereits durchgeführt wurde und
führt diese nicht erneut aus. Dazu dient die Tabelle
"<code class="literal">schema_info</code>", die bei der Anmeldung automatisch
angelegt wird.</p></div><div class="sect2" title="4.4.2. Format der Kontrollinformationen"><div class="titlepage"><div><div><h3 class="title"><a name="db-upgrade-files.format"></a>4.4.2. Format der Kontrollinformationen</h3></div></div></div><p>Die Kontrollinformationen sollten sich am Anfang der jeweiligen
Upgradedatei befinden. Jede Zeile, die Kontrollinformationen enthält,
hat dabei das folgende Format:</p><p>Für SQL-Upgradedateien:</p><pre class="programlisting">-- @key: value</pre><p>Für Perl-Upgradedateien:</p><pre class="programlisting"># @key: value</pre><p>Leerzeichen vor "<code class="varname">value</code>" werden
entfernt.</p><p>Die folgenden Schlüsselworte werden verarbeitet:</p><div class="variablelist"><dl><dt><span class="term">
<code class="varname">tag</code>
</span></dt><dd><p>Wird zwingend benötigt. Dies ist der "Name" des Upgrades.
Dieser "tag" kann von anderen Kontrolldateien in ihren
Abhängigkeiten verwendet werden (Schlüsselwort
"<code class="varname">depends</code>"). Der "tag" ist auch der Name, der
in der Datenbank eingetragen wird.</p><p>Normalerweise sollte die Kontrolldatei genau so heißen wie
der "tag", nur mit der Endung ".sql" bzw. "pl".</p><p>Ein Tag darf nur aus alphanumerischen Zeichen sowie den
Zeichen _ - ( ) bestehen. Insbesondere sind Leerzeichen nicht
erlaubt und sollten stattdessen mit Unterstrichen ersetzt
werden.</p></dd><dt><span class="term">
<code class="varname">charset</code>
</span></dt><dd><p>Empfohlen. Gibt den Zeichensatz an, in dem das Script
geschrieben wurde, z.B. "<code class="literal">UTF-8</code>". Aus
Kompatibilitätsgründen mit alten Upgrade-Scripten wird bei
Abwesenheit des Tags für SQL-Upgradedateien der Zeichensatz
"<code class="literal">ISO-8859-15</code>" angenommen. Perl-Upgradescripte
hingegen müssen immer in UTF-8 encodiert sein und sollten
demnach auch ein "<code class="literal">use utf8;</code>"
enthalten.</p></dd><dt><span class="term">
<code class="varname">description</code>
</span></dt><dd><p>Benötigt. Eine Beschreibung, was in diesem Update
passiert. Diese wird dem Benutzer beim eigentlichen
Datenbankupdate angezeigt. Während der Tag in Englisch gehalten
sein sollte, sollte die Beschreibung auf Deutsch
erfolgen.</p></dd><dt><span class="term">
<code class="varname">depends</code>
</span></dt><dd><p>Optional. Eine mit Leerzeichen getrennte Liste von "tags",
von denen dieses Upgradescript abhängt. kivitendo stellt sicher,
dass die in dieser Liste aufgeführten Scripte bereits
durchgeführt wurden, bevor dieses Script ausgeführt wird.</p><p>Abhängigkeiten werden rekursiv betrachtet. Wenn also ein
Script "b" existiert, das von Änderungen in "a" abhängt, und
eine neue Kontrolldatei für "c" erstellt wird, die von
Änderungen in "a" und "b" abhängt, so genügt es, in "c" nur den
Tag "b" als Abhängigkeit zu definieren.</p><p>Es ist nicht erlaubt, sich selbst referenzierende
Abhängigkeiten zu definieren (z.B. "a" -&gt; "b", "b" -&gt; "c"
und "c" -&gt; "a").</p></dd><dt><span class="term">
<code class="varname">priority</code>
</span></dt><dd><p>Optional. Ein Zahlenwert, der die Reihenfolge bestimmt, in
der Scripte ausgeführt werden, die die gleichen
Abhängigkeitstiefen besitzen. Fehlt dieser Parameter, so wird
der Wert 1000 benutzt.</p><p>Dies ist reine Kosmetik. Für echte Reihenfolgen muss
"depends" benutzt werden. kivitendo sortiert die auszuführenden
Scripte zuerst nach der Abhängigkeitstiefe (wenn "z" von "y"
abhängt und "y" von "x", so hat "z" eine Abhängigkeitstiefe von
2, "y" von 1 und "x" von 0. "x" würde hier zuerst ausgeführt,
dann "y", dann "z"), dann nach der Priorität und bei gleicher
Priorität alphabetisch nach dem "tag".</p></dd><dt><span class="term">
<code class="varname">ignore</code>
</span></dt><dd><p>Optional. Falls der Wert auf 1 (true) steht, wird das
Skript bei der Anmeldung ignoriert und entsprechend nicht
ausgeführt.</p></dd></dl></div></div><div class="sect2" title="4.4.3. Format von in Perl geschriebenen Datenbankupgradescripten"><div class="titlepage"><div><div><h3 class="title"><a name="db-upgrade-files.format-perl-files"></a>4.4.3. Format von in Perl geschriebenen
Datenbankupgradescripten</h3></div></div></div><p>In Perl geschriebene Datenbankscripte werden nicht einfach so
ausgeführt sondern müssen sich an gewisse Konventionen halten. Dafür
bekommen sie aber auch einige Komfortfunktionen bereitgestellt.</p><p>Ein Upgradescript stellt dabei eine vollständige Objektklasse
dar, die vom Elternobjekt "<code class="literal">SL::DBUpgrade2::Base</code>"
erben und eine Funktion namens "<code class="literal">run</code>" zur Verfügung
stellen muss. Das Script wird ausgeführt, indem eine Instanz dieser
Klasse erzeugt und darauf die erwähnte "<code class="literal">run</code>"
aufgerufen wird.</p><p>Zu beachten ist, dass sich der Paketname der Datei aus dem Wert
für "<code class="literal">@tag</code>" ableitet. Dabei werden alle Zeichen, die
in Paketnamen ungültig wären (gerade Bindestriche), durch Unterstriche
ersetzt. Insgesamt sieht der Paketname wie folgt aus:
"<code class="literal">SL::DBUpgrade2::tag</code>".</p><p>Welche Komfortfunktionen zur Verfügung stehen, erfahren Sie in
der Perl-Dokumentation zum oben genannten Modul; aufzurufen mit
"<span class="command"><strong>perldoc SL/DBUpgrade2/Base.pm</strong></span>".</p><p>Ein Mindestgerüst eines gültigen Perl-Upgradescriptes sieht wie
folgt aus:</p><pre class="programlisting"># @tag: beispiel-upgrade-file42
# @description: Ein schönes Beispielscript
# @depends: release_3_1_0
package SL::DBUpgrade2::beispiel_upgrade_file42;
use strict;
use utf8;
# These are additional texts for custom translations.
# The format is the same as for the normal file all, only
# with another key (more_texts instead of texts).
# The file has the form of 'english text' =&gt; 'foreign text',
use parent qw(SL::DBUpgrade2::Base);
$self-&gt;{more_texts} = {
sub run {
my ($self) = @_;
'Ship via' =&gt; 'Terms of delivery',
'Shipping Point' =&gt; 'Delivery time',
# hier Aktionen ausführen
return 1;
}
</pre><p>
</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>
1;
</pre></div><div class="sect2" title="4.4.4. Hilfsscript dbupgrade2_tool.pl"><div class="titlepage"><div><div><h3 class="title"><a name="db-upgrade-files.dbupgrade-tool"></a>4.4.4. Hilfsscript dbupgrade2_tool.pl</h3></div></div></div><p>Um die Arbeit mit den Abhängigkeiten etwas zu erleichtern,
existiert ein Hilfsscript namens
"<code class="filename">scripts/dbupgrade2_tool.pl</code>". Es muss aus dem
kivitendo-ERP-Basisverzeichnis heraus aufgerufen werden. Dieses Tool
liest alle Datenbankupgradescripte aus dem Verzeichnis
<code class="filename">sql/Pg-upgrade2</code> aus. Es benutzt dafür die
gleichen Methoden wie kivitendo selber, sodass alle Fehlersituationen
von der Kommandozeile überprüft werden können.</p><p>Wird dem Script kein weiterer Parameter übergeben, so wird nur
eine Überprüfung der Felder und Abhängigkeiten vorgenommen. Man kann
sich aber auch Informationen auf verschiedene Art ausgeben
lassen:</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Listenform: "<span class="command"><strong>./scripts/dbupgrade2_tool.pl
--list</strong></span>"</p><p>Gibt eine Liste aller Scripte aus. Die Liste ist in der
Reihenfolge sortiert, in der kivitendo die Scripte ausführen
würde. Es werden neben der Listenposition der Tag, die
Abhängigkeitstiefe und die Priorität ausgegeben.</p></li><li class="listitem"><p>Baumform: "<span class="command"><strong>./scripts/dbupgrade2_tool.pl
--tree</strong></span>"</p><p>Listet alle Tags in Baumform basierend auf den
Abhängigkeiten auf. Die "Wurzelknoten" sind dabei die Scripte, von
denen keine anderen abhängen. Die Unterknoten sind Scripte, die
beim übergeordneten Script als Abhängigkeit eingetragen
sind.</p></li><li class="listitem"><p><a name="db-upgrade-files.dbupgrade-tool.reverse-tree"></a>Umgekehrte Baumform: "<span class="command"><strong>./scripts/dbupgrade2_tool.pl
--rtree</strong></span>"</p><p>Listet alle Tags in Baumform basierend auf den
Abhängigkeiten auf. Die "Wurzelknoten" sind dabei die Scripte mit
der geringsten Abhängigkeitstiefe. Die Unterknoten sind Scripte,
die das übergeordnete Script als Abhängigkeit eingetragen
haben.</p></li><li class="listitem"><p>Baumform mit Postscriptausgabe:
"<span class="command"><strong>./scripts/dbupgrade2_tool.pl
--graphviz</strong></span>"</p><p>Benötigt das Tool "<span class="command"><strong>graphviz</strong></span>", um mit
seiner Hilfe die <a class="link" href="ch04s04.html#db-upgrade-files.dbupgrade-tool.reverse-tree">umgekehrte
Baumform</a> in eine Postscriptdatei namens
"<code class="filename">db_dependencies.ps</code>" auszugeben. Dies ist
vermutlich die übersichtlichste Form, weil hierbei jeder Knoten
nur einmal ausgegeben wird. Bei den Textmodusbaumformen hingegen
können Knoten und all ihre Abhängigkeiten mehrfach ausgegeben
werden.</p></li><li class="listitem"><p>Scripte, von denen kein anderes Script abhängt:
"<span class="command"><strong>./scripts/dbupgrade2_tool.pl --nodeps</strong></span>"</p><p>Listet die Tags aller Scripte auf, von denen keine anderen
Scripte abhängen.</p></li></ul></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. Programmatische API-Aufrufe&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. Translations and languages</td></tr></table></div></body></html>

Auch abrufbar als: Unified diff