Po4a(7) Rahmenwerk zur Übersetzung von Dokumentation und anderen Materialien

Einleitung

Das Projektziel von Po4a (PO für alles) ist es, die Übersetzung (und interessanter, die Wartung der Übersetzung) zu vereinfachen, indem die Gettext-Werkzeuge auch für Gebiete verwendet werden, wo diese nicht erwartet werden, wie Dokumentation.

Inhaltsverzeichnis

Das Dokument ist wie folgt organisiert:
1. Warum sollte ich Po4a verwenden? Wofür ist es gut?
Dieses einleitende Kapitel erklärt die Motivation des Projekts und seine Philosophie. Sie sollten es zuerst lesen, falls Sie gerade dabei sind, Po4a für Ihre eigene Übersetzungen zu untersuchen.
2. Wie wird Po4a verwandt?
Dieses Kapitel ist eine Art Referenzhandbuch. Es versucht, die Fragen der Benutzer zu beantworten und ihnen ein besseres Verständnis des gesamten Prozesses zu vermitteln. Hier wird eingeführt, wie Po4a mit den Dingen umgeht und es dient als Einleitung zur Dokumentation der speziellen Werkzeuge.
HOWTO: Wie wird eine neue Übersetzung begonnen?
HOWTO: Wie wird die Übersetzung zurück in eine Dokumentationsdatei zurücküberführt?
HOWTO: Wie wird eine Po4a-Übersetzung aktualisiert?
HOWTO: Wie wird eine existierende Übersetzung nach Po4a konvertiert?
HOWTO: Wie wird zusätzlicher Text zu Übersetzungen (wie der Name des Übersetzers) hinzugefügt?
HWOTO: Wie erfolgt alles dies in einem Programmaufruf?
HOWTO: Wie wird Po4a angepasst?
3. Wie funktioniert es?
Dieses Kapitel gibt Ihnen einen kurzen Überblick über die Interna von Po4a, so dass Sie sich sicherer fühlen, es zu warten und zu verbessern. Es könnte Ihnen auch dabei helfen, zu verstehen, warum es nicht das tut, was Sie erwarten, und wie Sie Ihre Probleme beheben können.
4. FAQ
Dieses Kapitel gruppiert die häufig gestellten Fragen (»Frequently Asked Questions«). In der Tat könnten derzeit die meisten dieser Fragen wie folgt formuliert werden: »Warum wurde es auf diese Weise entwickelt und nicht auf eine andere?«. Falls Sie glauben, Po4a ist nicht die richtige Lösung zur Übersetzung von Dokumentation, sollten Sie diesen Abschnitt lesen. Falls er Ihre Frage nicht beantwortet, nehmen Sie auf unserer Mailingliste <[email protected]> mit uns (auf Englisch) Kontakt auf. Wir freuen uns über Rückmeldungen.
5. Spezielle Hinweise zu Modulen
Dieses Kapitel stellt die Besonderheiten jedes Moduls vor, jeweils aus dem Blickwinkel des Übersetzers und ursprünglichen Autors. Lesen Sie diesen Abschnitt, um die Syntax kennenzulernen, die Ihnen beim Übersetzen in diesem Modul begegnen wird oder die Regeln, denen Sie in ihrem Originaldokument folgen sollten, um das Leben der Übersetzer zu erleichtern.

Tatsächlich ist dieser Abschnitt nicht wirklich Teil dieses Dokuments. Stattdessen befindet er sich in jeder Modul-Beschreibung. Dies stellt sicher, das die Information aktuell ist, indem die Dokumentation und der Code zusammengehalten werden.

Warum sollte ich Po4a verwenden? Wofür ist es gut?

Ich finde die Idee der Open-Source-Software gut, die jedem Zugriff auf die Software und ihre Quellen erlaubt. Als Franzose ist mir aber auch klar, dass die Lizenz nicht die einzige Beschränkung der Offenheit von Software ist: nicht übersetzte freie Software ist für Personen, die kein Englisch sprechen, nutzlos und wir haben noch einiges zu tun, um diese für jeden da draußen verfügbar zu machen.

Die Wahrnehmung dieser Situation hat sich bei den Akteuren im Bereich Open Source in den letzten Jahren dramatisch verbessert. Wir, die Übersetzer, haben den ersten Kampf gewonnen und jeden von der Bedeutung der Übersetzungen überzeugt. Unglücklicherweise war dies der leichte Teil. Jetzt haben wir was zu tun, und tatsächlich all dieses Zeug zu übersetzen.

Tatsächlich profitiert Open-Source-Software selbst von einem eher anständigen Übersetzungsniveau, Dank der wundervollen Gettext-Werkzeugsammlung. Diese ist in der Lage, zu übersetzende Zeichenketten aus dem Programm herauszulösen, sie in einem einheitlichen Format dem Übersetzer anzubieten und dann das Ergebnis dessen Arbeit zur Laufzeit zur Anzeige übersetzter Meldungen an den Benutzer zu verwenden.

But the situation is rather different when it comes to documentation. Too often, the translated documentation is not visible enough (not distributed as a part of the program), only partial, or not up to date. This last situation is by far the worst possible one. Outdated translation can turn out to be worse than no translation at all to the users by describing old program behavior which are not in use anymore.

Das zu lösende Problem

Die Übersetzung von Dokumentation ist an sich nicht sehr schwierig. Texte sind deutlich länger als Programmmeldungen und die Übersetzung dauert daher länger, allerdings werden dazu keine besonderen Fähigkeiten benötigt. Die Schwierigkeit liegt im Warten der Übersetzungsarbeit. Es ist sehr schwierig, fehleranfällig und unangenehm, herauszufinden, welche Teile sich geändert haben und aktualisiert werden müssen. Ich denke, das erklärt, warum so viele übersetzte Dokumentationen da draußen veraltet sind.

Die Antworten von Po4a

Daher besteht der ganze Sinn von Po4a darin, die Dokumentationsübersetzungen wartbar zu halten. Die Idee ist, die Gettext-Methodologie für dieses neue Feld zu nutzen. Wie bei Gettext werden Texte aus ihren ursprünglichen Stellen herausgelöst, um in einem einheitlichen Format den Übersetzern präsentiert zu werden. Die klassischen Gettext-Werkzeuge helfen dann beim Aktualisieren ihrer Arbeiten, wenn eine neue Veröffentlichung des Originals herauskommt. Im Gegensatz zum klassichen Gettext-Modell werden die Übersetzungen dann wieder in die Struktur des ursprünglichen Dokuments eingefügt, so dass es wie die ursprüngliche (englische) Version verarbeitet und verteilt werden kann.

Daher wird die Ermittlung der geänderten (und daher zu aktualisierenden) Teile des Dokuments sehr leicht. Ein anderer Pluspunkt liegt darin, dass die Werkzeuge fast die gesamte Arbeit übernehmen, wenn die Struktur des Originals fundamental neu organisiert wird und wenn Kapitel herumgeschoben, zusammengefasst oder geteilt werden. Indem der zu übersetzende Text aus der Dokumentenstruktur herausgelöst wird, hält Sie dies auch von der Komplexität der Textformatierung fern und reduziert das Risiko, dass Sie ein defektes Dokument erhalten (selbst wenn das nicht vollständig verhindert wird).

Bitte lesen Sie auch die FAQ weiter unten in diesem Dokument für eine komplette Liste der Vor- und Nachteile dieser Vorgehensweise.

Unterstützte Formate

Derzeit wurde diese Vorgehensweise erfolgreich für mehrere Arten von Textformatierungsformaten umgesetzt:

man

Das gute alte Handbuchformat, verwandt von vielen Programmen da draußen. Die Unterstützung durch Po4a wird hier sehr begrüßt, da dieses Format etwas schwierig zu benutzen und für Neulinge nicht wirklich einladend ist. Das Modul Locale::Po4a::Man(3pm) unterstütz das Format »mdoc«, das von den BSD-Handbuchseiten verwandt wird (diese sind auch unter Linux recht häufig anzutreffen).

