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 ist dafür verantwortlich, Dokumentationsdateien in PO-Dateien
       zu konvertieren. Sie benötigen es nur, um Ihr Übersetzungsprojekt mit Po4a einzurichten,
       niemals danach.

       Falls Sie ganz von Vorne anfangen, wird po4a-gettextize die übersetzbaren Zeichenketten
       aus der Dokumentation entnehmen und in eine POT-Datei schreiben. Falls Sie eine bereits
       übersetzte Datei mit dem Schalter -l bereitstellen, wird po4a-gettextize versuchen, die
       darin enthaltenen Übersetzungen in der erstellten PO-Datei zu verwenden. Dieser Prozess
       bleibt mühsam und händisch, wie dies im Abschnitt »Umwandlung einer händischen Übersetzung
       nach Po4a« weiter unten beschrieben ist.

       Falls das Master-Dokument Zeichen außerhalb von ASCII enthält, wird die neuerstellte PO-
       Datei UTF-8-kodiert sei. Andernfalls (falls das Master-Dokument komplett ASCII-kodiert
       ist) wird die erstellte PO-Datei die Kodierung des übersetzten Eingabedokuments oder
       UTF-8, falls kein übersetztes Dokument bereitgestellt wird, 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

           = item -k --keep-temps

           Keep the temporary master and localized POT files built before merging. This can be
           useful to understand why these files get desynchronized, leading to gettextization
           problems

       -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 wird versuchen, den Inhalt jeder bereitgestellten Übersetzungsdatei
       auszulesen und diesen Inhalt als msgstr in der erstellten PO-Datei zu verwenden. Warnung:
       Dieser Prozess ist sehr fragil: es wird angenommen, dass die N-te Zeichenkette in der
       übersetzten Datei der N-ten Zeichenkette im Original entspricht. Das wird natürlich nur
       funktionieren, wenn beide Dateien über die gleiche Struktur verfügen.

       Intern berichtet jedes Po4a-Auswerteprogramm den syntaktischen Typ jeder ausgelesenen
       Zeichenkette. Damit werden während der Gettextisierung Desynchronisationen erkannt. 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. 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 erkannte Strukturdesynchronisation ausführlich diagnostizieren.
       Wenn dies passiert, sollten Sie die Dateien manuell bearbeiten (das verlangt, dass Sie
       über ein gewisses Verständnis der Zielsprache verfügen). Sie müssen Pseudo-Absätze
       hinzufügen oder einigen Inhalt in einem der beiden (oder beiden) Dokumente(n) entfernen,
       um die berichteten Unstimmigkeiten zu korrigieren, bis die Struktur beider Dokumente
       perfekt passt. Hierzu werden im nächsten Abschnitt einige Tricks gezeigt.

       Selbst wenn das Dokument erfolgreich verarbeitet wurde, sind unerkannte Unterschiede und
       nicht berichtete Fehler weiterhin möglich. Daher werden sämtliche automatisch durch
       po4a-gettextize zugeordnete Übersetzungen mit fuzzy markiert, um eine händische
       Untersuchung durch Menschen zu verlangen. Es muss geprüft werden, ob jede ermittelte
       msgstr genau die Übersetzung der zugehörigen msgid und nicht die der Zeichenkette davor
       oder dahinter ist.

       Wie Sie erkennen können, liegt der Schlüssel darin, dass beide Dokumente die exakt gleiche
       Struktur haben. Daher erfolgt die Gettextisierung am besten mit genau der gleichen Version
       der master.dok, die auch für die Übersetzung verwandt wurde. Die Aktualisierung der Po-
       Datei mit der neusten Master-Datei sollte dann erst erfolgen, wenn die Gettextisierung
       erfolgreich war.

       Falls Sie Glück haben und die Dateistrukturen 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 :). Denken Sie daran, dass diese Routinearbeit der
       Preis ist, den Sie zur Nutzung des Komforts von Po4a danach zahlen müssen. Sobald die
       Konvertierung erfolgte, ist die Synchronisation zwischen dem Master-Dokument und den
       Übersetzungen immer voll automatisch.

       Selbst wenn Sachen schieflaufen ist Gettextisierung schneller als eine komplette
       Neuübersetzung. Ich konnte die existierende französische Übersetzung der gesamten Perl-
       Dokumentation an einem Tag gettextisieren, obwohl die Struktur vieler Dokumente nicht
       synchron war. Das waren mehr als zwei Megabyte an ursprünglichem Text (2 Millionen
       Zeichen). Eine Neuübersetzung von Anfang an hätte mehrere Monate Arbeit benötigt.

   Tipps und Tricks für den Gettextisierungsprozess
       Die Gettextisierung endet, sobald eine Desynchronisierung erkannt wurde. Theoretisch
       sollte es möglich sein, die Gettextisierung später im Dokument wieder zu synchronisieren,
       z.B. mit dem gleichen Algorithmus, den auch das Hilfswerkzeug diff(1) verwendet.
       Allerdings wäre eine händische Intervention weiterhin notwendig, um die Elemente, die
       nicht automatisch zugeordnet werden konnten, manuell zuzuordnen. Dies erklärt, warum
       (noch?) keine automatische Resynchronisation implementiert wurde.

       Wenn dies passiert, besteht die gesamte Aufgabe darin, die blöden Dateistrukturen durch
       manuelle Bearbeitungen wieder in Einklang zu bringen. po4a-gettextize erklärt relativ
       ausführlich, was falsch lief, wenn dies passiert. Es werden die Zeichenketten berichtet,
       die nicht zueinander passen, ihre Position im Text und ihre 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:

       •   Entfernen Sie sämtlichen zusätzlichen Inhalt der Übersetzung, wie beispielsweise
           Absätze, die den Übersetzern danken. Sie können diese in Po4a anschließend wieder
           mittels Addenda hinzufügen (siehe po4a(7)).

       •   Falls Sie die Dateien bearbeiten müssen, um ihre Strukturen abzugleichen, sollten Sie
           bevorzugt die Übersetzung bearbeiten. Falls die Änderungen am Original zu umfangreich
           sind, passen die alten und neuen Versionen während der PO-Aktualisierung nicht mehr
           zusammen und die entsprechende Überestzung wird trotzdem verworfen. Haben Sie aber
           keine Scheu, falls notwendig auch das Ursprungsdokument zu bearbeiten: 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 ;)

       •   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 gettextization.failed.po untersuchen,
           und beheben Sie das Problem, wo es wirklich ist.

       •   In some case, po4a adds a space at the end of either the original or the translated
           strings. This is because every string must be deduplicated during the gettextize
           process. Imagine that a string appearing several times unmodified in the original, but
           is translated in differing way, or that different paragraphs are translated in the
           exact same way.

           Without deduplication, such case would break the gettexization algorithm, as it is a
           simple one to one pairing between the msgids of both the master and the localized
           files. Since one of the PO files would miss an entry (that would be reported as
           duplicate, with two references), the pairing would fail.

           Since po4a uses the entry type ("title" or "plain paragraph", etc) to detect whether
           the parsing streams got desynchronized, similar issues could occur if two identical
           entries (same content but differing type) of the master file are translated in the
           exact same way in the localized file. po4a would detect a fake desyncronization in
           such case.

           In most cases, the extra space added by po4a to deduplicate the strings has no impact
           on the formatting. Strings are fuzzied anyway, and msgmerge will probably match the
           strings accordingly afterward.

       •   Abschließend sei bemerkt, dass Sie nicht zu überrascht sein sollten, wenn die erste
           Synchronisation Ihrer PO-Datei sehr lange dauert. Dies kommt daher, dass die meisten
           msgid der aus der Gettextisierung entstehenden PO-Datei nicht genau auf ein Element
           der POT-Datei, die aus der neuen Master-Datei gebaut wurde, passen. Dies zwingt
           Gettext, mit einem aufwändigen Zeichenketten-Umgebungssuche-Algorithmus nach dem
           ähnlichsten zu suchen.

           Beispielsweise benötigte die erste po4a-updatepo der Perl-Dokumentation der
           französischen Übersetzung (5,5 MB PO-Datei) rund 48 Stunden (ja, zwei Tage), während
           nachfolgende Läufe nur noch ein Dutzend Sekunden benötigten.

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-2020 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.