Ubuntu Manpage: po4a-gettextize - konvertiert eine Originaldatei (und ihre Übersetzungen) in eine PO-Datei

NAME

       po4a-gettextize - konvertiert eine Originaldatei (und ihre Übersetzungen) in eine PO-Datei

ÜBERSICHT

       po4a-gettextize -f fmt -m master.doc -l XX.doc -p XX.po

       (XX.po ist die Ausgabe, alles andere sind Eingaben)

BESCHREIBUNG

Po4a (PO für alles) erleichtert die Pflege von Dokumentationsübersetzungen mittels der klassischen
Gettext-Werkzeuge. Die Hauptfunktionalität von Po4a besteht darin, dass sie die Übersetzung des
Dokumenteninhaltes von der Dokumentenstruktur entkoppelt. Bitte schauen Sie in die Seite po4a(7) für eine
schonende Einführung in dieses Projekt.

Das Skript po4a-gettextize hilft Ihnen bei der Umwandlung Ihrer bereits bestehenden Übersetzung in einen
Po4a-basierten Arbeitsablauf. Dies sollte nur einmalig passieren, um bestehende Übersetzungen zu retten,
während sie in Po4a konvertiert werden, und nicht immer wiederkehrend, nach der Umwandlung Ihres
Projekts. Dieser aufwändige Prozess wird im Detail im nachfolgenden Abschnitt »Umwandlung einer
händischen Übersetzung nach Po4a« beschrieben.

Sie müssen eine Master-Datei (d.h. die Quelldatei auf Englisch) und eine bestehende übersetzte Datei
(z.B. ein vorheriger Übersetzungsversuch ohne Po4a) bereitstellen. Falls Sie mehr als eine Master- oder
Übersetzungsdatei bereitstellen, werden sie nacheinander verwandt, aber es könnte einfacher sein, jede
Seite oder jedes Kapitel separat zu gettextisieren, und dann msgmerge zu verwenden, um alle PO-Dateien
zusammenzuführen. Wie Sie möchten.

Falls das Master-Dokument Zeichen außerhalb von ASCII enthält, wird die neuerstellte PO-Datei
UTF-8-kodiert sei. Falls das Master-Dokument komplett ASCII-kodiert ist, wird die erstellte PO-Datei die
Kodierung des übersetzten Eingabedokuments verwenden.

OPTIONEN

-f, --format
Format der Dokumentation, mit der Sie arbeiten möchten. Verwenden Sie die Option --help-format, um
eine Liste der verfügbaren Formate zu erhalten.

-m, --master
Datei, die das zu übersetzende Master-Dokument enthält. Sie können diese Option mehrfach verwenden,
falls Sie mehrere Dokumente mit Gettext behandeln möchten.

-M, --master-charset
Zeichensatz der Datei, die das zu übersetzende Dokument enthält.

-l, --localized
Datei, die das lokalisierte (übersetzte) Dokument enthält. Falls Sie mehrere Master-Dateien angeben,
könnte es sinnvoll sein, mehrere lokalisierte Dateien durch mehrfache Verwendung dieser Option
anzugeben.

-L, --localized-charset
Zeichensatz der Datei, die das lokalisierte Dokument enthält.

-p, --po
Datei, in die der Nachrichtenkatalog geschrieben werden soll. Falls keine angegeben ist, wird der
Nachrichtenkatalog auf die Standardausgabe geschrieben.

-o, --option
Extraoption(en), die an die Formaterweiterung übergeben werden soll. Lesen Sie die Dokumentation
jeder Erweiterung für weitere Informationen über die gültigen Optionen und ihre Bedeutungen.
Beispielsweise könnten Sie dem AsciiDoc-Auswerter »-o tablecells« übergeben, während der Text-
Auswerter »-o tabs=split« akzeptierte.

-h, --help
zeigt eine kurze Hilfemeldung an

--help-format
die von Po4a verstandenen Dokumentationsformate auflisten

-k --keep-temps
die temporären Master- und vor dem Zusammenführen gebauten lokalisierten POT-Dateien behalten. Dies
kann hilfreich sein, um zu verstehen, warum Dateien nicht mehr synchron sind und damit zu
Gettextisierungs-Problemen führen.

-V, --version
zeigt die Version des Skripts und beendet sich

-v, --verbose
Erhöhen der Ausführlichkeit des Programms