pod

Das ist das »Perl Online Documentation«-Format. Die Sprache und Erweiterungen selbiger sind auf diese Art dokumentiert sowie die meisten existierenden Perl-Skripte. Sie erleichtert es, die Dokumentation nahe beim eigentlichen Code zu halten, indem beide in die gleiche Datei eingebettet werden. Es erleichtert Programmierern die Arbeit, aber unglücklicherweise nicht den Übersetzern.

sgml

Obwohl dieses Format heutzutage etwas von XML verdrängt wurde, wird es noch recht oft für Dokumente verwandt, die mehr als ein paar Bildschirmseiten lang sind. Es ermöglicht es Ihnen, komplette Bücher zu erstellen. Die Übersetzung so langer Dokumente zu aktualisieren kann zu einem echten Alptraum werden. diff stellt sich oft als nutzlos raus, wenn der ursprüngliche Text nach der Aktualisierung neu eingerückt wurde. Glücklicherweise kann Ihnen Po4a bei diesem Prozess helfen.

Derzeit werden nur die DebianDoc- und DocBook-DTD unterstützt, aber das Hinzufügen einer Unterstützung für eine neue DTD ist wirklich leicht. Es ist sogar möglich, Po4a für eine unbekannte SGML-DTD zu verwenden, ohne den Code zu verändern, indem die benötigten Informationen auf der Befehlszeile übergeben werden. Lesen Sie Locale::Po4a::Sgml(3pm) für weitere Details.

TeX / LaTeX

Das LaTeX-Format ist ein wichtiges Dokumentationsformat, das in der Welt der Freien Software und für Veröffentlichungen genutzt wird. Das Modul Locale::Po4a::LaTeX(3pm) wurde mit der Python-Dokumentation, einem Buch und ein paar Präsentationen ausprobiert.

Texinfo

Die gesamte GNU-Dokumentation ist in diesem Format geschrieben (das ist sogar eine der Voraussetzungen, um ein offizielles GNU-Projekt zu werden). Die Unterstützung für Locale::Po4a::Texinfo(3pm) in Po4a ist noch ganz am Anfang. Bitte berichten Sie Fehler und Funktionalitätswünsche.

xml

Das XML-Format liegt vielen Dokumentationsformaten zu Grunde.

Derzeit wird die DocBook-DTD von Po4a unterstützt. Lesen Sie Locale::Po4a::Docbook(3pm) für weitere Details.

andere

Po4a kann auch mit einigen selteneren oder spezialisierten Formaten umgehen, wie dem Dokumentationsformat der Kompilierungsoptionen des 2.4.x-er Kernels oder der vom Dia-Werkzeug erstellten Diagramme. Das Hinzufügen eines neuen Formats ist oft sehr leicht und die Hauptaufgabe besteht darin, einen Parser für Ihr Zielformat zu entwickeln. Lesen Sie Locale::Po4a::TransTractor(3pm) für mehr Informationen dazu.

Nicht unterstützte Formate

Unglücklicherweise fehlt Po4a noch Unterstützung für einige Dokumentationsformate.

Es gibt einen ganzen Satz an weiteren Formaten, die wir gerne mit Po4a unterstützen würden, nicht nur Dokumentationsformate. Tatsächlich würden wir gerne alle Marktnischen besetzen, die von den klassichen Gettext-Werkzeugen freigelassen werden. Darunter fallen Paketbeschreibungen (Deb und RPM), Paketinstallationsskriptfragen, Paket-Änderungsprotokolle (»Changelogs«) und alle spezialisierten Dateiformate, die von Programmen verwandt werden, wie Spieleszenarien oder WINE-Ressource-Dateien.

Wie wird Po4a verwandt?

Dieses Kapitel ist eine Art Referenzhandbuch. Es versucht, die Fragen der Benutzer zu beantworten und ihnen ein besseres Verständnis des gesamten Prozesses zu vermitteln. Hier wird eingeführt, wie Po4a mit den Dingen umgeht und es dient als Einleitung zur Dokumentation der speziellen Werkzeuge.

Graphischer Überblick

Das folgende Schema gibt einen Überblick über den Prozess der Dokumentationsübersetzung mittels Po4a. Haben Sie keine Angst vor der scheinbaren Komplexität, dies kommt daher, das hier der gesamte Prozess dargestellt ist. Sobald Sie Ihr Projekt auf Po4a umgestellt haben, ist nur der rechte Teil der Graphik relevant.

Beachten Sie, dass Master.dok als Beispiel der zu übersetzenden Dokumentation dient und Übersetzung.dok der entsprechende übersetzte Text ist. Die Endung könnte .pod, .xml oder .sgml lauten, abhängig vom Format. Jeder Teil der Abbildung wird in den folgenden Abschnitten noch im Detail dargestellt. 

                                   Master.dok
                                       |
                                       V
     +<-----<----+<-----<-----<--------+------->-------->-------+
     :           |                     |                        :
{Übersetzung}    |     { Aktualisierung von Master.dok }        :
     :           |                     |                        :
   XX.dok        |                     V                        V
(optional)       |                 Master.dok ->-------->------>+
     :           |                   (neu)                      |
     V           V                     |                        |
  [po4a-gettextize]   dok.XX.po--->+   |                        |
          |            (alt)       |   |                        |
          |              ^         V   V                        |
          |              |     [po4a-updatepo]                  |
          V              |           |                          V
   Übersetzung.pot       ^           V                          |
          |              |         dok.XX.po                    |
          |              |        (unscharf)                    |
   { Übersetzung }       |           |                          |
          |              ^           V                          V
          |              |  {manuelle Bearbeitung}              |
          |              |           |                          |
          V              |           V                          V
      dok.XX.po --->---->+<---<---- doc.XX.po   Addendum     Master.dok
    (anfänglich)                   (aktuell)   (optional)     (aktuell) 
          :                          |            |             |
          :                          V            |             |
          +----->----->----->------> +            |             |
                                     |            |             |
                                     V            V             V
                                     +------>-----+------<------+
                                                  |
                                                  V
                                           [po4a-translate]
                                                  |
                                                  V
                                                XX.dok
                                              (aktuell)

Auf der linken Seite wird gezeigt, wie eine Umstellung von einer Übersetzung, die Po4a nicht verwendet, in dieses System erfolgt. Oben im rechten Teil werden die Tätigkeiten des ursprünglichen Autors dargestellt (Aktualisierung der Dokumentation). In der Mitte vom rechten Teil sind die automatischen Tätigkeiten von Po4a dargestellt. Das neue Material wird herausgelöst und mit der existierenden Übersetzung verglichen. Unveränderte Teile werden gefunden und vorherige Übersetzungen verwandt. Teile, die teilweise geändert wurden, werden auch mit der vorherigen Übersetzung verbunden, allerdings mit einer speziellen Markierung, die angibt, dass die Übersetzung aktualisiert werden muss. Der untere Teil der Abbildung zeigt, wie formatierte Dokumente gebaut werden.

Tatsächlich ist der einzige manuelle Arbeitsschritt, den Sie als Übersetzer durchführen müssen, die Bearbeitung des mit »{manuelle Bearbeitung}« markierten Bereiches. Jaja, es tut mir leid, Po4a hilft beim Übersetzen. Es übersetzt nichts für Sie …

HOWTO: Wie wird eine neue Übersetzung begonnen?

Dieser Abschnitt stellt die benötigten Schritte dar, um eine neue Übersetzung mit Po4a zu beginnen. Die Verfeinerungen, um ein existierendes Projekt in dieses System zu überführen, werden in den relevanten Abschnitten dargestellt.

Um eine neue Übersetzung mit Po4a anzufangen, müssen Sie die folgenden Schritte ausführen:

-
Herauslösen des zu übersetzenden Texts aus dem ursprünglichen Dokument <Master.dok> in eine neue Übersetzungsvorlagendatei <Übersetzung.pot> (dem Gettext-Format). Verwenden Sie dafür das Programm po4a-gettextize auf folgende Art und Weise: 

  $ po4a-gettextize -f <Format> -m <Master.dok> -p <Übersetzung.pot>

