Bearbeiten Drucken

KDE-Übersetzungsprojekt: Dokumentation


Über diese Seite

Schwerpunkt dieser Seite ist die Übersetzung der Dokumentation. Seit der Umstellung auf das PO-Format stimmen weite Teile mit der Anleitung zur Übersetzung der Benutzeroberfläche überein und wurden von dort übernommen. Da die Übersetzung der Dokumentation jedoch einige Besonderheiten hat, halte ich diese Seite trotz teilweiser Doppelung für sinnvoll. Hilfe zur KDE-Übersetzung im Allgemeinen und zur Übersetzung der Benutzeroberfläche im speziellen gibts jeweils auf extra Seiten. Außerdem seien auch noch die internationalen Seiten von KDE zur GUI und zur Dokumentation (external link) genannt.
Diese Seiten werden laufend ergänzt und sollen irgendwann als Grundlage für die allgemeine Übersetzer-FAQ dienen. Rückmeldungen, Ergänzungen, Änderungswünsche jeglicher Art bitte an die jeweiligen Betreuer der Seiten oder gleich über dieses Wiki selber einpflegen.


Voraussetzungen fürs Übersetzen

Was solltest Du können?

Zu diesem Thema solltest du auch den entsprechenden Abschnitt unter "Voraussetzungen fürs Übersetzen" nachlesen. Was dort gesagt ist, gilt auch für die Übersetzung von Dokumentation und Online-Hilfe.

Ansonsten ist noch Folgendes wichtig:
  • Die Dokumentationen für KDE-Programme sind mit XML (eXtensible Markup Language) geschrieben.
    XML erlaubt es, sogenannte "Markup"-Sprachen mittels DTD (Document Type Definition) zu definieren. Eine DTD beschreibt z. B., welche Elemente ein Dokument enthalten kann und wie diese angeordnet sein müssen. So ist z. B. HTML durch eine solche DTD definiert.

  • Der Vorteil von XML ist, dass sich diese Markup-Sprachen relativ leicht ineinander umwandeln lassen. So kann man aus den XML-Quellen relativ einfach HTML, Postscript u. a. erzeugen. Die KDE-Dokumentationen benutzen momentan eine DTD namens "DocBook", bzw. eine KDE-DTD, die auf der Docbook DTD basiert. DocBook? ist momentan der Standard für technische Dokumentationen.
    Das bedeutet für dich: Falls du schon einmal mit einer strukturbeschreibenden Sprache wie HTML oder LaTex? gearbeitet hast, sollte auch XML kein Problem darstellen. Falls nicht, musst du ein wenig Zeit investieren, um ein gewisses Grundverständis über strukturbeschreibende Sprachen zu erhalten.
    Weitere Informationen und weiterführende Links zu XML und zu DocBook? findest du hier, besonders den Crashkurs sollte jeder wenigstens einmal gelesen haben.

  • Da die Screenshots in der Dokumentation die deutsche Oberfläche zeigen sollen, solltest du Screenshots anfertigen können. Mit KSnapshot oder XV dürfte das eigentlich kein Problem sein.


Welche Software solltest du mitbringen?

Dieser Teil ist durch die Umstellung auf PO-Dateien für die Übersetzung glücklicherweise erheblich einfacher geworden.
  • Für die Übersetzung der Dokumentation und Online-Hilfe gibt es das Programm KBabel von Matthias Kiefer, das für KDE entwickelt wurde und im Paket kdesdk enthalten ist. Dieses Paket kann dort heruntergeladen werden, wo auch alle anderen Teile der KDE-Pakete zu finden sind. Es unterstützt die Kodierung in UTF-8, die seit einiger Zeit unabdingbar für die Übersetzung der Dokumentation und Online-Hilfe ist.

  • Wenn in der Doku Screenshots vorkommen, brauchst du ein Programm, mit dem du Screenshots der deutschen Oberfläche machen kannst. Geeignet sind z. B. KSnapshot (aus dem Paket kdegraphics) oder XV.
    Bitte beachte auch die Screenshot-Richtlinien (external link).

  • Zur syntaktischen Überprüfung der fertigen Dokumentation und Online-Hilfe benötigst du den XML-Parser meinproc von Stephan Kulow. Er ist Teil von kdelibs und daher in der Grundinstallation von KDE bereits vorhanden.

  • Der Parser benötigt die Bibliothek libxml2 (external link). Eine Version von libxml2 ist im Paket kdesupport vorhanden, das zur Grundinstallation von KDE gehört. Damit sollte diese Bibliothek wie auch meinproc bereits auf deinem Rechner installiert sein. Ansonsten kann libxml2 auch über den oben angegebenen Link installiert werden. Du musst aber die neueste Version haben, da die vielen Distributionen beiliegenden Pakete von libxml2 noch nicht alle benötigten Eigenschaften haben. Wer vorkompilierte Pakete installiert, benötigt libxml2 und libxml2-devel.

  • Außerdem benötigst du das Programm po2xml. Es dient zur Erzeugung der XML-Datei einer Dokumentation aus der übersetzten PO-Datei. Es befindet sich wie KBabel im Paket kdesdk.

