<html><head>
- <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
- <title>4.5. Stil-Richtlinien</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="Lx-Office: Installation, Konfiguration, Entwicklung"><link rel="up" href="ch04.html" title="Kapitel 4. Entwicklerdokumentation"><link rel="prev" href="ch04s04.html" title="4.4. Translations and languages"><link rel="next" href="ch04s06.html" title="4.6. Dokumentation erstellen"></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.5. Stil-Richtlinien</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ch04s04.html">Zurück</a> </td><th width="60%" align="center">Kapitel 4. Entwicklerdokumentation</th><td width="20%" align="right"> <a accesskey="n" href="ch04s06.html">Weiter</a></td></tr></table><hr></div><div class="sect1" title="4.5. Stil-Richtlinien"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="devel.style-guide"></a>4.5. Stil-Richtlinien</h2></div></div></div><p>
- 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").
- </p><p>
- Diese Regeln sind keine Schikane sondern erleichtern allen das Leben!
- </p><p>
- Jeder, der einen Patch schickt, sollte seinen Code vorher überprüfen. Einige der Regeln lassen sich automatisch überprüfen, andere
- nicht.
- </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
- Es werden keine echten Tabs sondern Leerzeichen verwendet.
- </p></li><li class="listitem"><p>
- Die Einrückung beträgt zwei Leerzeichen. Beispiel:
- </p><pre class="programlisting">foreach my $row (@data) {
- if ($flag) {
- # do something with $row
- }
+ <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+ <title>4.5. 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.6.1: Installation, Konfiguration, Entwicklung"><link rel="up" href="ch04.html" title="Kapitel 4. Entwicklerdokumentation"><link rel="prev" href="ch04s04.html" title="4.4. SQL-Upgradedateien"><link rel="next" href="ch04s06.html" title="4.6. 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.5. Translations and languages</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ch04s04.html">Zurück</a> </td><th width="60%" align="center">Kapitel 4. Entwicklerdokumentation</th><td width="20%" align="right"> <a accesskey="n" href="ch04s06.html">Weiter</a></td></tr></table><hr></div><div class="sect1" title="4.5. Translations and languages"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="translations-languages"></a>4.5. Translations and languages</h2></div></div></div><div class="sect2" title="4.5.1. Introduction"><div class="titlepage"><div><div><h3 class="title"><a name="translations-languages.introduction"></a>4.5.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.5.2. Character set"><div class="titlepage"><div><div><h3 class="title"><a name="translations-languages.character-set"></a>4.5.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.5.3. File structure"><div class="titlepage"><div><div><h3 class="title"><a name="translations-languages.file-structure"></a>4.5.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 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.</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
- if ($use_modules) {
- $row->{modules} = MODULE->retrieve(
- id => $row->{id},
- date => $use_now ? localtime() : $row->{time},
- );
- }
+use utf8;
- $report->add($row);
-}</pre></li><li class="listitem"><p>Öffnende geschweifte Klammern befinden sich auf der gleichen Zeile wie der letzte Befehl. Beispiele:</p><pre class="programlisting">sub debug {
- ...
-}</pre><p>oder</p><pre class="programlisting">if ($form->{item_rows} > 0) {
- ...
-}</pre></li><li class="listitem"><p>
- 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.
- </p></li><li class="listitem"><p>
- Die Wörter "<code class="function">else</code>", "<code class="function">elsif</code>", "<code class="function">while</code>" befinden sich auf der gleichen
- Zeile wie schließende geschweifte Klammern. Beispiele:
- </p><pre class="programlisting">if ($form->{sum} > 1000) {
- ...
-} elsif ($form->{sum} > 0) {
- ...
-} else {
- ...
-}
-
-do {
- ...
-} until ($a > 0);</pre></li><li class="listitem"><p>
- Parameter von Funktionsaufrufen müssen mit runden Klammern versehen werden. Davon nicht betroffen sind interne Perl-Funktionen,
- und grep-ähnliche Operatoren. Beispiel:
- </p><pre class="programlisting">$main::lxdebug->message("Could not find file.");
-%options = map { $_ => 1 } grep { !/^#/ } @config_file;</pre></li><li class="listitem"><p>
- Verschiedene Klammern, Ihre Ausdrücke und Leerzeichen:
- </p><p>
- Generell gilt: Hashkeys und Arrayindices sollten nicht durch Leerzeichen abgesetzt werden. Logische Klammerungen ebensowenig,
- Blöcke schon. Beispiel:
- </p><pre class="programlisting">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;</pre></li><li class="listitem"><p>
- Mehrzeilige Befehle
- </p><div class="orderedlist"><ol class="orderedlist" type="a"><li class="listitem"><p>
- 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:
- </p><pre class="programlisting">$sth = $dbh->prepare("SELECT * FROM some_table WHERE col = ?",
- $form->{some_col_value});</pre></li><li class="listitem"><p>
- Ein Spezialfall ist der ternäre Oprator "?:", der am besten in einer übersichtlichen Tabellenstruktur organisiert
- wird. Beispiel:
- </p><pre class="programlisting">my $rowcount = $form->{"row_$i"} ? $i
- : $form->{oldcount} ? $form->{oldcount} + 1
- : $form->{rowcount} - $form->{rowbase};</pre></li></ol></div></li><li class="listitem"><p>
- Kommentare
- </p><div class="orderedlist"><ol class="orderedlist" type="a"><li class="listitem"><p>Kommentare, die alleine in einer Zeile stehen, sollten soweit wie der Code eingerückt sein.</p></li><li class="listitem"><p>Seitliche hängende Kommentare sollten einheitlich formatiert werden.</p></li><li class="listitem"><p>
- 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:
- </p><pre class="programlisting">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</pre></li></ol></div></li><li class="listitem"><p>
- Hashkeys sollten nur in Anführungszeichen stehen, wenn die Interpolation gewünscht ist. Beispiel:
- </p><pre class="programlisting">$form->{sum} = 0;
-$form->{"row_$i"} = $form->{"row_$i"} - 5;
-$some_hash{42} = 54;</pre></li><li class="listitem"><p>
- Die maximale Zeilenlänge ist nicht bescrä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.
- </p><p>
- Als Beispiel sei die Funktion <code class="function">print_options</code> aus <code class="filename">bin/mozilla/io.pl</code> angeführt.
- </p></li><li class="listitem"><p>
- Trailing Whitespace, d.h. Leerzeichen am Ende von Zeilen sind unerwünscht. Sie führen zu unnötigen Whitespaceänderungen, die
- diffs verfälschen.
- </p><p>
- Emacs und vim haben beide recht einfache Methoden zur Entfernung von trailing whitespace. Emacs kennt das Kommande
- <span class="command"><strong>nuke-trailing-whitespace</strong></span>, vim macht das gleiche manuell über <code class="literal">:%s/\s\+$//e</code> Mit <code class="literal">:au
- BufWritePre * :%s/\s\+$//e</code> wird das an Speichern gebunden.
- </p></li><li class="listitem"><p>
- Es wird kein <span class="command"><strong>perltidy</strong></span> verwendet.
- </p><p>
- In der Vergangenheit wurde versucht, <span class="command"><strong>perltidy</strong></span> zu verwenden, um einen einheitlichen Stil zu erlangen. Es hat
- sich aber gezeigt, dass <span class="command"><strong>perltidy</strong></span>s sehr eigenwilliges Verhalten, was Zeilenumbrüche angeht, oftmals gut
- formatierten Code zerstört. Für den Interessierten sind hier die <span class="command"><strong>perltidy</strong></span>-Optionen, die grob den
- beschriebenen Richtlinien entsprechen:
- </p><pre class="programlisting">-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</pre></li><li class="listitem"><p>
-
- <code class="varname">STDERR</code> ist tabu. Unkonditionale Debugmeldungen auch.
- </p><p>
- Lx-Office bietet mit dem Modul <code class="classname">LXDebug</code> einen brauchbaren Trace-/Debug-Mechanismus. Es gibt also keinen
- Grund, nach <code class="varname">STDERR</code> zu schreiben.
- </p><p>
- Die <code class="classname">LXDebug</code>-Methode "<code class="function">message</code>" 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.
- </p></li><li class="listitem"><p>
- Alle neuen Module müssen use strict verwenden.
- </p><p>
-
- <code class="varname">$form</code>, <code class="varname">$auth</code>, <code class="varname">$locale</code>, <code class="varname">$lxdebug</code> und
- <code class="varname">%myconfig</code> werden derzeit aus dem main package importiert (siehe <a class="xref" href="ch04.html#devel.globals" title="4.1. Globale Variablen">Globale Variablen</a>. Alle anderen
- Konstrukte sollten lexikalisch lokal gehalten werden.
- </p></li></ol></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch04s04.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="ch04s06.html">Weiter</a></td></tr><tr><td width="40%" align="left" valign="top">4.4. Translations and languages </td><td width="20%" align="center"><a accesskey="h" href="index.html">Zum Anfang</a></td><td width="40%" align="right" valign="top"> 4.6. Dokumentation erstellen</td></tr></table></div></body></html>
\ No newline at end of file
+ </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="ch04s04.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="ch04s06.html">Weiter</a></td></tr><tr><td width="40%" align="left" valign="top">4.4. 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.6. Die kivitendo-Test-Suite</td></tr></table></div></body></html>
\ No newline at end of file
projects / kivitendo-erp.git / blobdiff