<Format> ist natürlich das im Dokument Master.dok verwandte Format. Wie erwartet, geht die Ausgabe in translation.pot. Bitte lesen Sie po4a-gettextize(1) für weitere Details über die existierenden Optionen.

-
Übersetzen Sie tatsächlich, was übersetzt werden soll. Dafür müssen Sie die POT-Datei in z.B. dok.XX.po umbenennen (wobei XX der ISO639-Code für die Sprache ist, in die Sie übersetzen, z.B. fr) und bearbeiten Sie die entstandene Datei. Oft ist es eine gute Idee, die Datei nicht XX.po zu nennen, um Verwirrung mit der Übersetzung der Programmmeldungen zu vermeiden, allerdings ist das Ihre Entscheidung. Vergessen Sie nicht, die Kopfzeilen der PO-Datei zu aktualisieren, sie sind wichtig.

Die eigentliche Übersetzung kann mit dem PO-Modus von Emacs oder Vi, Lokalize (KDE-basiert), Gtranslator (GNOME-basiert) oder mit welchem Programm Sie am liebsten arbeiten (z.B. Virtaal), erfolgen.

Wenn Sie mehr darüber wissen wollen, müssen Sie auf jeden Fall die Gettext-Dokumentation konsultieren. Sie ist im Paket gettext-doc verfügbar.

HOWTO: Wie wird die Übersetzung zurück in eine Dokumentationsdatei zurücküberführt?

Sobald Sie mit der Übersetzung fertig sind, möchten Sie die übersetzte Dokumentation erhalten und diese dann zusammen mit der ursprünglichen an die Benutzer verteilen. Verwenden Sie hierfür das Programm po4a-translate(1) wie folgt (wobei XX für den Sprachcode steht): 

  $ po4a-translate -f <Format> -m <Master.dok> -p <dok.XX.po> -l <XX.dok>

Wie vorher ist <format> das im Dokument Master.dok verwandte Format. Diesmal ist aber die mit dem Schalter -p übergebene PO-Datei Teil der Eingabe. Dies ist Ihre Übersetzung. Die Ausgabe landet in XX.dok.

Bitte lesen Sie po4a-translate(1) für weitere Details.

HOWTO: Wie wird eine Po4a-Übersetzung aktualisiert?

Um Ihre Übersetzung zu aktualisieren, wenn sich die ursprüngliche Datei Master.dok geändert hat, verwenden Sie das Programm po4a-updatepo(1) wie folgt: 

  $ po4a-updatepo -f <Format> -m <neue_Master.dok> -p <alte_dok.XX.po>

(Bitte lesen Sie po4a-updatepo(1) für weitere Details.)

Natürlich wird der neue Absatz in dem Dokument nicht magisch in der PO-Datei durch diesen Befehl übersetzt werden und Sie müssen die PO-Datei manuell aktualisieren. Entsprechend müssen Sie die Übersetzung für Absätze, die geändert wurden, anpassen. Um sicherzustellen, dass Sie keine verpassen werden diese beim Erstellen mit »fuzzy« markiert und Sie müssen diese Markierung entfernen, bevor die Übersetzung von po4a-translate verwandt werden kann. Wie bei der ursprünglichen Übersetzung verwenden Sie am besten Ihren Lieblings-PO-Editor hierfür.

Sobald Ihre PO-Datei wieder aktuell ist, ohne verbliebene unübersetzte oder unscharfe Zeichenketten, können Sie ein übersetztes Dokument erstellen, wie dies im vorherigen Abschnitt beschrieben wurde.

HOWTO: Wie wird eine existierende Übersetzung nach Po4a konvertiert?

Oft haben Sie ein Dokument manuell übersetzt, bis eine größere Reorganisation des ursprünglichen Dokuments Master.dok stattfand. Nach ein paar unschönen Versuchen mit diff und ähnlichen Werkzeugen möchten Sie auf Po4a umstellen. Allerdings möchten Sie natürlich nicht ihre bestehenden Übersetzungen dabei verlieren. Keine Angst, dieser Fall wird auch von den Po4a-Werkzeugen abgedeckt und wird »Gettextisierung« genannt.

Der Schlüssel ist dabei, dass die gleiche Struktur im übersetzten Dokument und in dem ursprünglichen vorliegt, so dass die Werkzeuge die zugehörigen Inhalte entsprechend ermitteln können.

Falls Sie Glück haben (d.h. falls die Struktur beider Dokumente perfekt passt) wird dies reibungsfrei verlaufen und Sie sind in wenigen Sekunden eingerichtet. Andernfalls werden Sie herausfinden, warum dieser Prozess so einen scheußlichen Namen hat und Sie bereiten sich auf Routinearbeit vor. Denken Sie in jedem Fall daran, dass dies der Preis ist, den Sie zahlen müssen, um den Komfort von Po4a danach zu genießen. Das gute daran ist, dass Sie diesen Prozess nur einmal durchführen müssen.

Ich kann das nicht oft genug wiederholen. Um den Prozess zu erleichtern, ist es daher wichtig, dass Sie die genau identische Version finden, die zur Übersetzung verwandt wurde. Am besten ist es, wenn Sie sich die VCS-Revision, die für die Übersetzung verwandt wurde, notiert hatten und Sie sie nicht im Übersetzungsprozess geändert haben, und Sie diese daher verwenden können.

Es wird nicht gut funktionieren, wenn Sie einen aktualisierten Originaltext mit der alten Übersetzung verwenden. Es bleibt möglich, aber es ist schwieriger und sollte wirklich vermieden werden, wenn möglich. Tatsächlich schlage ich vor, dass die beste Lösung, wenn Sie den ursprünglichen Text nicht wiederfinden können, ist, jemanden zu finden, der die Gettextisierung für Sie vornimmt (aber nicht mich ;).

Vielleicht bin ich hier zu dramatisch. Selbst wenn Dinge schiefgehen, bleibt dies deutlich schneller als eine komplette Neuübersetzung. Ich konnte die existierende französische Übersetzung der Perl-Dokumentation an einem Tag gettextisieren, selbst obwohl Dinge schief gegangen sind. Das waren mehr als zwei Megabyte an Text und eine neue Übersetzung hätte Monate oder mehr gedauert.

Lassen Sie mich zuerst die Grundlagen der Prozedur erläutern. Später werde ich dann Tipps für die Fälle geben, bei denen was schief läuft. Um das Verständnis zu erleichtern, verwende ich das obige Beispiel noch mal.

Sobald Sie Sie die alte Master.dok, auf welche die Übersetzung XX.dok passt, haben, kann die Gettextisierung direkt mit der PO-Datei dok.XX.po erfolgen, ohne die manuelle Übersetzung der Datei Übersetzung.pot: 

 $ po4a-gettextize -f <Format> -m <alte_Master.dok> -l <XX.dok> -p <dok.XX.po>

Wenn Sie Glück haben, war's das. Sie haben Ihre alte Übersetzung nach Po4a konvertiert und können mit der Aktualisierung sofort beginnen. Folgen Sie einfach den Anweisungen, wie sie einige Abschnitte weiter oben beschrieben wurden, um Ihre PO-Datei mit dem neusten Originaldokument zu synchronisieren, und aktualisieren Sie die Übersetzung entsprechend.

Beachten Sie, dass selbst wenn alles korrekt abgelaufen zu sein scheint, es immer noch Fehlermöglichkeiten gibt. Das liegt daran, dass Po4a nicht in der Lage ist, den Text zu verstehen, um sicherzustellen, dass die Übersetzung auf das Original passt. Daher werden alle Zeichenketten bei diesem Vorgang mit »fuzzy« (d.h. als unscharf) markiert. Sie sollten daher alle sorgfältig prüfen, bevor Sie diese Markierung entfernen.