Details zu allen Programmen finden sich in der internationalen Version dieser Seiten (external link). Im Großen und Ganzen erleichtern sie sehr die Navigation (Auffinden und Abklappern von Fuzzies oder unübersetzten Strings), den Vergleich mit bereits vorhandenen Übersetzungen (somit also die Einheitlichkeit), die Überprüfung auf formale Korrektheit und überhaupt den gesamten Arbeitsablauf. Je mehr damit gearbeitet und Feedback an die Autoren geliefert wird, desto stärker werden naturgemäß diese Programme. Zumindest bei Matthias kann jeder diese Erfahrung leicht machen. ;)


POT-, PO- und DOCBOOK-Dateien

Was bei der Online-Hilfe- und Doku-Übersetzung tatsächlich übersetzt wird, sind Dateien mit der Erweiterung ".pot" und ".po" im Unicode-Format (UTF8). Das Wesentliche dazu kommt jetzt — das Unwesentliche steht in den Infoseiten des gettext-Pakets. ;)

Die englischen Dokumentationen und Online-Hilfeseiten liegen als DOCBOOK-Dateien vor. Es handelt sich um eine für technische Dokumentation übliche DTD (Document Type Definition) im XML-Format. Die übersetzbaren Inhalte dieser Dateien werden durch Programme, die auf dem Server l10n.kde.org liegen, automatisch extrahiert und in POT-Dateien geschrieben. (Ehe die Frage jemanden um den Schlaf bringt: "POT" heißt soviel wie "PO-Template", und "PO" heißt soviel wie "Portable Object" — aha! Beispiele, wie solche POT?s und PO?s und DOCBOOK?s aussehen, finden sich auf extra Seiten.)

Die englische POT-Datei einer Dokumentation bildet die einheitliche Vorlage für alle Übersetzerteams, die daraus PO-Dateien für die einzelnen Sprachen erstellen. Diese landessprachlichen POs wiederum liefern die übersetzten Textteile, aus denen wiederum auf dem Server l10n.kde.org automatisch übersetzte DOCBOOK-Dateien erstellt werden. Wenn schließlich der KDE-Anwender z. B. "German" oder "Icelandic" als Standardsprache für Programme ausgewählt hat und das KDE-Hilfezentrum aufruft, werden diese landessprachlichen DOCBOOK-Dateien geparst und durch das Ein-/Ausgabemodul für Hilfe (help kioslave) von Stephan Kulow ansprechend formatiert dargestellt. Die automatische Erstellung der landessprachlichen DOCBOOK-Dateien setzt allerdings voraus, das die POs formal in Ordnung sind, siehe unten das Stichwort "Kontrolle der Übersetzung".

Die englischen Dokumentationen (DOCBOOK) liegen in Unterordnern des Quellcodes für das jeweilige Programmpaket. Die POT-Dateien und sämtliche übersetzten PO- und DOCBOOK-Dateien befinden sich in einem extra KDE Basisordner namens l10n, bilden also ein separates KDE Paket. Dabei stehen:

  • die POT-Dateien im Ordner l10n/templates/docmessages/<paketname>
  • die deutschen PO-Dateien im Ordner l10n/de/messages/docmessages/<paketname>
  • die englischen Dokumentationen (Docbook) im Ordner l10n/documentation/<paketname> (zur Generierung der deutschen Docbook-Dateien notwendig)
  • und die automatisch daraus generierten deutschen Dokumentationen (Docbook) im Ordner l10n/de/docs/<paketname>

Eine Archivdatei mit allen Dateien von l10n (einschließlich XML-Dokumentation) findet sich unter ftp://ftp.kde.org/pub/kde/unstable/latest/kde-l10n (external link). In diesem Ordner findet sich sämtliches Material von über 30 Übersetzerteams. Natürlich kann man auch per SVN? oder WebSVN an die Dateien kommen.


