X-Git-Url: http://wagnertech.de/git?a=blobdiff_plain;f=doc%2Fhtml%2Fch04s04.html;h=f53c439c78776ae0d4c97cadf43fd381e778d634;hb=c62a6cabffc11bdb2d3fda2025fef2f3d07c5ba9;hp=15aaa08b3d403c4abaf1be25d68edb2af66d89f5;hpb=8041f98c3befcfffba2149954e84695a23d9b4a6;p=kivitendo-erp.git diff --git a/doc/html/ch04s04.html b/doc/html/ch04s04.html index 15aaa08b3..f53c439c7 100644 --- a/doc/html/ch04s04.html +++ b/doc/html/ch04s04.html @@ -1,100 +1,140 @@ - 4.4. Translations and languages
4.4. Translations and languages
Zurück Kapitel 4. Entwicklerdokumentation Weiter

4.4. Translations and languages

4.4.1. Introduction

[Anmerkung]Anmerkung

Dieser Abschnitt ist in Englisch geschrieben, um - internationalen Übersetzern die Arbeit zu erleichtern.

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.

4.4.2. Character set

All files included in a language pack must use UTF-8 as their encoding.

4.4.3. File structure

The structure of locales in kivitendo is:

kivitendo/locale/<langcode>/

where <langcode> stands for an abbreviation of the - language package. The builtin packages use two letter ISO 639-1 codes, - but the actual name is not relevant for the program and can easily be - extended to IETF language - tags (i.e. "en_GB"). In fact the original language packages - from SQL Ledger are named in this way.

In such a language directory the following files are - recognized:

LANGUAGE

This file is mandatory.

The LANGUAGE 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:

Deutsch (German)
all

This file is mandatory.

The central translation file. It is essentially an inline - Perl script autogenerated by locales.pl. To - generate it, generate the directory and the two files mentioned - above, and execute the following command:

scripts/locales.pl <langcode>

Otherwise you can simply copy one of the other languages. - You will be told how many are missing like this:

$ scripts/locales.pl en
-English - 0.6% - 2015/2028 missing

A file named "missing" will be - generated and can be edited. You can also edit the - "all" file directly. Edit everything you - like to fit the target language and execute - locales.pl again. See how the missing words - get fewer.

Num2text

Legacy code from SQL Ledger. It provides a means for - numbers to be converted into natural language, like - 1523 => one thousand five hundred twenty - three. If you want to provide it, it must be inlinable - Perl code which provides a num2text sub. If - an init sub exists it will be executed - first.

Only used in the check and receipt printing module.

special_chars

kivitendo comes with a lot of interfaces to different - formats, some of which are rather picky with their accepted - charset. The special_chars 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.

First entry should be the order of substitution for - entries as a whitespace separated list. All entries are - interpolated, so \n, \x20 - and \\ all work.

After that every entry is a special char that should be - translated when writing text into such a file.

Example:

[Template/XML]
-order=& < > \n
-&=&amp;
-<=&lt;
->=&gt;
-\n=<br>

Note the importance of the order in this example. - Substituting < and > befor & would lead to $gt; become - &amp;gt;

For a list of valid formats, see the German - special_chars entry. As of this writing the - following are recognized:

HTML
-URL@HTML
-Template/HTML
-Template/XML
-Template/LaTeX
-Template/OpenDocument
-filenames

The last of which is very machine dependant. Remember that - a lot of characters are forbidden by some filesystems, for - exmaple 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.

missing

This file is not a part of the language package - itself.

This is a file generated by - scripts/locales.pl while processing your - locales. It's only to have the missing entries singled out and - does not belong to a language package.

lost

This file is not a part of the language package - itself.

Another file generated by - scripts/locales.pl. 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.

more/all

This subdir and file is not a part of the language package - itself.

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: - 

-#!/usr/bin/perl
-# -*- coding: utf-8; -*-
-# vim: fenc=utf-8
+   4.4. SQL-Upgradedateien
4.4. SQL-Upgradedateien
Zurück Kapitel 4. Entwicklerdokumentation Weiter
4.4. SQL-Upgradedateien
4.4.1. Einführung
Datenbankupgrades werden über einzelne Upgrade-Scripte
+        gesteuert, die sich im Verzeichnis
+        sql/Pg-upgrade2 befinden. In diesem Verzeichnis
+        muss pro Datenbankupgrade eine Datei existieren, die neben den
+        eigentlich auszuführenden SQL- oder Perl-Befehlen einige
+        Kontrollinformationen enthält.
Kontrollinformationen definieren Abhängigkeiten und Prioritäten,
+        sodass Datenbankscripte zwar in einer sicheren Reihenfolge ausgeführt
+        werden (z.B. darf ein ALTER TABLE erst ausgeführt
+        werden, wenn die Tabelle mit CREATE TABLE angelegt
+        wurde), diese Reihenfolge aber so flexibel ist, dass man keine
+        Versionsnummern braucht.
kivitendo merkt sich dabei, welches der Upgradescripte in
+        sql/Pg-upgrade2 bereits durchgeführt wurde und
+        führt diese nicht erneut aus. Dazu dient die Tabelle
+        "schema_info", die bei der Anmeldung automatisch
+        angelegt wird.
4.4.2. Format der Kontrollinformationen
Die Kontrollinformationen sollten sich am Anfang der jeweiligen
+        Upgradedatei befinden. Jede Zeile, die Kontrollinformationen enthält,
+        hat dabei das folgende Format:
Für SQL-Upgradedateien:
-- @key: value
Für Perl-Upgradedateien:
# @key: value
Leerzeichen vor "value" werden
+        entfernt.
Die folgenden Schlüsselworte werden verarbeitet:

+                     tag
+                  
Wird zwingend benötigt. Dies ist der "Name" des Upgrades.
+              Dieser "tag" kann von anderen Kontrolldateien in ihren
+              Abhängigkeiten verwendet werden (Schlüsselwort
+              "depends"). Der "tag" ist auch der Name, der
+              in der Datenbank eingetragen wird.
Normalerweise sollte die Kontrolldatei genau so heißen wie
+              der "tag", nur mit der Endung ".sql" bzw. "pl".
Ein Tag darf nur aus alphanumerischen Zeichen sowie den
+              Zeichen _ - ( ) bestehen. Insbesondere sind Leerzeichen nicht
+              erlaubt und sollten stattdessen mit Unterstrichen ersetzt
+              werden.

+                     charset
+                  
Empfohlen. Gibt den Zeichensatz an, in dem das Script
+              geschrieben wurde, z.B. "UTF-8". Aus
+              Kompatibilitätsgründen mit alten Upgrade-Scripten wird bei
+              Abwesenheit des Tags für SQL-Upgradedateien der Zeichensatz
+              "ISO-8859-15" angenommen. Perl-Upgradescripte
+              hingegen müssen immer in UTF-8 encodiert sein und sollten
+              demnach auch ein "use utf8;"
+              enthalten.

+                     description
+                  
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.

+                     depends
+                  
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.
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.
Es ist nicht erlaubt, sich selbst referenzierende
+              Abhängigkeiten zu definieren (z.B. "a" -> "b", "b" -> "c"
+              und "c" -> "a").

+                     priority
+                  
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.
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".

+                     ignore
+                  
Optional. Falls der Wert auf 1 (true) steht, wird das
+              Skript bei der Anmeldung ignoriert und entsprechend nicht
+              ausgeführt.
4.4.3. Format von in Perl geschriebenen
+        Datenbankupgradescripten
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.
Ein Upgradescript stellt dabei eine vollständige Objektklasse
+        dar, die vom Elternobjekt "SL::DBUpgrade2::Base"
+        erben und eine Funktion namens "run" zur Verfügung
+        stellen muss. Das Script wird ausgeführt, indem eine Instanz dieser
+        Klasse erzeugt und darauf die erwähnte "run"
+        aufgerufen wird.
Zu beachten ist, dass sich der Paketname der Datei aus dem Wert
+        für "@tag" ableitet. Dabei werden alle Zeichen, die
+        in Paketnamen ungültig wären (gerade Bindestriche), durch Unterstriche
+        ersetzt. Insgesamt sieht der Paketname wie folgt aus:
+        "SL::DBUpgrade2::tag".
Welche Komfortfunktionen zur Verfügung stehen, erfahren Sie in
+        der Perl-Dokumentation zum oben genannten Modul; aufzurufen mit
+        "perldoc SL/DBUpgrade2/Base.pm".
Ein Mindestgerüst eines gültigen Perl-Upgradescriptes sieht wie
+        folgt aus:
# @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;
 }
-              

-              
-
Zurück Nach oben Weiter
4.3. SQL-Upgradedateien Zum Anfang 4.5. Die kivitendo-Test-Suite
\ No newline at end of file + +1; +

4.4.4. Hilfsscript dbupgrade2_tool.pl

Um die Arbeit mit den Abhängigkeiten etwas zu erleichtern, + existiert ein Hilfsscript namens + "scripts/dbupgrade2_tool.pl". Es muss aus dem + kivitendo-ERP-Basisverzeichnis heraus aufgerufen werden. Dieses Tool + liest alle Datenbankupgradescripte aus dem Verzeichnis + sql/Pg-upgrade2 aus. Es benutzt dafür die + gleichen Methoden wie kivitendo selber, sodass alle Fehlersituationen + von der Kommandozeile überprüft werden können.

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:

Zurück Nach oben Weiter
4.3. Programmatische API-Aufrufe Zum Anfang 4.5. Translations and languages
\ No newline at end of file