-d, --debug
Fehlersuch- (Debug-)Informationen ausgeben

--msgid-bugs-address e-mail@adresse
Setzt die E-Mail-Adresse, an die Fehler in den Meldungen (msgid) berichtet werden sollen.
Standardmäßig haben die erstellten POT-Dateien keine »Report-Msgid-Bugs-To«-Felder.

--copyright-holder Zeichenkette
Setzt den Namen des Urhebers in den Kopfzeilen der POT-Datei. Standardmäßig ist dies »Free Software
Foundation, Inc.«.

--package-name Zeichenkette
Setzt den Paketnamen für die POT-Kopfzeilen. Standardmäßig »PACKAGE«.

--package-version Zeichenkette
Setzt die Paketversion für die POT-Kopfzeilen. Standardmäßig »VERSION«.

Umwandlung einer händischen Übersetzung nach Po4a
po4a-gettextize synchronisiert die Master- und die übersetzen Dateien um ihre Inhalte in eine PO-Datei
auszulösen. Der Inhalt der Master-Datei ergibt die msgid, während der Inhalt der übersetzten Dateien die
msgstr ergibt. Dieser Prozess ist etwas fragil: es wird angenommen, dass die N-te Zeichenkette der
übersetzten Datei die Übersetzung der N-ten Zeichenkette des Originals ist.

Gettextisierung funktioniert am besten, wenn es Ihnen gelingt, exakt die gleiche Version des
ursprünglichen Dokuments zu finden, das für die Übersetzung verwandt wurde. Selbst dann könnte es
notwendig sein, dass sie mit der Master-Datei als auch den übersetzten Dateien herumbasteln, um ihre
Strukturen anzupassen, falls diese vom ursprünglichen Übersetzer geändert wurden. Daher wird empfohlen,
mit Kopien der Dateien zu arbeiten.

Intern berichtet jedes Po4a-Auswerteprogramm den syntaktischen Typ jeder ausgelesenen Zeichenkette. Damit
werden während der Gettextisierung Desynchronisationen erkannt. Im nachfolgenden Beispiel ist es sehr
unwahrscheinlich, dass die vierte Zeichenkette der Übersetzung (vom Typ »Kapitel«) die Übersetzung der
vierten Zeichenkette des Originals (vom Typ »Absatz«) ist. Es ist wahrscheinlicher, dass ein neuer Absatz
im Ursprungsdokument hinzugefügt oder dass zwei Absätze in der Übersetzung zusammengefasst wurden.

Original Übersetzung

Kapitel Kapitel
Absatz Absatz
Absatz Absatz
Absatz Kapitel
Kapitel Absatz
Absatz Absatz

po4a-gettextize wird jede Strukturdesynchronisation ausführlich diagnostizieren. Wenn dies passiert,
sollten Sie die Dateien manuell bearbeiten, um Pseudo-Absätze hinzuzufügen oder einigen Inhalt hier oder
dort zu entfernen, bis die Struktur beider Dateien genau übereinstimmt. Nachfolgend werden einige Tricks
beschrieben, um dabei das meiste der bestehenden Übersetzung zu retten.

Falls Sie Glück haben und die Dateistrukturen sofort genau passen, ist die Erstellung einer PO-Datei eine
Frage von Sekunden. Andernfalls werden Sie schnell verstehen, warum dieser Prozess einen so scheußlichen
Namen hat :). Selbst dann ist die Gettextisierung oft schneller als die Neuübersetzung von allem. Ich
habe die französische Übersetzung der gesamten Perl-Dokumentation an einem Tage gettextisiert, obwohl es
viele Synchronisierungsprobleme gab. Im Angesicht der Textmenge (2 MB an ursprünglichem Text), hätte der
Neustart der Übersetzung ohne Rettung der alten Übersetzung mehrere Monate an Arbeit bedeutet. Zusätzlich
ist dies der Preis, den Sie zur Nutzung des Komforts von Po4a zahlen müssen. Sobald die Konvertierung
erfolgte, ist die Synchronisation zwischen dem Master-Dokument und den Übersetzungen immer voll
automatisch.

Nach einer erfolgreichen Gettextisierung sollten die erstellten Dokumente manuell auf unerkannte
Abweichungen und nicht gemeldete Fehler überprüft werden, wie dies nachfolgend beschrieben ist.

Tipps und Tricks für den Gettextisierungsprozess

