1. Allgemeine Erklärungen zur Dokumentation

Wenn Sie selbst ein Dokument übersetzen möchten, müssen Sie nur einige einfache Schritte befolgen. Am besten lesen Sie erst einmal alle Informationen auf dieser Seite durch (sowie auf den im Abschnitt "Ressourcen" verlinkten Seiten) und befolgen dann die Anleitung Schritt für Schritt.

Es gibt einige Regeln und Erklärungen dazu, wie die Gentoo-Dokumentation inhaltlich übersetzt werden soll und wie der Aufbau eines Dokuments ist. Diese Dinge sind für alle Sprachen, in die die Gentoo-Dokumentation übersetzt wird, gleich, und werden sehr detailliert auf den englischen Seiten des Gentoo Documentation Projects erklärt. Die Seite, die Sie gerade betrachten, erklärt die Punkte, die für die Übersetzung ins Deutsche speziell sind.

Aber zuerst einige Erläuterungen, wie die deutsche Gentoo-Dokumentation aufgebaut ist und wie der eigentliche Prozess des Übersetzens aussieht:

2. Wie läuft eine Übersetzung ab?

• Suchen Sie sich ein Dokument aus, das Sie übersetzen möchten: Am einfachsten geht dies, indem Sie einen Blick ins "trads" werfen. Das trads ist eine Übersicht aller existierenden englischen Dokumente sowie der zugehörigen deutschen Übersetzungen, sowie des Übersetzungsstatuses jeden einzelnen Dokuments. Gemäß der Spalte "Priorität" können Sie dort ein Dokument auswählen, das Sie übersetzen möchten, aber selbstverständlich haben Sie die freie Wahl. Für bereits übersetzte (aber nicht mehr aktuell gehaltene) Dokumente, finden Sie in der Spalte "Diff. der Versionen EN" einen Link, der Ihnen direkt zeigt, welche Änderungen seit der letzten Übersetzung am englischen Original vorgenommen wurden (und dementsprechend, was am deutschen Dokument abgeändert werden muss).
• Bevor Sie nun mit dem Übersetzen beginnen, sollten Sie eine kurze Mail an die gentoo-doc-de@gentoo.org Mailingliste senden und so sicherstellen, dass noch niemand mit der Übersetzung des von Ihnen gewählten Dokumentes begonnen hat, und dass es nach Ihnen auch niemand anderes tut. Das vermeidet überflüssige doppelte Arbeit. In der Regel wird aber zeitnah von einem der Entwickler ein Eintrag im trads vorgenommen, so dass dieser Schritt vernachlässigt werden kann. Weiterhin ist die Zahl der Übersetzer momentan eh sehr gering.
• Übersetzen Sie das Dokument. :)
  Hilfestellungen (z.B. Übersetzungen bestimmter technischer Wörter sowie Gentoo-eigener Begriffe) finden Sie in den Ressourcen unten auf dieser Seite.
• Wenn Sie das Dokument fertig übersetzt haben, können Sie es entweder an die Liste schicken oder direkt an einen der Entwickler, die für die deutsche Dokumentation zuständig sind, zurzeit ist das nur Tobias Heinlein. Das Dokument wird dann von diesen Entwicklern Korrektur gelesen. Ist dies geschehen, wird das Dokument in das CVS von www.gentoo.org eingebracht. Eventuelle Änderungen und Korrekturen finden sich dort auch wieder. Der gentoo.de-Server synchronisiert sich automatisch mit den gentoo.org-Servern, so dass das Dokument dann auf beiden Internetseiten zu finden ist.

3. Weitere Informationen

gentoo.org-CVS

Wenn Ihnen trads oder das Webinterface ViewVC (auf das das trads teilweise verlinkt) aus irgendeinem Grund nicht genügen, können Sie Ihre Arbeitskopie der englischen Dokumentation auch aus dem gentoo.org CVS beziehen:

$ cvs -d :pserver:anonymous@anoncvs.gentoo.org/var/cvsroot co gentoo/xml

Mit welchem Editor kann ich die Dokumente bearbeiten?

Im Prinzip reicht ein einfacher Texteditor, der in UTF-8 abgespeicherte Dokumente bearbeiten kann, vollkommen aus. Bluefish bietet ein sehr schönes Syntax-Highlighting an. Aber auch die üblichen Verdächtigen, wie z.B. vim, sollten Sie durchaus in die nähere Auswahl mit einbeziehen.

Wenn Sie vim benutzen haben wir noch ein paar zusätzliche Tipps für Sie, mit denen Sie sich das Editieren der Dokumente etwas vereinfachen können. Zunächst sollten Sie sich das von Lars Weiler an die Erfordernisse des Schreibens von Gentoo Dokumentation angepasste vim xml-Pluginherunterladen und in das ~/.vim/ftplugins Verzeichnis legen. Damit vim dieses Plugin lädt, müssen Sie noch eine Einstellung in der .vimrc erstellen. Bei der Gelegenheit bringen Sie vim auch noch UTF-8 bei und machen aus einem tab zwei Leerzeichen.