Oft passen die Dokumentstrukturen nicht genau, wodurch po4a-gettextize daran gehindert wird, seine Aufgabe korrekt wahrzunehmen. Zu diesem Zeitpunkt besteht das Spiel darin, die Dateien zu bearbeiten, um ihre verdammte Struktur passend zu bekommen.

Es kann helfen, den Abschnitt Gettextization: Wie funktioniert es? unten zu lesen. Ein Verständnis des internen Vorgangs wird Ihnen bei der Durchführung helfen. Gut daran ist, dass po4a-gettextize recht ausführlich berichtet, was schief gelaufen ist, wenn das passiert. Zuerst nagelt es den Punkt fest, bei dem in den Dokumenten die Strukturdiskrepanzen vorliegen. Sie werden die Zeichenketten kennenlernen, die nicht zueinander passen, ihre Position im Text und ihren Typ. Desweiteren wird die soweit generierte PO-Datei in gettextization.failed.po ausgegeben.

-
Entfernen Sie alle zusätzlichen Teile in der Übersetzung, wie den Abschnitt, in dem Sie den Namen des Übersetzers angeben und allen danken, die zu der Übersetzung beigetragen haben. Addenda, die im nächsten Abschnitt beschrieben werden, erlauben es Ihnen, diese Informationen wieder hinzuzufügen.
-
Haben Sie keine Scheu, sowohl das Original als auch die Übersetzung zu bearbeiten. Das wichtigste ist, die PO-Datei zu erhalten. Sie können diese dann im Anschluss aktualisieren. Andererseits sollte die Bearbeitung der Übersetzung vorgezogen werden, wenn beide möglich wären, da dies die Dinge erleichtert, wenn die Gettextisierung abgeschlossen ist.
-
Falls notwendig, löschen Sie Teile des Originals, falls diese nicht übersetzt wurden. Beim anschließenden Synchronisieren der PO-Datei mit dem Dokument kommen diese von alleine zurück.
-
Falls Sie die Struktur etwas geändert haben (um zwei Absätze zusammenzufassen oder einen anderen aufzuteilen) nehmen Sie diese Änderungen zurück. Falls es Probleme im Original gibt, sollten Sie den Originalautor informieren. Wenn Sie diese nur in Ihrer Übersetzung korrigieren, werden diese nur für einen Teil der Gemeinschaft korrigiert. Und desweiteren ist das unmöglich, wenn Sie Po4a verwenden ;)
-
Manchmal passen die Inhalte des Absatzes, aber ihr Typ nicht. Dies zu korrigieren hängt stark vom Format ab. In POD und Man kommt dies oft daher, dass bei einem der beiden eine Zeile enthalten ist, die mit einem Leerzeichen beginnt. In diesen Formaten kann so ein Absatz nicht umgebrochen werden und erhält daher einen anderen Typ. Entfernen Sie einfach das Leerzeichen und es klappt wieder. Es kann sich auch um einen Tippfehler im Namen der Markierung (Tags) handeln.

Likewise, two paragraphs may get merged together in POD when the separating line contains some spaces, or when there is no empty line between the =item line and the content of the item.

-
Manchmal sind die Dateien nicht mehr synchron und die Übersetzuzng hängt am falschen Absatz. Dies zeigt an, dass das echte Problem schon früher in den Dateien vorlag. Überprüfen Sie gettextization.failed.po, um herauszufinden, wo die Desynchronisation beginnt und korrigieren Sie dies dort.
-
Manchmal erhalten Sie das starke Gefühl, dass Po4a Teile des Texts aufgefuttert hat, entweder vom Original oder von der Übersetzung. gettextization.failed.po können Sie entnehmen, dass beide gut aufeinander gepasst haben und dann Schlug die Gettextisierung fehl, da versucht wurde, einen Absatz mit einem Absatz vor (oder hinter) dem Richtigen zu paaren, als ob der richtige Absatz verschwunden wäre. Verfluchen Sie Po4a wie ich es getan habe, als es mir das erste Mal passierte. Gründlich.

Diese unglückliche Situation entsteht, wenn ein Absatz mehrfach im Dokument vorkommt. In diesem Fall wird kein neuer Eintrag in der PO-Datei erstellt, sondern es wird stattdessen eine neue Referenz zu dem bestehenden hinzugefügt.

So, when the same paragraph appears twice in the original but both are not translated in the exact same way each time, you will get the feeling that a paragraph of the original disappeared. Just kill the new translation. If you prefer to kill the first translation instead when the second one was actually better, remove the second one from where it is and put the first one in the place of the second one.

Wurden im Gegensatz dazu zwei ähnliche, aber verschiedene Absätze exakt identisch übersetzt, bekommen Sie den Eindruck, dass ein Absatz der Übersetzung verschwunden ist. Eine Lösung ist, eine dumme Zeichenkette zum ursprünglichen Absatz hinzuzufügen (wie »Ich bin anders«). Haben Sie keine Angst, diese Dinge verschwinden während der Synchronisation, und wenn der hinzugefügte Text kurz genug ist, wird Gettext ihre Übersetzung zum existierenden Text hinzufügen (und sie dabei als unscharf (»fuzzy«) markieren, was hier allerdings irrelevant ist, da alle Zeichenketten nach der Gettextisierung unscharf sind).

Hoffentlich werden diese Tipps Ihnen bei der Gettextisierungsarbeit und der Erlangung der wertvollen PO-Datei helfen. Sie können jetzt Ihre Datei synchronisieren und mit der Übersetzung beginnen. Bitte beachten Sie, dass bei langen Texten die erste Synchronisierung sehr lange dauert.

Beispielsweise dauerte der erste Lauf von po4a-updatepo der französischen Übersetzung der Perl-Dokumentation (eine 5.5 MB PO-Datei) rund zwei Tage auf einem 1 GHz G5-Computer. Ja, 48 Stunden. Die folgenden dauern aber nur ein paar Dutzend Sekunden auf meinem alten Laptop. Dies kommt daher, dass beim ersten Lauf die meisten Msgids der PO-Datei auf keine der POT-Datei passen. Dies zwingt Gettext, die ähnlichsten mit einem sehr aufwändigen Zeichenketten-Approximier-Algorithmus zu suchen.

HOWTO: Wie wird zusätzlicher Text zu Übersetzungen (wie der Name des Übersetzers) hinzugefügt?

Aufgrund der Gettext-Methode ist dies schwieriger mit Po4a als das vorherige reine Bearbeiten einer neuen Datei neben der ursprünglichen. Allerdings bleibt es dank sogenannter addenda möglich.

Es mag beim Verständnis helfen, Addenda als eine Art von Patches, die auf das übersetzte Dokument nach der Verarbeitung angewandt werden, zu betrachten. Sie unterscheiden sich recht stark von gewöhnlichen Patches (es gibt nur eine Zeile Kontext, der reguläre Ausdrücke von Perl einbetten kann, uns sie können nur neuen Text hinzufügen ohne alten zu löschen), aber die Funktionalität ist die gleiche.

Ihr Ziel ist es, dem Übersetzer zu erlauben, zusätzliche Inhalte zum Dokument hinzuzufügen, der keine Übersetzung aus dem ursprünglichen Dokument ist. Am häufigsten wird dies dazu verwandt, einen Abschnitt über die Übersetzung selbst hinzuzufügen, in der Beitragende aufgeführt sind und dargestellt wird, wie ein Fehler in der Übersetzung gemeldet werden soll.

Ein Addendum muss als separate Datei bereitgestellt werden. Die erste Zeile stellt eine Kopfzeile dar, die anzeigt, wo in dem erstellten Dokument das Addendum eingefügt werden soll. Der Rest der Addendumdatei wird dann unverändert an der angegebenen Position des erstellten Dokuments hinzugefügt.

Die Kopfzeile hat eine recht starre Syntax: Sie muss mit der Zeichenkette PO4A-HEADER: beginnen, gefolgt von einer durch Semikola (;) getrennten Liste von Schlüssel=Wert-Feldern. Leerzeichen SIND wichtig. Beachten Sie, dass Sie das Semikolon-Zeichen (;) nicht im Wert benutzen können (hierbei hilft auch nicht, das Zeichen zu schützen).