Wie funktioniert die Übersetzerei praktisch?

WICHTIG: Da sich immer mal wieder etwas (Standards, Formate, o.ä.) ändern kann, ist es wichtig, sich entweder in die Mailinglisten einzutragen oder sich hier auf dem Laufenden zu halten.

Im weiteren gehe ich davon aus, dass grundlegende Kenntnisse über die Struktur und Syntax von DocBook? vorhanden sind. Wer noch nicht mit DocBook? gearbeitet hat, dem sei der Crashkurs (external link) empfohlen, der bei den KDE DocBook-Tools dabei ist.


Welche Dokumentationen müssen noch übersetzt bzw. aktualisiert werden?

Claudiu Costin unterhält eine Dokumentations-Statistik (external link), die täglich aktualisiert wird. Auf dieser Seite ist eine Übersicht, welche Dokumentation schon vorhanden ist und ob sie im Vergleich zur englischen Originalversion aktuell ist. Allerdings sollte diese Statistik mit Vorsicht benutzt werden, da diese nur Dokumentationen anzeigt, die mindestens zu irgendeiner Zeit einmal zu 100% übersetzt gewesen sind. Sie vergleicht die DocBook-Dateien, die durch po2xml aber erst dann erzeugt werden, wenn die PO-Datei keine Fuzzies und unübersetzten Texte mehr enthält.

Grundsätzlich solltest Du Dich mit dem Autor der englischen Doku in Verbindung setzen, um zu erfahren, ob in absehbarer Zeit eine neue englische Version geplant ist, sonst übersetzt Du vielleicht mit viel Mühe eine Dokumentation, die bereits in Kürze veraltet ist. Den Autornamen und seine E-Mail-Adresse findest Du in der englischen DOCBOOK-Datei.

Wenn du die Quellen von kde-i18n für Deutsch bereits auf Deinem Rechner hast, liefert der Katalogmanager von KBabel deutlich mehr Informationen. Die Beschreibung zu KBabel befindet sich weiter unten.

Wenn du eine Dokumentation übersetzen willst, die noch nicht übersetzt wurde, findest du weiter unten eine Schritt-für-Schritt-Anleitung. Die Beschreibung deckt auch die Weiterführung oder Aktualisierung einer bereits vorhandenen Übersetzung ab.

Außerdem ist natürlich noch wichtig, dass nicht schon jemand anders an der Dokumentation arbeitet. Auf jeden Fall solltest du, bevor du mit der Übersetzung beginnst, die Sache mit dem Koordinator für deutsche Dokumentation oder dem Betreuer des fraglichen Pakets? abgesprochen haben.

Hier nochmal der Hinweis: Vor der Übersetzung sollte man den Autor der englischen Dokumentation kontaktieren, um sicher zu stellen, das nicht in naher Zukunft eine neue Ausgabe geplant ist. Schließlich will man sich ja keine unnötige Arbeit machen.


Schritt für Schritt: Die Übersetzung von POTs und POs