Die Gettextisierung stoppt sofort, wenn eine Desynchronisierung erkannt wurde. Wenn das passiert, müssen
Sie die Dateien soweit notwendig bearbeiten und die Strukturen der Dateien wieder anpassen.
po4a-gettextize erklärt relativ ausführlich, wenn etwas schief gelaufen ist. Es werden die Zeichenketten
berichtet, die nicht zueinander passen, ihre Position im Text und ihr Typ. Desweiteren wird die soweit
generierte PO-Datei in gettextization.failed.po zur weiteren Untersuchung ausgegeben.

Hier sind weitere Tricks, die Ihnen bei diesem mühsamen Prozess helfen und sicherstellen, dass sie das
meiste der vorhergehenden Übersetzung retten:

• Entfernen Sie sämtlichen zusätzlichen Inhalt der Übersetzung, wie beispielsweise Absätze, die den
Übersetzern danken. Sie sollten zu po4a separat als Addenda hinzugefügt werden (siehe po4a(7)).

• Bei der Bearbeitung der Dateien zur Anpassung ihrer Struktur sollten Sie bevorzugt die Übersetzung
bearbeiten. Falls die Änderungen am Original zu umfangreich sind, passen die alten und neuen
Versionen während der ersten Po4a-Ausführung nach der Gettextisierung nicht mehr zusammen (siehe
unten). Jede nicht passende Übersetzung wird sowieso verworfen. Mit diesem Wissen sollten Sie
weiterhin das Originaldokument bearbeiten, falls es andernfalls zu schwer ist, den
Gettextisierungsprozess fortzuführen, selbst falls das bedeutet, dass ein Absatz der Übersetzung
verworfen wird. Das Wichtigste ist, eine erste PO-Datei zum Starten zu bekommen.

• Haben Sie keine Scheu, ursprüngliche Inhalte zu löschen, die in der übersetzten Version nicht
erscheinen würden. Dieser Inhalt wird danach automatisch wieder eingefügt, wenn die PO-Datei mit dem
Dokument synchronisiert wird.

• Sie sollten wahrscheinlich den Ursprungsautor über sämtliche gerechtfertigten Strukturänderungen in
der Übersetzung informieren. Probleme in dem Ursprungsdokument sollten an den Autor berichtet werden.
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 ;) Aber am besten warten Sie
damit, bis Sie die Umwandlung mit po4a fertiggestellt haben, bevor Sie die Ursprungsdateien ändern.

• 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) in XML handeln.

Entsprechend könnten zwei Absätze in POD zusammengefasst worden sein, wenn die trennende Zeile
Leerzeichen enthält oder wenn es keine Leerzeile zwischen der =item-Zeile und dem Inhalt des »item«s
gibt.

• Manchmal erscheinen die Desynchronisationsmeldungen komisch, da die Übersetzung an einen falschen
Ursprungsabsatz angehängt ist. Dies ist ein Zeichen eines vorhergehenden und unerkannten Problems
früher im Prozess. Suchen Sie nach dem tatsächlichen Desynchronisationspunkt, indem Sie die erstellte
Datei gettextization.failed.po untersuchen, und beheben Sie das Problem, wo es wirklich ist.

• Andere Probleme können von doppelten Zeichenketten entweder im Original oder der Übersetzung kommen.
Doppelte Zeichenketten werden in PO-Dateien mit zwei Referenzen zusammengeführt. Dies stellt für den
Gettextisierungs-Algorithmus eine Schwierigkeit dar, der ein einfacher Paarungs-Algorithmus zwischen
den msgids der Master-Dateien als auch den übersetzten Dateien ist. Allerdings wird davon
ausgegangen, dass neuere Versionen von Po4a korrekt mit doppelten Zeichenketten umgehen, so dass Sie
alle verbliebenen Probleme (auf Englisch) berichten sollten, auf die Sie treffen.

Überprüfen von Dateien, die durch po4a-gettextize erstellt wurden
Jede von po4a-gettextize erstellte Datei sollte manuell geprüft werden, selbst wenn sich das Skript
erfolgreich beendet. Sie sollten die PO-Datei überfliegen, um sicherzustellen, dass die msgid und msgstr
tatsächlich zueinander passen. Es ist noch nicht notwendig, sicherzustellen, dass die Übersetzung perfekt
korrekt ist, da alle Einträge sowieso als unscharf (»fuzzy«) markiert sind. Sie müssen nur auf
offensichtliche Übereinstimmungsprobleme hin prüfen, da schlecht passende Übersetzungen in nachfolgenden
Schritten verworfen werden, während Sie sie eigentlich retten wollen.