Das klingt wieder beängstigend, aber das Beispiel unten sollte Ihnen dabei helfen, herauszufinden, wie die von Ihnen benötigte Kopfzeile geschrieben wird. Um die Diskussion zu beleuchten, nehmen wir an, dass Sie einen Abschnitt »Über diese Übersetzung« nach dem Abschnitt »Über dieses Dokument« hinzufügen möchten.

Dies sind die möglichen Schlüssel in der Kopfzeile:

position (zwingend)
Ein regulärer Ausdruck. Das Addendum wird in der Nähe der Zeile platziert, die auf diesen regulären Ausdruck passt. Beachten Sie, dass wir hier vom übersetzten Dokument reden, nicht dem ursprünglichen. Falls mehr als eine Zeile (oder keine) auf diesen regulären Ausdruck passt, wird das Hinzufügen fehlschlagen. Es ist in der Tat besser, einen Fehler zu melden, als das Addendum an der falschen Stelle hinzuzufügen.

Diese Zeile wird im Folgenden Positionspunkt genannt. Der Punkt, an dem das Addendum hinzugefügt wird, wird Einfügepunkt genannt. Diese zwei Punkte sind in der Nähe voneinander, aber nicht identisch. Wenn Sie beispielsweise einen neuen Abschnitt einfügen wollen, ist es leichter, den Positionspunkt auf den Titel des vorhergehenden Abschnitts zu setzen und Po4a zu erklären, wo der Abschnitt endet (denken Sie daran, dass der Positionspunkt durch einen regulären Ausdruck beschrieben wird, der auf eine eindeutige Zeile passen sollte).

Die Positionierung des Einfügepunkts in Hinblick auf den Positionspunkt wird durch die Felder mode, beginboundary und endboundary gesteuert, die unten beschrieben sind.

In unserem Fall hätten wir: 

     position=<title>Über dieses Dokument</title>
mode (zwingend)
Dies kann entweder die Zeichenkette before (vor) oder after (nach) sein, die die Position des Addendums relativ zum Positionspunkt beschreibt.

Da wir möchten, dass der neue Abschnitt unterhalb desjenigen, auf den der reguläre Ausdruck passt, eingefügt wird: 

     mode=after
beginboundary (nur bei mode=after verwandt, in diesem Fall zwingend)
endboundary (dasselbe)
regulärer Ausdruck, der zum Ende des Abschnitts passt, hinter dem das Addendum folgt

Wenn mode=after ist, ist der Einfügepunkt hinter dem Positionspunkt, aber nicht direkt dahinter! Er wird ans Ende des Abschnitts platziert, der beim Positionspunkt anfängt, d.h. hinter oder vor der Zeile, auf die das Argument ???boundary passt, abhängig davon, ob Sie beginboundary oder endboundary verwandt haben.

In diesem Fall kann ausgewählt werden, das Ende des Abschnitts anzugeben, das beim Hinzufügen von Folgendem passt: 

   endboundary=</Abschnitt>

oder den Anfang des nächsten Abschnitts anzugeben, indem Folgendes angegeben wird: 

   beginboundary=<Abschnitt>

In beiden Fällen wird das Addendum nach dem </Abschnitt> und vor dem <Abschnitt> platziert. Die erste Variante ist besser, da sie auch funktioniert, wenn das Dokument neu organisiert wird.

Es gibt beide Formen, da sich die Formate der Dokumentationen unterscheiden. In einigen davon gibt es eine Möglichkeit, das Ende eines Abschnitts zu markieren (genauso wie im gerade benutzten </Abschnitt>), während einige andere das Ende des Abschnitts nicht explizit markieren (wie in Handbuchseiten). Im erstgenannten Fall möchten Sie keine Abschnittsgrenzen, die ans Ende eines Abschnitts passen, so dass der Einfügepunkt danach kommt. Im letztgenannten Fall möchten Sie erreichen, dass Abschnittsgrenzen an den Anfang des nächsten Abschnitts passen, so dass der Einfügepunkt direkt davor kommt.

Dies kann undurchsichtig erscheinen, aber die nächsten Beispiele werden Sie hoffentlich erleuchten.

Um das bisher benutzte Beispiel zusammenzufassen, können Sie, um einen Abschnitt namens »Über diese Übersetzung« nach dem »Über dieses Dokument« einem SGML-Dokument hinzuzufügen, eine dieser beiden Kopfzeilen verwenden:
 PO4A-HEADER: mode=after; position=Über dieses Dokument; endboundary=</section>
 PO4A-HEADER: mode=after; position=Über dieses Dokument; beginboundary=<section>
Falls Sie etwas hinter den folgenden Nroff-Abschnitt hinzufügen möchten:
  .SH "AUTOREN"

Sie sollten eine Position setzen, die auf diese Zeile passt und ein beginboundary, das auf den Anfang des nächsten Abschnitts (d.h. ^\.SH) passt. Das Addendum wird dann nach dem Positionspunkt und unmittelbar vor der ersten Zeile, die auf das beginboundary passt, hinzugefügt. Das heißt: 

 PO4A-HEADER:mode=after;position=AUTOREN;beginboundary=\.SH
Falls Sie einem Abschnitt etwas hinzufügen möchten (etwa hinter »Copyright Großer Kerl«), statt einen ganzen Abschnitt hinzuzufügen, geben Sie eine Position an, die zu dieser Zeile passt und geben Sie ein beginboundary an, das zu irgendeiner Zeile passt.
 PO4A-HEADER:mode=after;position=Copyright Großer Kerl, 2004;beginboundary=^
Falls Sie am Ende des Dokuments etwas hinzufügen möchten, geben Sie eine Position an, die zu einer Zeile Ihres Dokuments passt (aber nur eine Zeile – Po4a wird nicht fortfahren, wenn sie nicht eindeutig ist) und geben Sie ein endboundary an, das zu nichts passt. Verwenden Sie hier keine einfachen Zeichenketten wie »EOF«, aber nehmen Sie bevorzugt solche, bei denen es unwahrscheinlich ist, dass sie sich in Ihrem Dokument befinden.
 PO4A-HEADER:mode=after;position=<title>Über</title>;beginboundary=FakePo4aBoundary

Denken Sie auf alle Fälle daran, dass dies reguläre Ausdrücke sind. Falls der Ausdruck zum Beispiel auf das Ende eines Nroff-Abschnitts passen soll, der mit der Zeile 

  .fi

endet, benutzen Sie .fi nicht als endboundary, weil es auf »e[rfi]nden« passt, was vermutlich nicht das ist, was sie erwarten. Das korrekte endboundary ist in diesem Fall: ^\.fi$.

Falls das Addendum nicht dort landet, wo Sie es erwartet haben, versuchen Sie das Argument -vv an die Werkzeuge zu übergeben, so dass sie erklären, was sie beim Platzieren des Addendums tun.

Ein ausführlicheres Beispiel

Originaldokument (POD-formatiert): 

 |=head1 BESCHREIBUNG
 |
 |dummy - Ein Platzhalterprogramm
 |
 |=head1 AUTOR
 |
 |ich

Dann wird das folgende Addendum sicherstellen, dass ein Abschnitt (auf Französisch) über den Übersetzer an das Ende der Datei hinzugefügt wird (auf Französisch heißt »ÜBERSETZER« »TRADUCTEUR« und »moi« heißt »ich«). 

 |PO4A-HEADER:mode=after;position=AUTEUR;beginboundary=^=head
 |
 |=head1 TRADUCTEUR
 |
 |moi

Um Ihr Addendum vor dem AUTOR einzufügen, verwenden Sie die folgende Kopfzeile: 

 PO4A-HEADER:mode=after;position=NOM;beginboundary=^=head1

Dies funktioniert, da die nächste auf das beginboundary /^=head1/ passende Zeile nach dem Abschnitt »BESCHREIBUNG« (übersetzt zu »NOM« auf Französisch) diejenige ist, die die Autoren deklariert. Daher wird das Addendum zwischen beide Abschnitte gelegt.

