
        *****************************************************
        *           GENERATED FILE, DO NOT EDIT             *
        * THIS IS NO SOURCE FILE, BUT RESULT OF COMPILATION *
        *****************************************************

This file was generated by po4a(7). Do not store it (in VCS, for example),
but store the PO file used as source file by po4a-translate.

In fact, consider this as a binary, and the PO file as a regular .c file:
If the PO get lost, keeping this translation up-to-date will be harder.

=encoding UTF-8

=head1 NAME

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

=head1 ÜBERSICHT

B<po4a-gettextize> B<-f> I<Fmt> B<-m> I<Master.dok> [B<-l> I<XX.dok>] B<-p>
I<XX.po>

(I<XX.po> ist die Ausgabe, alles andere sind Eingaben)

=head1 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 L<po4a(7)> für
eine schonende Einführung in dieses Projekt.

Das Skript B<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 B<po4a-gettextize> die übersetzbaren
Zeichenketten aus der Dokumentation entnehmen und in eine POT-Datei
schreiben. Falls Sie eine bereits übersetzte Datei mit dem Schalter B<-l>
bereitstellen, wird B<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.

=head1 OPTIONEN

=over 4

=item B<-f>, B<--format>

Format der Dokumentation, mit der Sie arbeiten möchten. Verwenden Sie die
Option B<--help-format>, um eine Liste der verfügbaren Formate zu erhalten.

=item B<-m>, B<--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.

=item B<-M>, B<--master-charset>

Zeichensatz der Datei, die das zu übersetzende Dokument enthält.

=item B<-l>, B<--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.

=item B<-L>, B<--localized-charset>

Zeichensatz der Datei, die das lokalisierte Dokument enthält.

=item B<-p>, B<--po>

Datei, in die der Nachrichtenkatalog geschrieben werden soll. Falls keine
angegeben ist, wird der Nachrichtenkatalog auf die Standardausgabe
geschrieben.

=item B<-o>, B<--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.

=item B<-h>, B<--help>

zeigt eine kurze Hilfemeldung an

=item B<--help-format>

die von Po4a verstandenen Dokumentationsformate auflisten

=item B<-V>, B<--version>

zeigt die Version des Skripts und beendet sich

=item B<-v>, B<--verbose>

Erhöhen der Ausführlichkeit des Programms

=item B<-d>, B<--debug>

Fehlersuch- (Debug-)Informationen ausgeben

=item B<--msgid-bugs-address> I<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.

=item B<--copyright-holder> I<Zeichenkette>

Setzt den Namen des Urhebers in den Kopfzeilen der POT-Datei. Standardmäßig
ist dies »Free Software Foundation, Inc.«.

=item B<--package-name> I<Zeichenkette>

Setzt den Paketnamen für die POT-Kopfzeilen. Standardmäßig »PACKAGE«.

=item B<--package-version> I<Zeichenkette>

Setzt die Paketversion für die POT-Kopfzeilen. Standardmäßig »VERSION«.

=back

=head2 Umwandlung einer händischen Übersetzung nach Po4a

B<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

B<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
I<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 F<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.

=head2 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 L<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. B<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 F<gettextization.failed.po> zur weiteren
Untersuchung ausgegeben.

Hier sind weitere Tricks, die Ihnen bei diesem mühsamen Prozess helfen:

=over 

=item 

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 L<po4a(7)>).

=item 

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.

=item 

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.

=item 

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 ;)

=item 

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 B<=item>-Zeile und dem Inhalt des »item«s gibt.

=item 

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

=item 

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. F<gettextization.failed.po> 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.

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.

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.

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.

=item 

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

=back

=head1 SIEHE AUCH

L<po4a(1)>, L<po4a-normalize(1)>, L<po4a-translate(1)>, L<po4a-updatepo(1)>,
L<po4a(7)>.

=head1 AUTOREN

 Denis Barbier <barbier@linuxfr.org>
 Nicolas François <nicolas.francois@centraliens.net>
 Martin Quinson (mquinson#debian.org)

=head1 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.

