- Die folgenden Regeln haben das Ziel, den Code möglichst gut les- und wartbar zu machen. Dazu gehört zum Einen, dass der Code - einheitlich eingerückt ist, aber auch, dass Mehrdeutigkeit so weit es geht vermieden wird (Stichworte "Klammern" oder "Hash-Keys"). -
- Diese Regeln sind keine Schikane sondern erleichtern allen das Leben! -
- Jeder, der einen Patch schickt, sollte seinen Code vorher überprüfen. Einige der Regeln lassen sich automatisch überprüfen, andere - nicht. -
- Es werden keine echten Tabs sondern Leerzeichen verwendet. -
- Die Einrückung beträgt zwei Leerzeichen. Beispiel: -
foreach my $row (@data) { - if ($flag) { - # do something with $row - } + +4.5. Translations and languages ![[Anmerkung]](system/docbook-xsl/images/note.png)
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.
\ No newline at end of file +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
LANGUAGEfile 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 anum2textsub. If + aninitsub 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_charsfile 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 +&=& +<=< +>=> +\n=<br>
Note the importance of the order in this example. + Substituting < and > befor & would lead to $gt; become + &gt;
For a list of valid formats, see the German +
special_charsentry. 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 dependent. 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.
- 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 - if ($use_modules) { - $row->{modules} = MODULE->retrieve( - id => $row->{id}, - date => $use_now ? localtime() : $row->{time}, - ); - } +use utf8; - $report->add($row); -}Öffnende geschweifte Klammern befinden sich auf der gleichen Zeile wie der letzte Befehl. Beispiele:
sub debug { - ... -}oder
if ($form->{item_rows} > 0) { - ... -}- Schließende geschweifte Klammern sind so weit eingerückt wie der Befehl / die öffnende schließende Klammer, die den Block gestartet - hat, und nicht auf der Ebene des Inhalts. Die gleichen Beispiele wie bei 3. gelten. -
- Die Wörter "
else", "elsif", "while" befinden sich auf der gleichen - Zeile wie schließende geschweifte Klammern. Beispiele: -if ($form->{sum} > 1000) { - ... -} elsif ($form->{sum} > 0) { - ... -} else { - ... -} - -do { - ... -} until ($a > 0);- Parameter von Funktionsaufrufen müssen mit runden Klammern versehen werden. Davon nicht betroffen sind interne Perl-Funktionen, - und grep-ähnliche Operatoren. Beispiel: -
$main::lxdebug->message("Could not find file."); -%options = map { $_ => 1 } grep { !/^#/ } @config_file;- Verschiedene Klammern, Ihre Ausdrücke und Leerzeichen: -
- Generell gilt: Hashkeys und Arrayindices sollten nicht durch Leerzeichen abgesetzt werden. Logische Klammerungen ebensowenig, - Blöcke schon. Beispiel: -
if (($form->{debug} == 1) && ($form->{sum} - 100 < 0)) { - ... -} +# 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', -$array[$i + 1] = 4; -$form->{sum} += $form->{"row_$i"}; -$form->{ $form->{index} } += 1; +$self->{more_texts} = { -map { $form->{sum} += $form->{"row_$_"} } 1..$rowcount;- Mehrzeilige Befehle -
- Werden die Parameter eines Funktionsaufrufes auf mehrere Zeilen aufgeteilt, so sollten diese bis zu der Spalte eingerückt - werden, in der die ersten Funktionsparameter in der ersten Zeile stehen. Beispiel: -
$sth = $dbh->prepare("SELECT * FROM some_table WHERE col = ?", - $form->{some_col_value});- Ein Spezialfall ist der ternäre Oprator "?:", der am besten in einer übersichtlichen Tabellenstruktur organisiert - wird. Beispiel: -
my $rowcount = $form->{"row_$i"} ? $i - : $form->{oldcount} ? $form->{oldcount} + 1 - : $form->{rowcount} - $form->{rowbase};
- Kommentare -
Kommentare, die alleine in einer Zeile stehen, sollten soweit wie der Code eingerückt sein.
Seitliche hängende Kommentare sollten einheitlich formatiert werden.
- Sämtliche Kommentare und Sonstiges im Quellcode ist bitte auf Englisch zu verfassen. So wie ich keine Lust habe, französischen - Quelltext zu lesen, sollte auch der Lx-Office Quelltext für nicht-Deutschsprachige lesbar sein. Beispiel: -
my $found = 0; -while (1) { - last if $found; - - # complicated check - $found = 1 if // + 'Ship via' => 'Terms of delivery', + 'Shipping Point' => 'Delivery time', } - -$i = 0 # initialize $i -$n = $i; # save $i -$i *= $const; # do something crazy -$i = $n; # recover $i
- Hashkeys sollten nur in Anführungszeichen stehen, wenn die Interpolation gewünscht ist. Beispiel: -
$form->{sum} = 0; -$form->{"row_$i"} = $form->{"row_$i"} - 5; -$some_hash{42} = 54;- Die maximale Zeilenlänge ist nicht beschränkt. Zeilenlängen unterhalb von 79 Zeichen helfen unter bestimmten Bedingungen, aber - wenn die Lesbarkeit unter kurzen Zeilen leidet (wie zum Biespiel in grossen Tabellen), dann ist Lesbarkeit vorzuziehen. -
- Als Beispiel sei die Funktion
print_optionsausbin/mozilla/io.plangeführt. -- Trailing Whitespace, d.h. Leerzeichen am Ende von Zeilen sind unerwünscht. Sie führen zu unnötigen Whitespaceänderungen, die - diffs verfälschen. -
- Emacs und vim haben beide recht einfache Methoden zur Entfernung von trailing whitespace. Emacs kennt das Kommande - nuke-trailing-whitespace, vim macht das gleiche manuell über
:%s/\s\+$//eMit:au - BufWritePre * :%s/\s\+$//ewird das an Speichern gebunden. -- Es wird kein perltidy verwendet. -
- In der Vergangenheit wurde versucht, perltidy zu verwenden, um einen einheitlichen Stil zu erlangen. Es hat - sich aber gezeigt, dass perltidys sehr eigenwilliges Verhalten, was Zeilenumbrüche angeht, oftmals gut - formatierten Code zerstört. Für den Interessierten sind hier die perltidy-Optionen, die grob den - beschriebenen Richtlinien entsprechen: -
-syn -i=2 -nt -pt=2 -sbt=2 -ci=2 -ibc -hsc -noll -nsts -nsfs -asc -dsm --aws -bbc -bbs -bbb -mbl=1 -nsob -ce -nbl -nsbl -cti=0 -bbt=0 -bar -l=79 --lp -vt=1 -vtc=1
- -
STDERRist tabu. Unkonditionale Debugmeldungen auch. -- Lx-Office bietet mit dem Modul
LXDebugeinen brauchbaren Trace-/Debug-Mechanismus. Es gibt also keinen - Grund, nachSTDERRzu schreiben. -- Die
LXDebug-Methode "message" nimmt als ersten Paramter außerdem eine Flagmaske, für - die die Meldung angezeigt wird, wobei "0" immer angezeigt wird. Solche Meldungen sollten nicht eingecheckt werden und werden in - den meisten Fällen auch vom Repository zurückgewiesen. -- Alle neuen Module müssen use strict verwenden. -
- -
$form,$auth,$locale,$lxdebugund -%myconfigwerden derzeit aus dem main package importiert (siehe Globale Variablen. Alle anderen - Konstrukte sollten lexikalisch lokal gehalten werden. -
+