Revision 42298d2c
Von Moritz Bunkus vor etwa 6 Jahren hinzugefügt
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> </td><th width="60%" align="center">Kapitel 4. Entwicklerdokumentation</th><td width="20%" align="right"> <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/<langcode>/</pre><p>where <langcode> 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 <langcode></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 => 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=& < > \n
|
||
&=&amp;
|
||
<=&lt;
|
||
>=&gt;
|
||
\n=<br></pre><p>Note the importance of the order in this example.
|
||
Substituting < and > befor & would lead to $gt; become
|
||
&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> </td><th width="60%" align="center">Kapitel 4. Entwicklerdokumentation</th><td width="20%" align="right"> <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" -> "b", "b" -> "c"
|
||
und "c" -> "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' => 'foreign text',
|
||
use parent qw(SL::DBUpgrade2::Base);
|
||
|
||
$self->{more_texts} = {
|
||
sub run {
|
||
my ($self) = @_;
|
||
|
||
'Ship via' => 'Terms of delivery',
|
||
'Shipping Point' => '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> </td><td width="20%" align="center"><a accesskey="u" href="ch04.html">Nach oben</a></td><td width="40%" align="right"> <a accesskey="n" href="ch04s05.html">Weiter</a></td></tr><tr><td width="40%" align="left" valign="top">4.3. SQL-Upgradedateien </td><td width="20%" align="center"><a accesskey="h" href="index.html">Zum Anfang</a></td><td width="40%" align="right" valign="top"> 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> </td><td width="20%" align="center"><a accesskey="u" href="ch04.html">Nach oben</a></td><td width="40%" align="right"> <a accesskey="n" href="ch04s05.html">Weiter</a></td></tr><tr><td width="40%" align="left" valign="top">4.3. Programmatische API-Aufrufe </td><td width="20%" align="center"><a accesskey="h" href="index.html">Zum Anfang</a></td><td width="40%" align="right" valign="top"> 4.5. Translations and languages</td></tr></table></div></body></html>
|
Auch abrufbar als: Unified diff
Dokumentation: HTML & PDF gebaut