Praktisch läuft das jetzt so ab, dass KBabel installiert und die betreffende Datei damit übersetzt werden. (Außerdem werden die aktuellen Versionen der Ordner l10n/templates/docmessages/, l10n/de/docmessages/ und l10n/documentation/<paketname> aus dem SVN benötigt.)
Das sieht dann etwa folgendermaßen aus:
  • Beim ersten Start von KBabel werden Benutzerdaten abgefragt, die bitte möglichst korrekt einzutragen sind, da hieraus die Kopfzeilen der übersetzten Dateien erstellt werden. Falls die Daten nicht von selbst abgefragt werden, trage sie bitte von Hand ein: Projekt -> Einrichten... -> Identität. Vergiss v. a. nicht, unter Projekt -> Einstellungen... -> Speichern die Kodierung "utf8" einzustellen (8bit Unicode Transfer Format).
    Es empfiehlt sich außerdem, unter Einstellungen -> KBabel einrichten... -> Bearbeiten -> Erscheinungsbild die Option "Umgebende Anführungszeichen" zu aktivieren, da man sonst Leerzeichen an den Zeilenenden leicht übersieht.

  • Nach dem Start von KBabel sollte zunächst der Katalogmanager aufgerufen werden. Er zeigt an, was im Einzelnen zu bearbeiten ist (Fuzzies, unübersetzte Strings und Programme). Dies funktioniert natürlich nur, wenn eine aktuelle Kopie der Ordner l10n/templates/docmessages/ und l10n/de/docmessages/ vorliegt. Außerdem müssen die Pfade zu diesen Ordnern im Katalogmanager eingestellt werden: Projekt -> Einrichten... -> Ordner.

  • Wenn der Katalogmanager anzeigt, dass noch keine Übersetzung für das jeweilige Programm existiert (sprich: es gibt noch keine gleichnamige PO-Datei im entsprechenden Ordner "l10n/de/docmessages/<paketname>") - und nur in diesem Fall! - dann wird eine POT-Datei in den Editor geladen und mit der Endung "po" neu abgespeichert, und zwar eben dorthin, wo man grade vergeblich gesucht hat. Das ergibt dann eine Datei namens "l10n/de/docmessages/<paketname>/programmname.po".

    KBabel erledigt alle diese Schritte automatisch beim Laden aus dem Katalogmanager und anschließendem Sichern der Datei, sofern die Pfade unter Projekt -> Einstellungen... -> Ordner richtig gesetzt wurden.

    Ab hier wird für das betreffende Programm nur noch mit der PO-Datei gearbeitet. Der Großteil der Arbeit besteht ab nun im Aktualisieren, Verbessern und Vereinheitlichen bereits vorhandener Übersetzungen (also bereits vorliegender POs).

  • Beim Aktualisieren werden die leeren Strings neu übersetzt und die mit "fuzzy" gekennzeichneten kontrolliert und nötigenfalls korrigiert. "Nötigenfalls" bedeutet übrigens soviel wie "fast immer".
    Für die Korrektur von Dokumentationen bietet KBabel einen "Diff-Modus". Bei aktiviertem Diff-Modus (bei der Korrektur von Dokumentation sollte dieser immer aktiviert sein) erscheinen in der msgid neu hinzugekommene oder gelöschte Zeichen farbig hervorgehoben. Die benötigten Informationen werden aus der Übersetzungsdatenbank gewonnen, die einmal angelegt automatisch die msgstrs und msgids speichert.
    Wenn Du Korrekturen an einem "fuzzy" vorgenommen hast, löscht KBabel den Vermerk "fuzzy" automatisch. Falls die Übersetzung korrekt war und unverändert bleiben soll, muss der Vermerk von Hand beseitigt werden (strg+u). Als fuzzy markierte Strings werden beim Kompilieren nicht berücksichtig und werden somit auch nicht übersetzt angezeigt.

    KBabel löscht auch automatisch überflüssig gewordene Zeilen, die sich auskommentiert am Ende der Datei befinden und bei der Arbeit mit dem Programm nicht mehr angezeigt werden. Zum Beispiel solche:

    #~ msgid "Where do you want to go tomorrow?"
    #~ msgstr "Where do you want to go tomorrow?"
    #~ msgid "No comment available"
    #~ msgstr "Keine Erklärung verfügbar"

    Dabei handelt es sich um Texte und ihre Übersetzungen, die nicht mehr länger zugeordnet werden konnten — zumeist einfach, weil sie ganz weggefallen sind oder in der Dokumentation an andere Stellen verschoben wurden.

    Eine vollständige beispielhafte PO-Datei? befindet sich auf einer extra Seite.

Wenn bei der Dokumentation Bildschirmphotos des Programms beiliegen, sollen diese in der deutschen Übersetzung die deutsche Programmoberfläche zeigen. Um Bildschirmphotos zu machen, eignet sich KSnapshot ganz gut, aber du kannst genauso gut ein anderes Programm dazu verwenden.
ACHTUNG: Falls das Bild nicht gerade ein bestimmtes Design zeigen soll, sollte es mit dem Standard KDE-Design erstellt werden. Ein extravagantes Aussehen sorgt nur für Verwirrung beim Benutzer.
Die Bilder sollten dann unter dem gleichen Namen wie die Originalbilder im Ordner l10n/de/docs/<modul>/<paketname> abgespeichert werden. Das erleichtert auch später die Aktualisierung der Dokumentation.
WICHTIG: Bildschirmphotos nicht mehr im GIF-Format verwenden, sondern im PNG-Format speichern.
Weitere Informationen zu Bildschirmphotos für KDE Dokumentationen findest du hier (external link).

