<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.6.1: 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>
\ No newline at end of file
+
+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>
\ No newline at end of file
projects / kivitendo-erp.git / blobdiff