Deutsch:Coding guidelines

Coding guidelines Dies ist der Beginn der Übersetzung der Coding Guidelines der Version 1.22

Coding Guidelines

=1. Vorgaben/Voreinstellungen=

Deutsch:Coding_guidelines-Vorgaben

=Code Layout/Guidelines=

Deutsch:Coding_guidelines/code_layout

=Styling=

Allgemeine Dinge

Templates sollten in einer übereinstimmenden Weise erstellt werden. Sie sollten auf einer Kopie einer bereits existierenden Seite basieren, Beispielsweise index, viewforum oder viewtopic (diese Kombination hat ein breites Spektrum an Bedingungen und Variablen). Bitte beachten Sie das die Einrückungen und Coding Guidelines genauso auf Templates angewendet werden sollen wo es möglich ist.

Die äußere Tabellenklasse forumline wurde durch tablebg ersetzt.

Wenn der ''

Dies wird dazu führen, dass die Ausgabe der Zeilenfelder die Klasse row1 verwendet wenn die Zeilenzahl gerade ist, und row2 im anderen Fall. Der S_ROW_COUNT Parameter wird automatisch bei Schleifen angelegt. Ein weiteres Beispiel ist folgendes: Dies wird die Zeilenfelder in den ersten beiden Reihen lila, blau in den Zeilen 2 bis 5, grün in den Zeilen 5 bis 10 und rot für alle weiteren ausgeben. Also, Sie können einen "schönen" Farbverlauf erstellen, als Beispiel.

Was können Sie noch machen? Also, Sie können IF benutzen um allgemeine Überprüfungen zu machen wie dem Login Status eines Users: mache

Dies ersetzt die existierende (erschummelte) Methode in 2.0.x eines leeren Arrays und BEGIN/END.

=Übersetzungsrichtlinien (i18n/L10n)=

Standardisierung
Grund:

phpBB ist einer der am meisten übersetzten Open-Source Projekten, mit über 60 Lokalisierungen in der aktuellen, stable Version. Trotz das die aus dem Stegreif entstandene Methode für die Benennung der Sprachpakete funktionierte, hoffen wir diesen Prozess für phpBB3 und nachfolgende Versionen durchdachter zu gestalten, um eine bessere Unterstützung für aktuelle und zukünftige WebBrowser zu bieten.

Encoding:

Mit phpBB3 wird die Ausgabe Encodierung für das Forum auf UTF-8, einem universellem Zeichensatz vom Unicode Consortium, umgestellt, welches eine Zusammenfassung aus US-ASCII und ISO-8859-1 ist. Durch die Verwendung dieses Zeichensatzes wird ermöglicht Scripts auszuführen, die früher verschiedene Zeichensätze benötigten (beispielsweise ISO-8859-1 bis ISO-8859-15 (Latein, Griechisch, kyrillisch, thailändisch, hebräisch, arabisch); GB2312 (vereinfachtes Chinesisch); Big5 (Traditionelles Chinesisch), EUC-JP (Japanisch), EUC-KR (koreanisch), VISCII (vietnamesisch); und weitere). Dadurch entfällt das konvertieren zwischen den verschiedenen Zeichensätzen und verbessert die Zugänglichkeit für mehrsprachige Foren.

Deshalb müssen die Sprachdateien für phpBB jetzt als UTF-8 Dokumente gespeichert werden, mit dem Vorbehalt das die Dateien kein BOM enthalten dürfen, aufgrund der nicht-Unicode-fähigen PHP Versionen. Für Foren mit dem Lateinischem Zeichensatz (gilt für fast alle europäischen Sprachen), ist diese Änderung am einfachsten, da UTF-8 eine Erweiterung des US-ASCII und ISO-8859-1 ist.

Sprach-Tags:

Die IETF hat kürzlich die RFC 4646 die Tags zur Identifizierung herausgegeben, welche in Kombination mit den RFC 4647 den älteren RFC 3006 und noch älteren RFC 1766 ersetzt. RFC 4646 benutzt ISO 639-1/ISO 639-2, ISO 3166-1 alpha-2, ISO 15924 und UN M.49 um einen Sprach Tag zu definieren. Jeder komplette Tag ist eine Zusammenstellung von Sub-Tags, welche Groß- und Kleinschreibung nicht beachten und leer sein können.