Für alles Weitere verweisen wir auf die Infoseiten des gettext-Pakets.


Häufige Probleme und Fehler

  • Bitte nicht Satz für Satz übersetzen, sondern immer abschnittsweise. Also immer einen Abschnitt lesen, und diesen dann sinngemäß übersetzen.

  • Bei Screenshots bitte immer darauf achten, dass auch wirklich das aktuelle GUI gezeigt wird.

  • Zeilenumbrüche haben keinen Einfluss auf die Formatierung der Dokumentation. Sie können an beliebiger Stelle im msgstr eingefügt werden. Wichtig ist aber ein Leerzeichen am Zeilenende. Zum Beispiel wird

    "... volume of your"
    "sound card."

    in der Dokumentation fälschlicherweise zu

    ... volume of yoursound card.

Folgende Punkte besonders beachtet werden:
  • Die msgids CREDIT_FOR_TRANSLATORS und ROLES_OF_TRANSLATORS spielen eine Sonderrolle. Hier trägt sich der Übersetzer (ev. auch mehrere) ein. Dabei muss ein bestimmtes Markup beachtet werden. Die msgstrs müssen die folgende Form haben:

    msgid "CREDIT_FOR_TRANSLATORS"
    msgstr ""
    "<para>Übersetzung: Vorname Nachname "
    "<email>E-Mailadresse</email></para><para>Überarbeitung der "
    "Übersetzung: Vorname2 Nachname2 <email>E-Mailadresse2</email></para>"



    msgid "ROLES_OF_TRANSLATORS"
    msgstr ""
    "<othercredit "
    "role=\"translator\"><firstname>Gregor</firstname><surname>Zumstein</surname>"
    "<affiliation><address><email>zumstein@ssd.ethz.ch</email></address>"
    "</affiliation><contrib>Übersetzung</contrib></othercredit><othercredit "
    "role=\"translator\"><firstname>Frank</firstname><surname>Schütte</surname>"
    "<affiliation><address><email>F.Schuette@t-online.de</email></address>"
    "</affiliation><contrib>Überarbeitung der "
    "Übersetzung</contrib></othercredit>"

    Die einfachste Art, die korrekten XML-Tags in die Übersetzung zu übernehmen, besteht darin, dass man in diesem Fall die Tastenkombination Strg-Leertaste betätigt. Diese kopiert automatisch die oben erwähnten Einträge, allerdings ohne Inhalt, in den Übersetzungsteil. Hier dann bitte aufpassen, dass die Inhalte richtig in die Tags eingefügt werden.

  • Reservierte Zeichen wie z. B. Anführungen müssen durch einen Backslash ("\") entschärft werden, wenn sie als normale Buchstaben gelten sollen:

    Aktiviert die Vollbilddarstellung. Weitere Informationen finden Sie unter
    <link linkend=\"aktion-fullscreen\">Vollbildanzeige von &aktion;
    verwenden.</link>

    KBabel unterstützt dich dabei, indem es bei der Eingabe eines Anführungszeichens automatisch ein Backslash ergänzt.

  • & führt zur Einfärbung des msgstrs in der Fehlerfarbe. KBabel dient auch zur Übersetzung von Programmoberflächen. Dort gibt es Menükurzbefehle, die durch ein & gekennzeichnet werden. Für die Übersetzung von Dokumentationen kann diese hier fälschliche Einfärbung (der msgstr muss nicht die gleiche Anzahl an & wie die msgid enthalten) irritieren. Sie kann unter Einstellungen -> KBabel einrichten... -> Bearbeiten -> Allgemein -> Bei Fehler Textfarbe ändern abgeschaltet werden. Hier kann man auch einrichten, welche Prüfungen überhaupt automatisch durchgeführt werden sollen.

  • Entities wie z. B. &Enter; können in der Regel so (unübersetzt) ins Deutsche übernommen werden. Die Systemweit verfügbaren Entities und deren Übersetzung ins Deutsche findest Du in der Liste der Entities.

Was musst du sonst noch bei der Übersetzung beachten?

Organisatorisches und Syntaktisches:
  • Wenn du bei der Übersetzung feststellst, dass die Originaldokumentation nicht konsistent ist oder schlecht oder unklar formuliert ist, so sind wir übereingekommen, dass man das in der Übersetzung bereinigen sollte. Beispiel dafür sind häufige Wortwiederholungen, schwammige Formulierungen usw.

  • Weiterhin solltest du, wenn du feststellst, dass die Beschreibungen in der Dokumentation nicht mehr mit der aktuellen GUI übereinstimmen oder einfach etwas fehlt, dieses nicht in deiner Übersetzung ergänzen, sondern dich auf jeden Fall mit dem Autor der Originaldokumentation bzw. dem Dokumentationsteam in Verbindung setzen, da in der Regel neue Markups und damit auch neue zu übersetzende "messages" in die POT-Dateien eingesetzt werden müssen.

  • Es kann auch vorkommen, dass du unklare, falsche Bezeichnungen in der deutschen Übersetzung findest oder einfach einen besseren Vorschlag hast. In diesem Fall solltest du dich (wenn du nicht selbst die GUI-Übersetzung des Programms machst) mit dem Übersetzer der GUI in Verbindung setzen.

  • Der Programmname darf nicht verändert werden bzw. nur den Namen benutzen, der auch im K-Menü auftaucht! Bei der Kurzbeschreibung vielleicht mal einen Blick auf den Hinweis werfen, der im K-Menu erscheint bzw. der in der zum Programm gehörigen '.desktop'-Datei steht. Eventuell kannst du das übernehmen.

  • Bildschirmphotos und alle anderen Bilder müssen im Format PNG (Portable Network Graphics) sein, da aus lizenzrechtlichen Gründen auf GIF-Bilder verzichtet werden soll.

Stil und ähnliches:

  • Es ist wichtig zu wissen, dass in verschiedenen Kulturkreisen verschiedene Erwartungen an die Formulierung technischer Anleitungen gestellt wird.

  • Zitat aus der Zeit Nr.18 1999, Seite 37:
    "Der amerikanische Text ist oft sehr salopp. Deutsche Leser bevorzugen dagegen einen neutralen Ton und einen zupackenden, geschmeidigen Stil. Vermeiden Sie lange eingebettete Satzkonstruktionen ..."
    Das solltest du bei der Formulierung der Übersetzung immer im Kopf haben. Du musst natürlich nicht alle Witze rauswerfen, aber zuviel des Guten verleiht halt hierzulande schnell einen unseriösen Eindruck.

  • Die Anrede des Lesers bitte immer förmlich mit "Sie". Wichtig: Großschreibung.


Sichtwort: Einheitlichkeit

Lies zu diesem Thema bitte auch den entsprechenden Abschnitt in der allgemeinen Anleitung.

Vorerst besteht das Bestreben nach einer einheitlichen Übersetzung der Dokumentation aus einer Datenbank mit Standardübersetzungen (external link) (Anmerkung: leider scheint diese Datenbank nicht zu funktionieren). Zusätzlich sind in einer weiteren Liste Empfehlungen gegeben, wie immer wieder vorkommende Textpassagen übersetzt werden sollten. Es kann natürlich vorkommen, dass ein Begriff in einem bestimmten Kontext des Verständnisses wegen anders übersetzt werden sollte.


Stichwort: Rechtschreibung

Da ab dem 1. August 1999 alle (oder zumindest die meisten) deutschen Zeitschriften und Zeitungen die neue Rechtschreibung übernommen haben, haben wir beschlossen, diese auch in den KDE-Dokumentationen zu verwenden. Auch wenn du selbst vielleicht kein Befürworter der Rechtschreibreform bist, versuche bitte, dich daran zuhalten. Links zu weiterführenden Anleitungen und Nachschlagewerken findest du in der Linkliste.


Kontrolle der Übersetzung

Zwei wichtige Dinge sind zu prüfen, bevor du die Dokumentation veröffentlichst: Rechtschreibung und Syntax der XML-Anweisungen.

  • KBabel enthält ein Menü zur Aktivierung der Rechtschreibprüfung. Es verwendet die Pakete aspell oder ispell, die in jeder Linux-Distribution enthalten sind.

  • Etwas komplizierter ist die syntaktische Überprüfung der erstellten Dokumentation. Sie erfolgt in zwei Schritten. Erstens muss aus der PO-Datei die übersetzte DOCBOOK-Datei erstellt werden. Dafür gibt es verschiedene Möglichkeiten:

    • Sofern du die für deine Sprache nötigen Teilbäume des Pakets kde-i18n (l10n/de/docs) und die Quellen der englischen Dokumentation hast (l10n/documentation/<modul>/<paket>), dessen Dokumentation du übersetzt hast, kannst du das Skript update_xml im Oder l10n aufrufen. Das Skript verwendet po2xml zur Erzeugung der Docbook-Dateien. Zwei Parameter können dem Skript übergeben werden. Als erster (erforderlicher) Parameter wird der Name des Sprach-Ordners übergeben, also

      update_xml de

      für die deutschsprachige Dokumentation. Das Skript nimmt die aktuellen PO-Dateien und erstellt mit Hilfe der englischen DOCBOOK-Dateien die übersetzte deutsche DOCBOOK-Datei im richtigen Unterordner. Soll nur ein bestimmtes Programm oder Paket aktualisiert werden, kann dem Skript als zweiter Parameter der Programm- oder Paketname übergeben werden:

      update_xml de kdenetwork

      Als Übersetzer hat man gewöhnlich nur Interesse daran, dass gerade übersetzte Handbuch zu generieren. Die ist z. B. mit dem folgenden Aufruf möglich:

      update_xml de kdepim/kmail

      Das erspart hier die Generierung des gesamten Paketes kdepim und somit viel Zeit.

    • Mindestens benötigst du die englische DOCBOOK-Datei (in der Regel im Unterordner doc des Programmpakets unter dem Namen index.docbook) und die deutsche PO-Datei. Das Programm po2xml übernimmt wiederum die Erstellung der DOCBOOK-Datei:

      po2xml [Englische DOCBOOK-Datei] [PO-Datei] >[Übersetzte DOCBOOK-Datei]

      Im Kopf dieser Datei muss jetzt noch von Hand der Abschnitt

      <!ENTITY % English "INCLUDE" > <! change language only here >

      durch die Landessprache, also für die deutsche Übersetzung

      <!ENTITY % German "INCLUDE" > <! change language only here >

      eingesetzt werden.

  • Jetzt muss die soeben erstellt DOCBOOK-Datei auf syntaktische Korrektheit überprüft werden.
    WICHTIG!! Es reicht nicht aus, die DOCBOOK-Datei im KDE-Hilfezentrum darzustellen. Der dortige Parser ist auf Geschwindigkeit optimiert und stellt daher alles dar, was irgendwie den Konventionen von XML entspricht. Er ist sehr großzügig im Hinblick auf Markup-Fehler.
    Stattdessen gibt es von Stephan Kulow das Programm meinproc. Es wird mit

    meinproc --check [übersetzte DOCBOOK-Datei]

    aufgerufen. Falls es nicht fehlerfrei parsen kann, meldet es die Zeilennummern und unkorrekten Textteile.

  • Fehlerkorrektur: Wenn meinproc einen Fehler meldet, musst du die passende Stelle der PO-Datei suchen, was mittels des von meinproc ausgedruckten Kontextes kein Problem darstellt, und dort den Fehler korrigieren. Eine Korrektur der übersetzten DOCBOOK-Datei ist sinnlos, da sie ja maschinell aus der PO-Datei erzeugt wird.


Wohin mit der übersetzten Dokumentation?

Um die Konsistenz zu verbessern und Tipp- und Grammatikfehler zu reduzieren, haben wir beschlossen, alle Dokumentationen von einem anderen als dem Übersetzer noch mal gegenlesen zu lassen. Da man dazu neigt, einen Text nur noch zu überfliegen, wenn man ihn zu oft gelesen hat, fallen einem viele Fehler häufig nicht mehr auf.

Du gehst also folgendermaßen vor:
Wenn du die PO-Datei nochmal auf Syntaxfehler getestet hast und die Rechtschreibung in Ordnung ist, packe sie mit gzip. Die gepackte Datei sollte den Namen des zu der Dokumentation gehörenden Programms haben, also z. B. kmix_doc_po_011231.gz. Wenn Screenshots dabei sind, dann bitte alles zusammen mit tar und gzip packen. Hast du mehrere Dateien eines Pakets geändert, ist es einfacher, das komplette Paket zu versenden, also z. B. kdemultimedia_doc_po_011231.gz Diese Datei sendest du dann dem Koordinator des Übersetzungsteams, der sie dann zu einem Anderen zum Gegenlesen weiterschickt. Danach wird sie dann auf dem Webserver veröffentlicht. Ab da werden dann tausende (wenn nicht millionen ;-)) Leute deine Dokumentation lesen, wenn sie die Hilfe in dem Programm aufrufen.
Das sollte man sich bewusst machen.

BearbeitenQuelleHistorie

Menü