Glücklicherweise verlangt dieser Schritt nicht, dass Sie die Zielsprache verstehen, sie müssen nur
ähnliche Elemente in jeder msgid und seiner entsprechenden msgstr erkennen. Da ich selbst Französisch,
Englisch und etwas Deutsch spreche, kann ich das mindestens für alle europäischen Sprachen durchführen.
Manchmal gelingt es mir sogar, Zuordnungsprobleme in nicht lateinischen Sprachen zu erkennen, indem ich
auf die Länge der Zeichenketten, Struktur der Phrasen (passt die Anzahl der Satzzeichen?) und andere
Hinweise achte, aber ich bevorzuge, wenn jemand anders diese Sprachen überprüfen kann.

Falls Sie eine falsche Zuordnung erkennen, bearbeiten Sie das Original und die Übersetzungsdateien, falls
po4a-gettextize einen Fehler meldet und versuchen Sie es erneut. Sobald Sie eine geeigente PO-Datei für
Ihre bisherige Übersetzung haben, sichern Sie diese, bis Sie Po4a korrekt zum Funktionieren bekommen.

po4a das erste Mal ausführen
Am einfachsten wird Po4a eingerichtet, indem eine Konfigurationsdatei po4a.conf geschrieben und das
integrierte Po4a-Programm verwandt wird (po4a-updatepo und po4a-translate sind veraltet). Bitte lesen Sie
den Abschnitt »KONFIGURATIONSDATEI« in der Dokumentation po4a(1) für weitere Details.

Wenn po4a das erste Mal ausgeführt wird, wird die aktuelle Version der Master-Dokumente zur
Aktualisierung der PO-Dateien, die die alten, zu rettenden Übersetzungen enthalten, verwandt. Das kann
eine ganze Zeit dauern, da viele der msgids der Gettextisierung nicht genau auf die Elemente der POT-
Datei von den neuesten Master-Dateien passen. Dies zwingt Gettext dazu, den ähnlichsten mittels eines
teueren Ähnlichkeitsalgorithmus für Zeichenketten zu ermitteln. Beispielsweise dauert der erste Lauf über
die französische Übersetzung der Perl-Dokumentation (5,5 MB PO-Datei) mehr als 48 Stunden (ja, zwei
Tage), während nachfolgende Läufe nur Sekunden dauerten.

Verschieben Ihrer Übersetzung in den Produktivbetrieb
Nach diesem ersten Lauf sind die PO-Dateien bereit, von Übersetzern geprüft zu werden. Alle Einträge in
der PO-Datei wurden durch po4a-gettextization als unscharf markiert, wodurch ihre sorgfältige Prüfung vor
der Verwendung erzwungen wird. Übersetzer sollten sich jeden Eintrag vornehmen und nachprüfen, dass die
gerettete Übersetzung tatsächlich auf den aktuellen Ursprungstext passt und bei Bedarf die Übersetzung
aktualisieren und die »fuzzy«-Markierungen entfernen.

Sobald genug »fuzzy«-Markierungen entfernt wurden, wird po4a damit beginnen, die auf der Platte
befindlichen Übersetzungsdateien zu erstellen und Sie können den Übersetzungsarbeitsablauf produktiv
stellen. Einige Projekte finden es nützlich, Weblate zur Koordination zwischen Übersetzern und Betreuern
zu verwenden, allerdings ist das jenseits des Aufgabenbereichs von po4a.

SIEHE AUCH

       po4a(1), po4a-normalize(1), po4a-translate(1), po4a-updatepo(1), po4a(7).

AUTOREN

        Denis Barbier <barbier@linuxfr.org>
        Nicolas François <nicolas.francois@centraliens.net>
        Martin Quinson (mquinson#debian.org)

URHEBERRECHT UND LIZENZ

       Copyright 2002-2022 SPI, Inc.

       Dieses Programm ist freie Software; Sie können es unter den Bedingungen der GPL (siehe die Datei COPYING)
       vertreiben und/oder verändern.

Po4a-Werkzeuge                                     2023-01-03                                PO4A-GETTEXTIZE(1p)