Die Reihenfolge der Sub-Tags wenn alle vorhanden sind ist: Sprache-Schriftsystem-Region-Variante-Erweiterung-private Nutzung. Sollte ein Sub-Tag leer sein, so wird der zugehörige Bindestrich ebenfalls weggelassen. Deshalb wäre der Sprach-Tag für Englisch en und nicht en-.

Die meisten Sprach-Tags bestehen aus zwei oder drei Zeichen (von ISO 639-1/ISO 639-2). Manchmal folgt diesem eine zwei- bis dreistellige Zahl als Regions-Sub-Tag (von ISO 3166-1 alpha-2 oder UN M.49). Einige Beispiele sind:

Das wichtigste Ziel der Sprach-Tags ist es die kennzeichnenden Informationen zu transportieren, und diese trotzdem so kurz wie möglich zu halten. Als Beispiel wird en, fr und ja als Gegenstück zu en-GB, fr-FR, ja-JP verwendet, weil wir wissen das englisch, französisch und japanisch ihren Ursprung in Großbritannien, Frankreich und Japan haben.

Das nächste ist der ISO 15924 Sprachsystem Code und wann man es verwendet, und wann nicht. Als Beispiel en-Latin ist syntaktisch korrekt um Englisch mit lateinischen Zeichen zu beschreiben, aber in der Welt wird englisch eigentlich fast immer in Lateinischen Buchstaben geschrieben. Für solche Sprachen wie englisch die überwiegend nur mit einem Schriftsystem geschrieben werden, hat die IANA Language Subtag Registry ein "Suppress-Script" (unterdrücken/weglassen) Feld, das bedeutet das der Schriftsystem-Sub-Tag in solchen Fällen weggelassen werden sollte, außer ein spezifisches Schriftsystem benötigt dies. Manche Sprachen werden in mehr als einem Schriftsystem geschrieben und in solchen Fällen wird der Schriftsystem-Sub-Tag bestärkt, da manche Benutzer die Sprache in einem Schriftsystem lesen können, aber nicht in einem anderen. Einige Beispiele sind:

Der dreistellige UN M.49 Code over sollte anstelle des zwei-stelligen ISO 3166-1 alpha-2 Code verwendet werden wenn ein makro-geographische Unterscheidung benötigt wird und/oder ISO 3166-1 alpha-2 mehrdeutig ist.

Beispiele für englisch mit makro-geographischen Regionen:

Beispiele mit Spanisch und makro-geographische Regionen:

Beispiele bei den ISO 3166-1 alpha-2 mehrdeutig ist und UN M.49 bevorzugt werden sollte:

Makro-Sprachen & örtliche Prägungen:

RFC 4646 vorausschauende Features welche in ISO 639-3 verfügbar gemacht werden sollen (derzeit nur Entwurf), zielen darauf ab eine so vollständige Auflistung der Sprachen verfügbar zu machen, einschließlich lebender, toter, altertümlicher und konstruierter Sprachen, egal ob Haupt-, Neben- oder ungeschriebener Sprache. Ein neues Feature von ISO 639-3 verglichen zu den zwei Vorgängern ist das Konzept der Makrosprachen, arabisch und chinesisch sind hierfür zwei Beispiele. In solchen Fällen ist der jeweilige Code von ar und zh sehr vage bei den Dialekten/Prägungen oder vielleicht zu knapp und damit zu schwer für alle außer den besonders gebildeten Benutzern. Für solche Makro-Sprachen wird empfohlen das der Sprach-Sub-Tag als Suffix für das Makro-Sprach-Tag genutzt wird, Beispiel:

Weitere Erwägungen
Normalisierung der Sprach-Tags für phpBB:

Für phpBB werden die Sprach-Tags nicht in ihrer Originalform benutzt, sondern kleingeschrieben und der Bindestrich - wird wenn es angemessen ist durch den Unterstrich _ ersetzt, hier ein paar Beispiele:

Benutzung der iso.txt:

Die iso.txt Datei ist eine kleine vollständig in UTF-8 kodierte Datei die drei Zeilen enthält:


 * 1. Englischer Name der Sprache
 * 2. Name in der Sprache in eben dieser Sprache
 * 3. Informationen zum Autoren

