OpenClonk: Englische Dokumentations-Sources

Bisher waren die Sources der Entwicklermodus-Dokumentation nur auf Deutsch verfügbar. Die Doku basierte auf der von Clonk Rage, die ebenfalls für einige Zeit nur in Deutsch verfügbar war und erst später in’s Englische übersetzt wurde. Wie auch immer, bevor etwas übersetzt werden konnte, musste ja erst einmal eine deutsche Version verfügbar sein (siehe Bug #287)  – daher konnte bisher auch keiner der englisch-sprachigen User etwas zur Doku beitragen.  Nach einiger anfänglicher Arbeit von Maikel setzte ich mir letztes Wochenende zum Ziel die Situation zu ändern: Die Hauptdokumentation sollte auf Englisch vorhanden sein, welche dann möglicherweise in Deutsch (oder andere Sprachen) übersetzt werden kann. Dazu wäre das Tool xml2po, das alle XML-Dateien in docs/sdk scannt und danach daraus sogenannte po-Dateien erzeugt, die alle entsprechenden Strings zum Übersetzen enthalten, am Besten geeignet. Die po-Dateien werden dann von Menschen aus Fleisch und Blut übersetzt.

Die folgenden Schritte müssen dafür unternommen werden (Plus/Minus etwas Detailarbeit):

1. Die Englische Übersetzung vervollständigen: Als ich anfing, waren an die 200 unübersetzte deutsche Strings in der Doku, die ich mir vornehmen musste. gtranslator ist ein nettes Tool, das bei der Übersetzung hilft, bis auf eine Tatsache: Es zeigt nicht an, wo der String herkommt (z.B. welche Zeile aus welcher XML-Datei) – das musste ich von Hand in der po-Datei nachsehen, wenn ich das wissen musste.
2. Ein Script schreiben, das die po-Datei der englischen Übersetzung liest, den deutschen Inhalt aller XML-Dateien mit ihrer englischen Version ersetzt, und eine po-Datei mit der Übersetzung von Englisch zu Deutsch anlegt. Dieses Script fing als sehr hübsches und klares Python-Script an, aber dann musste es immer mehr Spezialfälle behandeln. Inzwischen kann ich nicht mehr sagen, dass ich besonders stolz darauf bin… aber naja, schlussendlich erfüllte es seinen Zweck. Eine weiter Sache, die ich währenddessen gelernt habe: Es ist eine gute Idee, Python-Strings und Unicode-Objekte möglichst nicht durcheinander zu benutzen; stattdessen sollte man lieber immer entweder das eine, oder das andere benutzen – andernfalls bekommt man seltsame “UnicodeDecodeError”-Exceptions und was nicht alles überall verstreut… ein Grund, warum ich Programmiersprachen mit starker Typisierung lieber mag.
3. Duplikate in der neu erstellten de.po-Datei loswerden. Es gab doch einige Fälle, wo zwei verschiedene deutsche Strings mit dem gleichen englischen String übersetzt werden. Das sieht man besonders oft in Tabellen, die (Englische) Bezeichner auflisten – die sollten gar nicht übersetzt werden, denn sie beziehen sich auf einen Eintrag in einer Konfigurations-Datei. Ich habe beschlossen, sie mit einem anderen XML-Tag zu markieren (<literal_col> statt <col>), sodass sie in der Übersetzung gar nicht erst auftauchen.

Einige der Strings, die noch zu übersetzen sind, enthalten XML-Fragmente, zum Beispiel um Platzhalter oder Text-Highlighting einzufügen. Nicht wenige dieser XMLs in der englischen Dokumentation sind kaputt. Ich frage mich, warum das Problem nicht gleich erkennbar war, als die Dokumentation am entstehen war.

Nun, wenn du die Dokumentation nach Deutsch, oder eine andere Sprache übersetzen möchtest, brauchst du lediglich die docs/de.po Dateien mit einem Tool deiner Wahl (zum Beispiel ein simpler Texteditor – das Format der Datei ist wunderhübsch selbsterklärend) bearbeiten. Auf Linux kannst du die .po-Dateien recht leicht neu generieren (mittels Scan der XML-Dateien für neue Strings) und eine übersetzte Version mittels make in docs/(für Windows ist das alles etwas komplizierter, aber bei Bedarf kannst du in die Anleitung schauen: README.cygwin.txt) erzeugen. Dabei werden ebenfalls die XML-Dateien zu HTML konvertiert – ideal um in Webbrowsern (Firefox kann zum Beispiel aus irgendeinem Grund nichts mit XMLs anfangen) angezeigt zu werden. Wenn du von Grund auf eine Übersetzung in eine neue Sprache anfangen möchtest (oder du möchtest sie in den make Prozess mit einbinden, weißt aber nicht wie) fühl dich frei einer der Entwickler im Forum oder Chat anzuschreiben. Ein Wort zur Warnung: Alle Docs zu übersetzen ist eine unglaublich große Arbeit, da diese mehr als 4000 Strings enthalten. Wie auch immer, es wäre schon eine feine Sache wenn alles Stück für Stück in kleineren Portionen übersetzt wird. Unübersetzte Strings bleiben vorerst auf Englisch.

Abgesehen von dieser hier gibt es noch mehr Arbeiten, die die Dokumentation betreffen. Newton hat uns darüber bereits einen netten Überblick im Forum gegeben. So, meine englisch-sprachigen Freunde, jetzt habt ihr keine Entschuldigung mehr :D . Außerdem enthält der Code  noch einige Strings oder Kommentare, die auf Deutsch geschrieben sind. Später irgendwann können diese auch übersetzt werden, aber die Kommentare sollten auch ganz gut unübersetzt verständlich sein. Wenn ihr die Dokumentation-XMLs übersetzt, könnt ihr euch sogar ein direkte Vorschau eurer Änderungen im Internet Explorer (nicht im Firefox) anschauen.

Ursprünglicher Post von Clonk-Karl am 22. August 2010.