HWOTO: Wie erfolgt alles dies in einem Programmaufruf?

Die Benutzung von Po4a erweist sich für Benutzer als ein wenig fehleranfällig, da Sie zwei unterschiedliche Programme in der richtigen Reihenfolge aufrufen müssen (po4a-updatepo und dann po4a-translate), von denen jedes mehr als drei Argumente benötigt. Zudem war es schwer, mit diesem System nur eine PO-Datei für all Ihre Dokumente zu benutzen, wenn mehr als ein Format benutzt wurde.

Das Programm po4a(1) wurde entworfen, um diese Schwierigkeiten zu lösen. Sobald Ihr Projekt auf dieses System umgestellt wurde, schreiben Sie eine einfache Konfigurationdatei, die erklärt, wo Ihre Übersetzungsdateien (PO und POT) liegen, wo Ihre Originaldokumente liegen, deren Formate und wohin ihre Übersetzungen platziert werden sollen.

Wird po4a(1) für diese Datei aufgerufen, wird sichergestellt, dass die PO-Dateien mit dem Original synchronisiert werden und dass das übersetzte Dokument ordentlich erzeugt wird. Gewiss möchten Sie dieses Programm zwei Mal aufrufen: Einmal vor der Bearbeitung der PO-Datei, um sie zu aktualisieren, und einmal danach, um ein vollständig aktualisiertes übersetztes Dokument zu erhalten. Sie müssen sich aber nur eine Befehlszeile merken.

HOWTO: Wie wird Po4a angepasst?

Po4a-Module haben Optionen (mit der Option -o angegeben), die benutzt werden können, um das Verhalten des Moduls zu ändern.

Es ist außerdem möglich, ein Modul oder neue/abgeleitete/veränderte Module anzupassen, indem ein Modul in lib/Locale/Po4a/ abgelegt und dem durch die PERLLIB- oder PERL5LIB-Umgebung angegebenen Pfad lib hinzugefügt wird. Zum Beispiel: 

   PERLLIB=$PWD/lib po4a --previous po4a/po4a.cfg

Hinweis: Der tatsächliche Name des Lib-Verzeichnisses ist nicht von Bedeutung.

Wie funktioniert es?

Dieses Kapitel gibt Ihnen einen kurzen Überblick über die Interna von Po4a, so dass Sie sich sicherer fühlen, es zu warten und zu verbessern. Es könnte Ihnen auch dabei helfen, zu verstehen, warum es nicht das tut, was Sie erwarten, und wie Sie Ihre Probleme beheben können.

Was steckt dahinter?

Die Po4a-Architektur ist objektorientiert (in Perl. Ist das nicht schön?). Der gemeinsame Vorfahr zu allen Auswertungsklassen nennt sich TransTractor. Dieser merkwürdige Name ist der Tatsache zu verdanken, dass er gleichzeitig für das Übersetzen des Dokuments und das Extrahieren von Zeichenketten zuständig ist.

Förmlicher ausgedrückt nimmt es ein Dokument zum Übersetzen plus eine PO-Datei, die die Übersetzungen enthält, als Eingabe, während es zwei getrennte Ausgaben erzeugt: Eine weitere PO-Datei (die das Ergebnis des Extrahierens übersetzbarer Zeichenketten vom Eingabedokument ist) und einem übersetzen Dokument (mit der gleichen Struktur, wie der aus der Eingabe, bei der aber alle übersetzbaren Zeichenketten durch den Inhalt der Eingabe-PO-Datei ersetzt wurden). Hier eine grafische Darstellung davon: 

 Eingabedokument -- \                             /---> Ausgabedokument
                     \      TransTractor::       /       (übersetzt)
                      +-->--   parse()  --------+
                     /                           \
 Eingabe-PO-Datei---/                             \---> Ausgabe-PO-Datei
                                                          (extrahiert)

Dieser kleine Knochen ist der Kern der Po4a-Architektur. Falls Sie die Eingabe-PO-Datei und das Ausgabedokument weglassen, erhalten Sie po4a-gettextize. Falls Sie beide Eingaben bereitstellen und die Ausgabe-PO-Datei nicht beachten, erhalten Sie po4a-translate.

TransTractor::parse() ist eine virtuelle Funktion, die durch jedes Modul implementiert wird. Hier nun ein kleines Beispiel, um zu zeigen, wie es funktioniert. Es wertet eine Liste von Absätzen aus, von denen jeder mit <p> beginnt. 

  1 sub parse {
  2   PARAGRAPH: while (1) {
  3     $my ($paragraph,$pararef,$line,$lref)=("","","","");
  4     $my $first=1;
  5     while (($line,$lref)=$document->shiftline() && defined($line)) {
  6       if ($line =~ m/<p>/ && !$first--; ) {
  7         $document->unshiftline($line,$lref);
  8
  9         $paragraph =~ s/^<p>//s;
 10         $document->pushline("<p>".$document->translate($paragraph,$pararef));
 11
 12         next PARAGRAPH;
 13       } else {
 14         $paragraph .= $line;
 15         $pararef = $lref unless(length($pararef));
 16       }
 17     }
 18     return; # Keine definierte Zeile erhalten? Ende der Eingabedatei.
 19   }
 20 }

Zeile sechs wird erreicht, wenn <p> zum zweiten Mal gelesen wurde. Dies signalisiert den nächsten Absatz. Daher sollte die gerade erhaltene Zeile zurück in das Originaldokument (Zeile sieben) ablegt und der soweit gebaute Absatz ausgegeben werden. Nachdem das führende <p> in Zeile neun entfernt wurde, wird die Verbindung dieser Markierung mit der Übersetzung des restlichen Absatzes ausgegeben.

Diese translate()-Funktion ist richtig toll. Sie schiebt ihre Argumente in die Ausgabe-PO-Datei (Extrahierung) und gibt ihre Übersetzung so zurück, wie sie in der Eingabe-PO-Datei vorgefunden wurde (Übersetzung). Da sie als Teil des Arguments von pushline() verwandt wird, landet diese Übersetzung im Ausgabedokument.

Ist das nicht toll? Es ist möglich, ein vollständiges Po4a-Modul in weniger als 20 Zeilen zu bauen, wenn das Format einfach genug ist …

Sie können unter Locale::Po4a::TransTractor(3pm) mehr darüber erfahren.

Gettextisierung: Wie funktioniert das?

Die Idee hierbei ist, das Originaldokument und seine Übersetzung zu nehmen und zu sagen, dass die Nte übersetzte Zeichenkette der Übersetzung die Übersetzung der Nten extrahierten Zeichenkette des Originals ist. Damit das funktioniert, müssen sich beide Dateien die exakt gleiche Struktur teilen. Falls die Dateien zum Beispiel die folgende Struktur haben, ist es sehr unwahrscheinlich, dass die vierte Zeichenkette der Übersetzung (vom Typ »Kapitel«) die Übersetzung der vierten Zeichenkette des Originals (vom Typ »Absatz«) ist. 

    Original         Übersetzung
  Kapitel            Kapitel
    Absatz             Absatz
    Absatz             Absatz
    Absatz           Kapitel
  Kapitel              Absatz
    Absatz             Absatz

Dafür werden Po4a-Parser sowohl für das Original als auch für die Übersetzungsdateien zum Extrahieren der PO-Dateien benutzt. Dann wird eine dritte PO-Datei gebaut, deren Zeichenketten von der zweiten als Übersetzung der Zeichenketten der ersten genommen werden. Um zu prüfen, ob die zusammengefügten Zeichenketten tatsächlich die Übersetzung der jeweils anderen sind, sollten Dokumenten-Parser in Po4a Informationen über den syntaktischen Typ der extrahierten Zeichenketten im Dokument setzen (alle existierenden tun das, Ihres sollte das ebenfalls tun). Dann wird diese Information benutzt, um sicherzustellen, dass beide Dokumente die gleiche Syntax haben. Im vorhergehenden Beispiel würde es ermöglichen, festzustellen, dass Zeichenkette vier im einen Fall ein Absatz und im anderen Fall eine Kapitelüberschrift ist und dieses Problem melden.