Die iso.txt wird automatisch beim einstellen auf phpBB.com generiert. Sie brauchen diese Datei also nicht erstellen wenn Sie diese auf phpBB.com veröffentlichen wollen, aber denken Sie daran das phpBB diese Datei benötigt um die Sprache zu erkennen.

Weil die Sprach-Tags selber maschinell gelesen werden, können diese auf Menschen verwirrend wirken und weil die beschreibenden Strings in der iso.txt benötigt werden. Trotz das en-US noch sehr einfach in "Englisch wie es in der USA benutzt wird" aufgelöst werden kann, ist de-CH schon schwieriger, weniger Menschen wissen das das de von "Deutsch" kommt, German für "German" und CH die offizielle Abkürzung für die Schweiz oder auch die "Confoederatio Helvetica" ist.

Für jede englische Beschreibung kommt der Sprachname zuerst und dann zusätzliche Informationen zur Beschreibung der Sub-Tags des Sprach Codes hintereinander aufgelistet, mit Kommas getrennt in Klammern, Beispiel:

Für die übersetzte Sprachbeschreibung, übersetzen Sie einfach die englische Version, und benutzen Sie was für die Zeichensetzung in der Sprache benutzt wird, vorausgesetzt die Sprache besitzt überhaupt eine Zeichensetzung.

Überlegen zu bidirektionalem Unicode:

Da phpBB jetzt UTF-8 verwendet, müssen alle Übersetzer nun in Kauf nehmen das bestimmte Strings in der umgekehrten Direktionalität angezeigt wird, oder die Ausgabe ungewiss ist.

Die verschiedenen Unicode Kontrollzeichen für bidirektionalen Text und ihre HTML Äquivalente wenn entsprechend sind die folgenden:

In der iso.txt kann Textrichtung explizit mit den Unicode Zeichen werden, die 3 Methoden bieten links-nach-rechts/rechts-nach-links Kennzeichnungen/Einschübe/überschreibungen, ohne sie wird die Anordnung der Zeichen falsch, beispielsweise:

Bei der Wahl der drei Methoden wird es meist LRM oder RLM sein, um ein "starkes" Zeichen welches die die eindeutigen Punktierungszeichen vollständig umspannt und daher die korrekte Direktionalität ausreichend vererbt.

In einigen Fällen kann das Script links-nach-rechts und rechts-nach-links Direktionalitäten mischen, da kann LRE & RLE mit PDF besser passen. Zum Schluss, in sehr seltenen Fällen wo die Direktionalität erzwungen werden muss, benutzen Sie LRO & RLO mit PDF.

Für weitere Informationen bei den Techniken der Bidirektionalität, schauen Sie bitte in das W3C Tutorial zu den Techniken bei XHTML Seiten mit bidirektionalem Text (englisch).

Arbeiten mit Platzhaltern:

Da phpBB in mehrere Sprachen mit unterschiedlichen Textrichtungen als deutsch arbeitet, ist es möglich das bestimmte Werte in einer anderen Reihenfolge kommen. Nehmen Sie das simple "Seite X von Y" als Beispiel, in deutsch kann dies einfach folgendermaßen geschrieben werden: ... 'PAGE_OF'	=>	'Seite %s von %s', /* Einfach die Werte schnappen und einsetzen und hoffen das sie in der richtigen Reihenfolge kommen */ ...

… ein besserer Weg um explizit die Reihenfolge bei dem Ersetzen festzulegen ist: ... 'PAGE_OF'	=>	'Seite %1$s von %2$s', /* Explizite Reihenfolge der Ersetzungen, selbst wenn sie in der gleichen Reihenfolge wie in deutsch sind */ ...

Warum damit herumschlagen? Weil manche Sprachen das zurück in das Deutsche übersetzt sowas geschrieben haben könnten wie: ... 'PAGE_OF'	=>	'Gesamt %2$s Seiten, gerade auf Seite %1$s', /* Explizite Reihenfolge der Ersetzungen, zurückübersetzt verglichen mit dem deutschen zeigt das die Gesamtzahl der Seiten zuerst kommt */ ...

Schreibstil
Verschiedene Tipps und Kniffe:

Da die Sprachdateien PHP-Dateien sind, indem die verschiedenen Strings für phpBB als Array gespeichert werden, welche wiederum für das Anzeigen auf der HTML Seite genutzt werden, sind Syntax-Regeln nötig. Potentielle Problem Zeichen sind: ' (gerades Apostroph), &quot; (Anführungszeichen), &lt; (kleiner-als Zeichen), &gt; (größer-als Zeichen) und &amp; (kaufmännisches Und).

// Schlecht - Das nicht maskiert Apostroph wird einen PHP parse Fehler hervorrufen ... 'CONV_ERROR_NO_AVATAR_PATH' =>	'Note to developer: you must specify $convertor['avatar_path'] to use %s.', ...

// Gut - Apostrophe sollten mit dem Backslash maskiert werden, beispielsweise mit: \ ... 'CONV_ERROR_NO_AVATAR_PATH' =>	'Note to developer: you must specify $convertor[\'avatar_path\'] to use %s.', ...

Wie auch immer, da phpBB3 jetzt UTF-8 als Kodierung nutzt, können wir das zu unserem Vorteil nutzen und müssen nicht mehr daran denken das Apostroph zu maskieren:

// Schlecht - Das nicht maskiert Apostroph wird einen PHP parse Fehler hervorrufen ... 'USE_PERMISSIONS'	=>	'Test out user's permissions', ...

// Okay - nicht-Programmierer würden &quot;user\'s&quot; nicht automatisch benutzen ... 'USE_PERMISSIONS'	=>	'Test out user\'s permissions', ...

// Am besten - Benutzten Sie das rechtsliegende Apostroph ... 'USE_PERMISSIONS'	=>	'Test out user’s permissions', ...

Das &quot; (Anführungszeichen), < (kleiner-als Zeichen) und > (größer als Zeichen) Zeichen können alle als Bildzeichen oder als HTML Entity angezeigt werden, als Beispiel:

// Schlecht - Kein gültiges HTML, da Segmente die nicht Teil eines Tags sind nicht als Entity geschrieben sind ... 'FOO_BAR'	=>	'PHP version < 4.3.3.

Visit "Downloads" at www.php.net.', ...

// Okay - Kein ungültiges HTML mehr, aber $quot;$amp;quot;$quot; ist sehr unschön ... 'FOO_BAR'	=>	'PHP version &lt; 4.3.3.

Visit &quot;Downloads&quot; at www.php.net.', ...

// Am besten - kein ungültiges HTML und die Benutzung typographisch-korrekter Anführungszeichen ... 'FOO_BAR'	=>	'PHP version &lt; 4.3.3.

Visit “Downloads” at www.php.net.', ...

Zum Schluss: das &amp; (kaufmännische Und) muss immer als Entity geschrieben werden, unabhängig davon wo es benutzt wird:

// Schlecht - kein gültiges HTML, keines der &amp;'s ist als Entity geschrieben ... 'FOO_BAR'	=>	'Foo & Bar.', ...

// Gut - Gültiges HTML, das &amp; ist in allen Fällen als Entity geschrieben ... 'FOO_BAR'	=>	'Foo &amp; Bar.', ...

Um zu erfahren wie diese Zeichen eingegeben werden lesen sie bitte http://en.wikipedia.org/wiki/Unicode#Input_methods da dies sehr stark vom Betriebssystem, der aktuellen Tastatursprache und den nativen Fähigkeiten des Editors zum bearbeiten der phpBB Sprachdateien abhängt.

Rechtschreibung, Punktierung, Grammatik und ähnliches:

Die Standardsprache mit der phpBB ausgeliefert wird ist britisches Englisch, welches die Rechtschreibung der Cambridge University Press verwendet und dem Sprachcode en zugeordnet ist. Der Schreibstil tendieren zu dem formalen und Übersetzungen sollten versuchen dies nachzuahmen. Zumindest die Varianten mit den kompaktesten Sprachcodes. Weniger formale Übersetzungen oder die mit Umgangssprache müssen als solche gekennzeichnet werden, entweder mit der Erweiterung oder dem private Nutzung Sprachcode.

=7. Guidelines Changelog=

Deutsch:Coding_guidelines/Changelog