.\" -*- mode: troff; coding: utf-8 -*- .\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) .\" .\" 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 .. .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .ie n \{\ . ds C` "" . ds C' "" 'br\} .el\{\ . 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 1" .TH PO4A-GETTEXTIZE.1P 1 2024-06-26 "perl v5.38.2" "User Contributed Perl Documentation" .\" 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 \fIXX.dok\fR] \fB\-p\fR \fIXX.po\fR .PP (\fIXX.po\fR ist die Ausgabe, alles andere sind Eingaben) .SH BESCHREIBUNG .IX Header "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 \fBpo4a\fR\|(7) für eine schonende Einführung in dieses Projekt. .PP Das Skript \fBpo4a\-gettextize\fR 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. .PP 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 \fBmsgmerge\fR zu verwenden, um alle PO-Dateien zusammenzuführen. Wie Sie möchten. .PP 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. .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\-k\fR \fB\-\-keep\-temps\fR" 4 .IX Item "-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. .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 synchronisiert die Master\- und die übersetzen Dateien um ihre Inhalte in eine PO-Datei auszulösen. Der Inhalt der Master-Datei ergibt die \fBmsgid\fR, während der Inhalt der übersetzten Dateien die \fBmsgstr\fR 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. .PP 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. .PP 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. .PP .Vb 1 \& Original Übersetzung \& \& Kapitel Kapitel \& Absatz Absatz \& Absatz Absatz \& Absatz Kapitel \& Kapitel Absatz \& Absatz Absatz .Ve .PP \&\fBpo4a\-gettextize\fR 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. .PP 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 \fIviele\fR 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. .PP Nach einer erfolgreichen Gettextisierung sollten die erstellten Dokumente manuell auf unerkannte Abweichungen und nicht gemeldete Fehler überprüft werden, wie dies nachfolgend beschrieben ist. .PP \fITipps und Tricks für den Gettextisierungsprozess\fR .IX Subsection "Tipps und Tricks für den Gettextisierungsprozess" .PP 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. \fBpo4a\-gettextize\fR 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 \fIgettextization.failed.po\fR zur weiteren Untersuchung ausgegeben. .PP Hier sind weitere Tricks, die Ihnen bei diesem mühsamen Prozess helfen und sicherstellen, dass sie das meiste der vorhergehenden Übersetzung retten: .IP \(bu 4 Entfernen Sie sämtlichen zusätzlichen Inhalt der Übersetzung, wie beispielsweise Absätze, die den Übersetzern danken. Sie sollten zu \fBpo4a\fR separat als Addendum hinzugefügt werden (siehe \fBpo4a\fR\|(7)). .IP \(bu 4 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. .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 ;) Aber am besten warten Sie damit, bis Sie die Umwandlung mit \fBpo4a\fR fertiggestellt haben, bevor Sie die Ursprungsdateien ändern. .IP \(bu 4 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. .Sp 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 \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 die erstellte Datei \fIgettextization.failed.po\fR untersuchen, und beheben Sie das Problem, wo es wirklich ist. .IP \(bu 4 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 \fBmsgid\fRs 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. .SS "Überprüfen von Dateien, die durch \fBpo4a\-gettextize\fP erstellt wurden" .IX Subsection "Überprüfen von Dateien, die durch po4a-gettextize erstellt wurden" Jede von \fBpo4a\-gettextize\fR erstellte Datei sollte manuell geprüft werden, selbst wenn sich das Skript erfolgreich beendet. Sie sollten die PO-Datei überfliegen, um sicherzustellen, dass die \fBmsgid\fR und \fBmsgstr\fR 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. .PP Glücklicherweise verlangt dieser Schritt nicht, dass Sie die Zielsprache verstehen, sie müssen nur ähnliche Elemente in jeder \fBmsgid\fR und seiner entsprechenden \fBmsgstr\fR 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. .PP Falls Sie eine falsche Zuordnung erkennen, bearbeiten Sie das Original und die Übersetzungsdateien, falls \fBpo4a\-gettextize\fR 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. .SS "\fBpo4a\fP das erste Mal ausführen" .IX Subsection "po4a das erste Mal ausführen" Am einfachsten wird Po4a eingerichtet, indem eine Konfigurationsdatei \fBpo4a.conf\fR geschrieben und das integrierte \fBpo4apo4a\fR\-Programm verwandt wird (\fBpo4a\-updatepo\fR und \fBpo4a\-translate\fR sind veraltet). Bitte lesen Sie den Abschnitt »KONFIGURATIONSDATEI« in der Dokumentation \fBpo4a\fR\|(1) für weitere Details. .PP Wenn \fBpo4a\fR 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 \fBmsgid\fRs 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. .SS "Verschieben Ihrer Übersetzung in den Produktivbetrieb" .IX Subsection "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 \fBpo4a\-gettextization\fR 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. .PP Sobald genug »fuzzy«\-Markierungen entfernt wurden, wird \fBpo4a\fR 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 \fBpo4a\fR. .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\-2023 SPI, Inc. .PP 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.