.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "PO4A-GETTEXTIZE 1p" .TH PO4A-GETTEXTIZE 1p "2020-08-19" "Po4a-Werkzeuge" "Po4a-Werkzeuge" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" po4a\-gettextize \- konvertiert eine Originaldatei (und ihre Übersetzungen) in eine PO\-Datei .SH "ÜBERSICHT" .IX Header "ÜBERSICHT" \&\fBpo4a\-gettextize\fR \fB\-f\fR \fIFmt\fR \fB\-m\fR \fIMaster.dok\fR [\fB\-l\fR \fI\s-1XX\s0.dok\fR] \fB\-p\fR \&\fI\s-1XX\s0.po\fR .PP (\fI\s-1XX\s0.po\fR ist die Ausgabe, alles andere sind Eingaben) .SH "BESCHREIBUNG" .IX Header "BESCHREIBUNG" Po4a (\s-1PO\s0 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 \fBpo4a\fR\|(7) für eine schonende Einführung in dieses Projekt. .PP Das Skript \fBpo4a\-gettextize\fR ist dafür verantwortlich, Dokumentationsdateien in PO-Dateien zu konvertieren. Sie benötigen es nur, um Ihr Übersetzungsprojekt mit Po4a einzurichten, niemals danach. .PP Falls Sie ganz von Vorne anfangen, wird \fBpo4a\-gettextize\fR die übersetzbaren Zeichenketten aus der Dokumentation entnehmen und in eine POT-Datei schreiben. Falls Sie eine bereits übersetzte Datei mit dem Schalter \fB\-l\fR bereitstellen, wird \fBpo4a\-gettextize\fR 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. .PP Falls das Master-Dokument Zeichen außerhalb von \s-1ASCII\s0 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 \s-1UTF\-8,\s0 falls kein übersetztes Dokument bereitgestellt wird, verwenden. .SH "OPTIONEN" .IX Header "OPTIONEN" .IP "\fB\-f\fR, \fB\-\-format\fR" 4 .IX Item "-f, --format" Format der Dokumentation, mit der Sie arbeiten möchten. Verwenden Sie die Option \fB\-\-help\-format\fR, um eine Liste der verfügbaren Formate zu erhalten. .IP "\fB\-m\fR, \fB\-\-master\fR" 4 .IX Item "-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. .IP "\fB\-M\fR, \fB\-\-master\-charset\fR" 4 .IX Item "-M, --master-charset" Zeichensatz der Datei, die das zu übersetzende Dokument enthält. .IP "\fB\-l\fR, \fB\-\-localized\fR" 4 .IX Item "-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. .IP "\fB\-L\fR, \fB\-\-localized\-charset\fR" 4 .IX Item "-L, --localized-charset" Zeichensatz der Datei, die das lokalisierte Dokument enthält. .IP "\fB\-p\fR, \fB\-\-po\fR" 4 .IX Item "-p, --po" Datei, in die der Nachrichtenkatalog geschrieben werden soll. Falls keine angegeben ist, wird der Nachrichtenkatalog auf die Standardausgabe geschrieben. .IP "\fB\-o\fR, \fB\-\-option\fR" 4 .IX Item "-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. .IP "\fB\-h\fR, \fB\-\-help\fR" 4 .IX Item "-h, --help" zeigt eine kurze Hilfemeldung an .IP "\fB\-\-help\-format\fR" 4 .IX Item "--help-format" die von Po4a verstandenen Dokumentationsformate auflisten .IP "\fB\-V\fR, \fB\-\-version\fR" 4 .IX Item "-V, --version" zeigt die Version des Skripts und beendet sich .IP "\fB\-v\fR, \fB\-\-verbose\fR" 4 .IX Item "-v, --verbose" Erhöhen der Ausführlichkeit des Programms .IP "\fB\-d\fR, \fB\-\-debug\fR" 4 .IX Item "-d, --debug" Fehlersuch\- (Debug\-)Informationen ausgeben .IP "\fB\-\-msgid\-bugs\-address\fR \fIe\-mail@adresse\fR" 4 .IX Item "--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. .IP "\fB\-\-copyright\-holder\fR \fIZeichenkette\fR" 4 .IX Item "--copyright-holder Zeichenkette" Setzt den Namen des Urhebers in den Kopfzeilen der POT-Datei. Standardmäßig ist dies »Free Software Foundation, Inc.«. .IP "\fB\-\-package\-name\fR \fIZeichenkette\fR" 4 .IX Item "--package-name Zeichenkette" Setzt den Paketnamen für die POT-Kopfzeilen. Standardmäßig »PACKAGE«. .IP "\fB\-\-package\-version\fR \fIZeichenkette\fR" 4 .IX Item "--package-version Zeichenkette" Setzt die Paketversion für die POT-Kopfzeilen. Standardmäßig »VERSION«. .SS "Umwandlung einer händischen Übersetzung nach Po4a" .IX Subsection "Umwandlung einer händischen Übersetzung nach Po4a" \&\fBpo4a\-gettextize\fR 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. .PP 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. .PP .Vb 1 \& Original Übersetzung \& \& Kapitel Kapitel \& Absatz Absatz \& Absatz Absatz \& Absatz Kapitel \& Kapitel Absatz \& Absatz Absatz .Ve .PP \&\fBpo4a\-gettextize\fR 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. .PP 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 \&\fIfuzzy\fR 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. .PP 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 \fImaster.dok\fR, 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. .PP 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. .PP 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. .SS "Tipps und Tricks für den Gettextisierungsprozess" .IX Subsection "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. .PP Wenn dies passiert, besteht die gesamte Aufgabe darin, die blöden Dateistrukturen durch manuelle Bearbeitungen wieder in Einklang zu bringen. \fBpo4a\-gettextize\fR 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 \fIgettextization.failed.po\fR zur weiteren Untersuchung ausgegeben. .PP Hier sind weitere Tricks, die Ihnen bei diesem mühsamen Prozess helfen: .IP "\(bu" 4 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 \fBpo4a\fR\|(7)). .IP "\(bu" 4 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. .IP "\(bu" 4 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. .IP "\(bu" 4 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 ;) .IP "\(bu" 4 Manchmal passen die Inhalte des Absatzes, aber ihr Typ nicht. Dies zu korrigieren hängt stark vom Format ab. In \s-1POD\s0 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 \s-1XML\s0 handeln. .Sp Entsprechend könnten zwei Absätze in \s-1POD\s0 zusammengefasst worden sein, wenn die trennende Zeile Leerzeichen enthält oder wenn es keine Leerzeile zwischen der \fB=item\fR\-Zeile und dem Inhalt des »item«s gibt. .IP "\(bu" 4 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 \fIgettextization.failed.po\fR untersuchen, und beheben Sie das Problem, wo es wirklich ist. .IP "\(bu" 4 In manchen unglücklichen Umständen werden Sie das Gefühl bekommen, dass Po4a Teile des Texts aufgefuttert hat, entweder vom Original oder von der Übersetzung. \fIgettextization.failed.po\fR können Sie entnehmen, dass beide Dateien bis zum Absatz N wie erwartet passten. Dann wird aber ein (nicht erfolgreicher) Versuch unternommen, den Absatz N+1 in der Ursprungsdatei nicht dem Absatz N+1 in der Übersetzung zuzuordnen, wie dies der Fall sein sollte, sondern dem Absatz N+2. So als ob der Absatz N+1, den Sie in dem Dokument gesehen haben, einfach während des Prozesses aus der Datei verschwunden wäre. .Sp 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. .Sp Die vorhergehende Situation taucht also auf, wenn zwei ähnliche aber verschiedene Absätze auf die gleiche Weise übersetzt werden. Dies wird anscheinend einen Absatz der Übersetzung entfernen. Um das Problem zu beheben, reicht es aus, einen der Übersetzungen leicht zu verändern. Sie können auch den zweiten Absatz im Ursprungsdokument entfernen. .Sp Im gegenteiligen Fall, wenn der gleiche Absatz zweimal im Ursprungsdokument auftaucht, aber nicht auf die gleiche Weise an beiden Stellen übersetzt ist, werden Sie das Gefühl bekommen, dass ein Absatz im Ursprungsdokument einfach verschwunden wäre. Kopieren Sie einfach die beste Übersetzung über die andere in dem übersetzten Dokument, um das Problem zu beheben. .IP "\(bu" 4 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. .Sp Beispielsweise benötigte die erste \fBpo4a\-updatepo\fR der Perl-Dokumentation der französischen Übersetzung (5,5 \s-1MB\s0 PO-Datei) rund 48 Stunden (ja, zwei Tage), während nachfolgende Läufe nur noch ein Dutzend Sekunden benötigten. .SH "SIEHE AUCH" .IX Header "SIEHE AUCH" \&\fBpo4a\fR\|(1), \fBpo4a\-normalize\fR\|(1), \fBpo4a\-translate\fR\|(1), \fBpo4a\-updatepo\fR\|(1), \&\fBpo4a\fR\|(7). .SH "AUTOREN" .IX Header "AUTOREN" .Vb 3 \& Denis Barbier \& Nicolas François \& Martin Quinson (mquinson#debian.org) .Ve .SH "URHEBERRECHT UND LIZENZ" .IX Header "URHEBERRECHT UND LIZENZ" Copyright 2002\-2020 \s-1SPI,\s0 Inc. .PP Dieses Programm ist freie Software; Sie können es unter den Bedingungen der \&\s-1GPL\s0 (siehe die Datei \s-1COPYING\s0) vertreiben und/oder verändern.