Theoretisch wäre es möglich, das Problem festzustellen und die Dateien nachher neu zu synchronisieren (genauso wie es diff tut). Aber es ist nicht klar, was mit den wenigen Zeichenketten geschehen soll, bevor sie asynchron werden und es würde manchmal zu schlechten Ergebnissen führen. Dies ist der Grund, weshalb aktuelle Implementierungen nicht versuchen, etwas neu zu synchronisieren und lautstark fehlschlagen, wenn etwas schiefgeht, was manuelle Änderungen an Dateien erfordert, um das Problem zu lösen.

Sogar mit diesen Vorsichtsmaßnahmen können hier sehr einfach Dinge schiefgehen. Daher werden alle Übersetzungen, die auf diese Weise entstehen, als »fuzzy« (unscharf) markiert, um sicherzustellen, dass der Übersetzer sie aufarbeitet und prüft.

Addendum: Wie funktioniert es?

Gut, das hier ist ziemlich leicht. Das übersetzte Dokument wird nicht direkt auf die Platte geschrieben, sondern im Speicher gehalten, bis alle Addenda angewandt wurden. Die hier beteiligten Algorithmen sind eher unkompliziert. Es wird nach einer Zeile gesucht, die zum regulären Positionsausdruck passt und falls mode=before ist, wird das Addendum davor eingefügt. Wenn nicht, wird die nächste zur Abschnittsgrenze passende Zeile gesucht und das Addendum nach dieser Zeile eingefügt, falls es ein endboundary ist oder vor dieser Zeile, falls es ein beginboundary ist.

Häufig gestellte Fragen

Dieses Kapitel gruppiert die häufig gestellten Fragen (»Frequently Asked Questions«). In der Tat könnten derzeit die meisten dieser Fragen wie folgt formuliert werden: »Warum wurde es auf diese Weise entwickelt und nicht auf eine andere?«. Falls Sie glauben, Po4a ist nicht die richtige Lösung zur Übersetzung von Dokumentation, sollten Sie diesen Abschnitt lesen. Falls er Ihre Frage nicht beantwortet, nehmen Sie auf unserer Mailingliste <[email protected]> mit uns (auf Englisch) Kontakt auf. Wir freuen uns über Rückmeldungen.

Warum ist jeder Absatz getrennt zu übersetzen?

Ja, in Po4a wird jeder Absatz getrennt übersetzt (tatsächlich entscheidet dies jedes Modul, aber alle existierenden Module tun dies und Ihres sollte das auch tun). Es gibt zwei Hauptvorteile für dieses Herangehen:
  • Wenn die technischen Teile des Dokuments nicht sichtbar sind, kann der Übersetzer nicht daran herumbasteln. Je weniger Markierungen der Übersetzer vorgesetzt bekommt, um so weniger Fehler kann er machen.
  • Das Zerschneiden des Dokuments hilft beim Isolieren der Änderungen am Originaldokument. Wenn das Original verändert wurde, wird es durch diesen Prozess vereinfacht, herauszufinden, welche Teile der Übersetzung aktualisiert werden müssen.

Sogar mit diesen Vorteilen mögen einige Leute den Gedanken nicht, jeden Absatz einzeln zu übersetzen. Hier einige Antworten auf deren Befürchtungen:

  • Diese Herangehensweise erwies sich im KDE-Projekt als erfolgreich und ermöglichte dort Leuten die größte bekannte Sammlung übersetzter und aktueller Dokumentation.
  • Die Übersetzer können weiterhin den Kontext zum Übersetzen benutzen, da die Zeichenketten in der PO-Datei in der gleichen Reihenfolge wie im Originaldokument stehen. Nacheinander zu übersetzen ist daher eher vergleichbar, ob Sie Po4a verwenden oder nicht. Und auf jeden Fall bleibt die beste Möglichkeit, den Kontext zu erhalten, das Dokument in ein druckbares Format umzuwandeln, da die Fassungen mit Textformatierungen nach Auffassung des Verfassers nicht wirklich lesbar sind.
  • Diese Herangehensweise ist diejenige, die von professionellen Übersetzern angewandt wird. Es stimmt, dass die etwas andere Ziele als Open-Source-Übersetzer verfolgen. Die Wartung ist zum Beispiel meist weniger kritisch für sie, da der Inhalt sich seltener ändert.

Warum wird nicht auf Satzebene (oder darunter) unterteilt?

Professionelle Übersetzerwerkzeuge unterteilen das Dokument machmal auf Satzebene, um die Wiederverwendbarkeit vorhergehender Übersetzungen zu maximieren und ihre Verarbeitung zu beschleunigen. Das Problem ist, dass der gleiche Satz mehrere Übersetzungen haben könnte, je nach Kontext.

Absätze sind definitionsgemäß länger als Sätze. Das wird hoffentlich sicherstellen, dass der gleiche Absatz, wenn er in zwei Dokumenten vorkommt, die gleiche Bedeutung (und Übersetzung) hat, ohne in jedem Fall den Kontext zu beachten.

Unterteilen in kleinere Teile als einen Satz wäre sehr schlecht. Es wäre etwas zu umfangreich, hier zu erklären warum, aber interessierte Leser können beispielsweise die Handbuchseite Locale::Maketext::TPJ13(3pm) lesen (die der Perl-Dokumentation beigefügt ist). Kurz gesagt, hat jede Sprache ihre besonderen syntaktischen Regeln und es gibt keine Möglichkeit, Sätze durch angesammelte Teile von Sätzen für alle existierenden Sprachen zu bilden (oder gar für fünf der zehn meistgesprochenen, oder sogar weniger).

Why not put the original as comment along with translation (or the other way around)?

Auf den ersten Blick schien Gettext nicht für alle Arten von Übersetzungen geeignet zu sein. Es scheint zum Beispiel nicht an Debconf angepasst zu sein, die Schnittstelle, die alle Debian-Pakete für ihr Zusammenspiel mit dem Anwender während der Installation nutzen. In diesem Fall waren die Texte schön klein (ein Dutzend Zeilen für jedes Paket) und es war schwierig, die Übersetzung in eine Spezialdatei abzulegen, da sie vor der Paketinstallation verfügbar sein müssen.

Daher haben sich die Debconf-Entwickler entschieden, eine andere Lösung zu implementieren, bei der Übersetzungen in die gleiche Datei wie das Original platziert werden. Dies ist recht ansprechend. Jemand könnte dies zum Beispiel sogar für XML wollen, dies würde dann ungefähr so aussehen: 

 <section>
  <title lang="de">Mein Titel</title>
  <title lang="fr">Mon titre</title>
  <para>
   <text lang="de">Mein Text.</text>
   <text lang="fr">Mon texte.</text>
  </para>
 </section>

Aber es war dadurch so problematisch, dass nun eine PO-basierte Herangehensweise benutzt wird. Nur das Original kann in der Datei bearbeitet werden und die Übersetzung muss in PO-Dateien erfolgen, die von der Master-Schablone extrahiert wurden (und zur Kompilierungzeit des Pakets zurück platziert werden). Das alte System wurde wegen mehrerer Probleme missbilligt:

  • Verwaltungsprobleme

    Falls mehrere Übersetzer gleichzeitig einen Patch bereitstellen, ist es schwierig, sie zusammenzufügen.

    Wie möchten Sie Änderungen im Original ermitteln, wofür die Übersetzungen aktualisiert werden müssen? Um Diff zu benutzen, müssen sie vermerken, welche Version des Originals Sie übersetzt haben. D.h. Sie benötigen in Ihrer Datei eine PO-Datei. ;)

  • Kodierungsprobleme

    This solution is viable when only European languages are involved, but the introduction of Korean, Russian and/or Arab really complicate the picture. UTF could be a solution, but there are still some problems with it.

    Außerdem sind solche Probleme schwer feststellbar (d.h. nur koreanische Leser werden bemerken, dass die Kodierung von Koreanisch kaputt ist [aufgrund des russischen Übersetzers]).

