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.