Zunächst weisen Sie vim an, Filetype Plugins zu laden:
filetype plugin on
Nun setzen Sie das Encoding auf UTF-8:
set encoding=utf-8
Und nun machen Sie aus einem Tab zwei Leerzeichen, dies ist
für das Editieren von Tabellen gemäß Coding Style sinnvoll.
set expandtab
set tabstop=2
set shiftwidth=2

Was ist dies für eine komische HTML-ähnliche Syntax in den Dokumenten? Gibt es irgendwo eine Liste für die ganzen Optionen?

Klar. Der XML-Leitfaden gibt eine sehr schöne Einführung in das von uns benutzte GuideXML. Wenn Sie Dokumentation übersetzen wollen, müssen Sie nicht unbedingt sofort den Sinn eines jeden Tag verstehen, ich vermute aber mal, dass Sie es trotzdem wissen wollen. ;)

Gibt es eine Richtlinie, wie die Dokumente aussehen müssen?

Ja, wie bereits am Anfang angedeutet, gibt es eine Vielzahl von Richtlinien. Sowohl an der englischen Dokumentation, als auch an den deutschen Übersetzungen arbeitet eine Vielzahl von Leuten mit. Damit sich alle innerhalb möglichst kurzer Zeit in einem Dokument zurecht finden können, ist ein "Coding Style" festgelegt worden. Im "Coding Style" wird festgelegt, wie die XML-Tags im Dokument zu platzieren sind, ausserdem gibt es einige Regeln, die dazu dienen, die Dokumentation so lesbar wie möglich zu halten. Um einen Eindruck zu erhalten, wie ein Dokument mit angewandtem Coding Style aussieht, schauen Sie sich irgendeine Datei an, zum Beispiel kernel-upgrade.xml.

Solange diese übereinstimmen lässt sich einfach erschließen auf welche Version des Originals sich die Übersetzung bezieht. Weiterhin sollten Sie beim Einreichen Ihrer Übersetzungen auch immer die CVS-Revisionsnummer des Originaldokuments angeben, damit es passend in der Trads-Übersicht eingetragen werden kann.

Wie erhalte ich die GuideXML DTD (Document Type Definition) Datei?

Sie müssen keine zusätzlichen Pakete installieren. Alle DTD-Dateien (einschließlich der für GuideXML) befinden sich unter /usr/portage/metadata/dtd/. Die Dokumentationsentwicklungs-Tips & Tricks gehen weiter auf deren Benutzung ein.

Fertigstellen der Übersetzung

Bevor Sie Dokumentation zur Korrektur an die Liste schicken, sollten Sie noch kurz prüfen, ob das Dokument syntaktisch korrekt ist.

# xmllint dokumentation.xml

Optional können Sie sich die übersetzte Dokumentation auch anschauen. Dazu benötigen Sie die guide.xsl, main.css sowie optional einige Grafiken. Links zu diesen Dateien finden Sie im Docs-Team Tips&Tricks Guide unter Testing GuideXML. Mit diesen Dateien sind Sie in der Lage lokal eine HTML-Version Ihres Dokuments zu erstellen.

# xsltproc --novalid guide.xsl doku.xml > test.html

Da wir zwar nicht faul aber durchaus etwas bequem sind, erstellen wir uns ein kleines Makefile; ein make dokument geht nunmal schneller.

dokument:
  xsltproc --novalid guide.xsl dokument.xml > test.html

4. Ressourcen

Mailinglisten: Sie sollten sich zumindest auf der gentoo-doc-de@gentoo.org Liste anmelden, da hierüber - neben IRC - ein Großteil der Kommunikation unter den Übersetzern abläuft. Zum Anmelden senden Sie eine Nachricht an gentoo-doc-de-subscribe@gentoo.org

Statusupdates: Das bereits mehrfach erwähnte trads bietet eine Übersicht über den aktuellen Status der Übersetzungen. Diese Auflistung wird mehrmals stündlich neu generiert.

Englische Dokumente: Hier finden Sie eine Übersicht der bisher auf Englisch verfügbaren Gentoo Dokumentation. Zusätzlich bietet Ihnen das viewcvs auf gentoo.org die Möglichkeit in verschiedenen Ansichtsmodi zwischen den englischen Versionen zu diffen; ein interessantes Feature, wenn Sie bereits übersetzte Dokumentationen aktualisieren möchten.

Weiterführende Dokumentation: Sie sollten je nach Vorkenntnissen einen Blick in das GuideXML Howto werfen.

Übersetzungshilfen: Wir arbeiten außerdem am Aufbau einer Übersicht über die stilistischen Konventionen für die deutsche Gentoo Dokumentation. Sie finden diese hier.