PO4A-GETTEXTIZE.1P

Section: User Contributed Perl Documentation (1)
Updated: 2024-06-17
Index Return to Main Contents

NAME

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

ÜBERSICHT

po4a-gettextize -f Fmt -m Master.dok [-l XX.dok] -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 Addendum 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 po4apo4a-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

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