Gettext löst all diese Probleme gleichzeitig.

Aber Gettext wurde nicht für diese Verwendung entworfen!

Das stimmt, allerdings kam bisher niemand mit einer besseren Lösung. Die einzige bekannte Alternative ist die manuelle Übersetzung mit all den Verwaltungsproblemen.

Was ist mit den anderen Übersetzungswerkzeugen für Dokumentation, die Gettext benutzen?

Soweit mir bekannt, gibt es nur zwei davon:
poxml
Dies ist das durch KDE-Leute entwickelte Werkzeug, um DocBook-XML zu handhaben. Soweit bekannt, war es das erste Programm zum Extrahieren von Zeichenketten aus der Dokumentation in PO-Dateien und um sie nach dem Übersetzen wieder einzuspeisen.

Es kann nur XML und eine spezielle DTD handhaben. Der Verfasser ist ziemlich unglücklich mit der Handhabung von Listen, die in einer großen Msgid enden. Wenn die Liste groß wird, wird es schwerer, das große Stück zu verkleinern.

po-debiandoc
Dieses von Denis Barbier erstellte Programm ist so eine Art Vorläufer des Po4a-SGML-Moduls, wodurch ersteres mehr oder weniger missbilligt ist. Wie der Name sagt, handhabt es nur die DebianDoc-DTD, die mehr oder weniger eine missbilligte DTD ist.

Die Hauptvorteile von Po4a demgegenüber sind die Erleichterung beim Hinzufügen zusätzlichen Inhalts (was dort sogar schlechter ist) und die Fähigkeit, Gettext zu verwenden.

Entwickler über Übersetzung schulen

Wenn Sie versuchen, Dokumentationen oder Programme zu übersetzen, sehen Sie sich drei Arten von Problemen gegenüber; linguistische (nicht jeder spricht zwei Sprachen), technische (der Grund, weshalb Po4a existiert) und beziehungsartige/menschliche. Nicht alle Entwickler verstehen die Notwendigkeit, Dinge zu übersetzen. Sogar wenn sie entgegenkommend sind, könnten Sie ignorieren, wie Übersetzern die Arbeit erleichtert wird. Um dabei zu helfen, bringt Po4a ein Menge Dokumentation mit, auf die Bezug genommen werden kann.

Ein weiterer wichtiger Punkt ist, dass jede übersetzte Datei mit einem kurzen Kommentar beginnt, der angibt, um was für eine Datei es sich handelt und wie sie benutzt wird. Dies sollte den armen Entwicklern helfen, die mit tonneweisen Dateien in unterschiedlichen Sprachen überschüttet werden, die sie kaum sprechen können und hilft ihnen, korrekt damit umzugehen.

In einem Projekt, das Po4a verwendet, sind übersetzte Dateien keine Quelldateien mehr. Da SGML-Dateien üblicherweise Quelldateien sind, ist dies ein einfacher Fehler. Daher haben alle vorhandenen Dateien diese Kopfzeilen: 

 |       *****************************************************
 |       *           GENERATED FILE, DO NOT EDIT             * 
 |       * THIS IS NO SOURCE FILE, BUT RESULT OF COMPILATION *
 |       *****************************************************
 |
 | This file was generated by po4a-translate(1). Do not store it (in VCS,
 | for example), but store the PO file used as source file by po4a-translate. 
 |
 | In fact, consider this as a binary, and the PO file as a regular source file:
 | If the PO gets lost, keeping this translation up-to-date will be harder ;)

Ebenso müssen die normalen PO-Dateien von Gettext nur in das Verzeichnis po/ kopiert werden. Aber dies ist nicht der Fall bei denen, die durch Po4a manipuliert wurden. Das Hauptrisiko hier ist, dass ein Entwickler die existierende Übersetzung seines Programms mit der Übersetzung seiner Dokumentation löscht. (Beides kann nicht in der gleichen PO-Datei gespeichert werden, weil sein Programm seine Übersetzung als mo-Datei installieren muss, während die Dokumentation ihre Übersetzung nur zur Zeit der Kompilierung benötigt.) Daher enthalten die PO-Dateien, die vom Modul po-debiandoc erzeugt wurden folgende Kopfzeilen: 

 #
 #  ADVISES TO DEVELOPERS:
 #    - you do not need to manually edit POT or PO files.
 #    - this file contains the translation of your debconf templates.
 #      Do not replace the translation of your program with this !!
 #        (or your translators will get very upset)
 #
 #  ADVISES TO TRANSLATORS:
 #    If you are not familiar with the PO format, gettext documentation 
 #     is worth reading, especially sections dedicated to this format.
 #    For example, run:
 #         info -n '(gettext)PO Files'
 #         info -n '(gettext)Header Entry'
 #
 #    Some information specific to po-debconf are available at
 #            /usr/share/doc/po-debconf/README-trans
 #         or http://www.debian.org/intl/l10n/po-debconf/README-trans
 #

ZUSAMMENFASSUNG der Vorteile der Gettext-basierten Herangehensweise

  • Die Übersetzungen werden nicht zusammen mit dem Original gespeichert, wodurch es möglich wird, festzustellen, ob Übersetzungen nicht mehr aktuell sind.
  • Die Übersetzungen werden jeweils in separaten Dateien gespeichert, was verhindert, dass sich Übersetzer unterschiedlicher Sprachen, sowohl beim Senden des Patches als auch auf der Ebene des Dateikodierung, stören.
  • Es basiert intern auf Gettext (Po4a bietet aber eine sehr einfache Schnittstelle, so dass Sie die Interna nicht verstehen müssen, um es zu benutzen). Auf diese Art muss das Rad nicht neu erfunden werden und aufgrund ihrer weiten Verbreitung kann davon ausgegangen werden, dass diese Werkzeuge mehr oder weniger fehlerfrei sind.
  • Für den Endanwender hat sich nichts geändert (außer der Tatsache, dass Übersetzungen hoffentlich besser gepflegt werden). Die resultierende Dokumentationsdatei, die verteilt wird, ist exakt dieselbe.
  • Es ist nicht nötig, dass Übersetzer eine neue Dateisyntax lernen und ihr bevorzugter PO-Editor (wie der PO-Modus von Emacs, Lokalize oder Gtranslator) wird gut funktionieren.
  • Gettext bietet eine einfache Möglichkeit, Statistiken darüber zu erhalten, was erledigt ist, was überprüft und aktualisiert werden sollte und was noch zu erledigen ist. Einige Beispiele können unter den folgenden Adressen gefunden werden: 

     - http://kv-53.narod.ru/kaider1.png
 - http://www.debian.org/intl/l10n/

Aber nicht alles ist rosig und diese Herangehensweise hat auch einige Nachteile, die bewältigt werden müssen.

  • Addenda sind … auf den ersten Blick merkwürdig.
  • Sie können den übersetzten Text nicht nach Ihren Präferenzen anpassen, wie das Aufteilen eines Absatzes hier und das Zusammensetzen zwei anderer dort. Aber, falls es in einem gewissen Sinn ein Problem mit dem Original gibt, sollte es sowieso als Fehler gemeldet werden.
  • Sogar mit der einfachen Oberfläche bleibt es ein neues Werkzeug, das Leute lernen müssen.

    Es wäre traumhaft, wenn jemand Po4a in Gtranslator oder Lokalize einbinden würde. Wenn eine SGML-Datei geöffnet wird, werden die Zeichenketten automatisch extrahiert. Wenn sie gespeichert wird, kann eine übersetzte SGML-Datei auf die Platte geschrieben werden. Falls es fertiggebracht wird, ein MS-Word-Modul™ (oder zumindest RTF) zu erstellen, können es sogar professionelle Übersetzer nutzen.

AUTOREN

 Denis Barbier <barbier,linuxfr.org>
 Martin Quinson (mquinson#debian.org)

TRANSLATIONS

LAST GESUCHT