
        *****************************************************
        *           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 - PO-Dateien und übersetzte Dokumente auf einen Rutsch aktualisieren

=head1 ÜBERSICHT

B<po4a> [I<Optionen>] I<Konfig_Datei>

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

Bei der Ausführung wertet B<po4a> alle in seiner Konfigurationsdatei festgelegten Dokumentationsdateien aus. Es aktualisiert die PO-Dateien (die die Übersetzung enthalten), um alle Änderungen an der Dokumentation abzubilden, und erstellt die übersetzte Dokumentation, indem der Inhalt der Übersetzung (wie er sich in den PO-Dateien befindet) in die Struktur des ursprünglichen Master-Dokumentes eingespeist wird.

Zuerst enthalten die PO-Dateien nur die zu übersetzenden Zeichenketten aus der ursprünglichen Dokumentation. Dieses Dateiformat erlaubt es den Übersetzern, manuell eine Übersetzung für jeden Absatz, der von B<po4a> herausgelöst wurde, bereitzustellen. Falls die Dokumentation nach der Übersetzung verändert wird, markiert B<po4a> die entsprechende Übersetzung als »fuzzy« (unscharf) in der PO-Datei. Damit wird um eine manuelle Begutachtung durch die Übersetzer gebeten. Die Übersetzer können auch ein sogenanntes »addendum« bereitstellen, das zusätzliche Inhalte bereitstellt, in denen beispielsweise angegeben wird, wer die Übersetzung angefertigt hat und wie Fehler berichtet werden sollen.

    Masterdokumente  ---+---->-------->------>------>----+
 (Dokumentenerstellung) |                                |
                        V        (Po4a-Ausführung)       >-----+--> übersetzte
                        |                                |     |    Dokumente
 bestehende PO-Dateien ->---> aktualisierte PO-Dateien >-+     |
         ^                               |               |
         |                               V               |
         +----------<----------<---------+               ^
          (manueller Übersetzungsprozess)                |
                                                         |
 Addendum -->--------------------------------------------+

Der Arbeitsablauf in B<po4a> ist asynchron, passend für Open-Source-Projekte. Der Dokumentenersteller schreibt das Master-Dokument in seiner eigenen Geschwindigkeit. Die Übersetzer prüfen und aktualisieren die Übersetzungen in den PO-Dateien. Die Betreuer führen bei Bedarf B<po4a> erneut aus, um alle Änderungen an der Ursprungsdokumentation in den PO-Dateien wiederzugeben und aktualisierte Dokumentenübersetzungen bereitzustellen, indem sie die neusten Übersetzungen in die neuste Dokumentenstruktur einspeisen.

Standardmäßig wird ein angegebenes Dokument erstellt, wenn mindestens 80% seines Inhalts übersetzt ist. Der nicht übersetzte Text wird in der Ursprungssprache behalten. Die erstellte Dokumentation mischt daher die Sprachen, falls die Übersetzung nicht vollständig ist. Sie können den Schwellwert von 80% mit der oben beschriebenen Option I<--keep> ändern. Beachten Sie aber, dass das Verwerfen von Übersetzungen, sobald sie nicht mehr zu 100% erfüllt sind, für die Übersetzer entmutigend sein kann, deren Arbeit fast nie dem Benutzer angezeigt wird, während das Zeigen von »Übersetzungen«, die zu unvollständig sind, bei Endbenutzer zu Verdruß führen kann.

Das Speichern der übersetzten Dokumentationsdateien in dem Versionssteuerungssystem ist wahrscheinlich eine schlechte Idee, da diese Dateien automatisch erstellt werden. Die wertvollen Dateien sind die PO-Dateien, die die harte Arbeit ihrer Mitübersetzer enthalten. Auch finden es manche Leute einfacher, mit den Übersetzern durch eine Online-Plattform wie S<weblate> zu interagieren, aber dieses ist natürlich vollständig optional.

=head2 Schnellstartanleitung

Nehmen wir an, dass Sie ein Programm namens B<foo> betreuen, das eine auf englisch geschriebene Handbuchseite F<man/foo.1> enthält. (Englisch wird in den meisten Open-Source-Projekten als Brückensprache verwandt, aber B<po4a> kann in jeder Sprachkombination eingesetzt werden). Vor einiger Zeit stellte jemand eine deutsche Übersetzung mit dem Namen F<man/foo.de.1> bereit und verschwand. Dies ist ein Problem, da Sie gerade einen Fehlerbericht bekommen haben, der Sie informiert, dass Ihre Dokumentation eine grob irreführende Information enthält, die in allen Sprachen korrigiert werden muss. Sie sprechen aber kein Deutsch, so dass Sie nur das Ursprungsdokument korrigieren können, nicht die Übersetzung. Und jetzt möchte ein anderer Beitragender eine japanische Übersetzung erstellen und Sie sprechen auch kein japanisch.

Jetzt ist es Zeit, Ihre Dokumentation nach B<po4a> umzuwandeln, um Ihre Dokumentations-Wartungs-Albträume zu lösen. Sie möchten Ihre Dokumentation je nach Bedarf ändern können, Sie möchten die Arbeit ihrer Mitübersetzer erleichtern und Sie möchten sicherstellen, dass Ihre Benutzer niemals veraltete und daher irreführende Dokumentation sehen.

Die Umwandlung besteht aus zwei Schritten: Einrichtung der Po4a-Infrastruktur und der Umwandlung der bisherigen deutschen Übersetzung, um die bisherige Arbeit zu retten. Letzterer Teil erfolgt mittels S<po4a-gettextize> wie folgt beschrieben. Wie im Detail in L<po4a-gettextize(1)> dargestellt, ist der Prozess selten vollautomatisch, aber wenn er einmal erledigt ist, dann enthält die Datei B<de.po> die deutsche Übersetzung, die in Ihren Po4a-Arbeitsablauf integriert werden kann.

  po4a-gettextize --format man --master foo.1 --localized foo.de.1 --po de.po

Lassen Sie uns nun Po4a konfigurieren. Bei geeigneter Anordung der Dateien, könnte die Konfigurationsdatei so einfach wie folgende sein:

 [po_directory] man/po4a/

 [type: man] man/foo.1 $lang:man/translated/foo.$lang.1

Sie legt fest, dass alle PO-Dateien (die die Arbeit der Übersetzer enthalten) im Verzeichnis F<man/po4a/> liegen und dass Sie eine Master-Datei F<man/foo.1> haben. Falls Sie mehrere Master-Dateien haben, hätten Sie mehrere Zeilen ähnlich der zweiten Zeile. Jeder dieser Zeilen gibt auch an, wohin die entsprechenden Übersetzungsdateien geschrieben werden sollen. Hier ist die deutsche Übersetzung von F<man/foo.1> in F<man/translated/foo.de.1>.

Das letzte, was wir zum Abschluss der Konfiguration von B<po4a> benötigen, ist eine POT-Datei, die das Vorlagenmaterial enthält, das zum Starten einer neuen Übersetzung verwandt werden soll. Erstellen Sie einfach eine leere Datei mit der Endung S<.pot> im festgelegten S<po_directory> (z.B. F<man/po4a/foo.pot>) und B<po4a> wird sie mit dem erwarteten Inhalt ausfüllen.

Hier ist eine kurze Wiederholung dieser Installation:

  ├── man/
  │   ├── foo.1        <- Die ursprüngliche Handbuchseite in englischer Sprache
  │   ├── po4a/
  │   │   ├── de.po    <- Die deutsche PO-Übersetzung aus der Gettextisierung
  │   │   └── foo.pot  <- Die POT-Vorlage für zukünftige Übersetzung (am Anfang leer)
  │   └── translated/  <- Verzeichnis, in das die Übersetzungen hin erzeugt werden
  └── po4a.cfg         <- Die Konfigurationsdatei

Sobald die Installation erfolgt ist, wird B<po4a> Ihre Dokumentation auswerten, die POT-Vorlagendatei aktualisieren und diese zur Aktualisierung der PO-Übersetzungsdateien und zur Aktualisierung der Dokument-Übersetzungsdateien verwenden. Alles in einem Befehl:

        po4a --verbose po4a.cfg

Das wars. B<po4a> ist jetzt vollständig konfiguriert. Sobald Sie die Fehler in F<man/foo.1> behoben haben, wird der betroffene Absatz in der deutschen Übersetzung durch den korrigierten Absatz auf Englisch ersetzt. Das Mischen der Sprachen ist nicht optimal, aber es ist die einzige Möglichkeit, Fehler in Übersetzungen zu beheben, die Sie nicht mal verstehen und sicherzustellen, dass der den Benutzern dargestellte Inhalt niemals irreführend ist. Das Aktualisieren der deutschen Übersetzung ist in der entsprechenden PO-Datei auch viel leichter, so dass der Sprachen-Mix nicht sehr lange vorliegen könnte. Wenn dann schließlich die japanische Übersetzerin eine neue Übersetzung beitragen will, sollte sie S<foo.pot> in S<ja.po> umbenennen und die Übersetzung vervollständigen. Sobald Sie diese Datei haben, legen Sie diese einfach in F<man/po4a/po/> ab. Wenn Sie dann B<po4a> wieder ausführen, erscheint einfach eine übersetzte Datei als F<man/translated/foo.ja.1> (vorausgesetzt, dass genug Inhalt übersetzt ist).

=head1 OPTIONEN

=over 4

=item B<-k>, B<--keep>

Minimaler Schwellwert in Prozent, ab der die übersetzte Datei erhalten (d.h. geschrieben) wird, standardmäßig 80. D.h., standardmäßig müssen Dateien zu 80% übersetzt sein, um auf Platte geschrieben zu werden.

=item B<-w>, B<--width>

Spalte, an der die entstehende Datei umgebrochen werden soll, falls das Format dies unterstützt (Vorgabe: 76)

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

zeigt eine kurze Hilfemeldung an

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

Zeichensatz der Dateien, die die zu übersetzenden Dokumente enthalten. Beachten Sie, dass alle Master-Dokumente im gleichen Zeichensatz vorliegen müssen.

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

Zeichensatz der Dateien, die die lokalisierten Dokumente enthalten. Beachten Sie, dass alle übersetzte Dateien den gleichen Zeichensatz verwenden werden.

=item B<-A>, B<--addendum-charset>

Zeichensatz der Addenda. Beachten Sie, dass alle Addenda im gleichen Zeichensatz vorliegen sollten.

=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<-q>, B<--quiet>

Verringern der Ausführlichkeit des Programms

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

Fehlersuch- (Debug-)Informationen ausgeben

=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<-f>, B<--force>

immer die POT- und PO-Dateien erstellen, selbst wenn B<po4a> dies nicht für notwendig betrachtet

Das Standardverhalten (wenn B<--force> nicht angegeben ist) ist wie folgt:

=over 

Falls die POT-Datei bereits existiert, wird sie neu erstellt, falls ein Master-Dokument oder die Konfigurationsdatei neuer ist (außer B<--no-update> ist angegeben). Die POT-Datei wird auch in ein temporäres Dokument geschrieben und B<po4a> überprüft, dass die Änderungen wirklich benötigt werden.

Eine Übersetzung wird auch nur neu erstellt, falls das Master-Dokument, die PO-Datei, einer ihrer Addenda oder die Konfigurationsdatei neuer ist. Um zu vermeiden, dass die Erstellung von Übersetzungen, die die Schwellwertbarriere nicht erreichen, versucht wird (siehe B<--keep>), kann eine Datei mit der Erweiterung F<.po4a-stamp> erstellt werden (siehe B<--stamp>).

=back

Falls ein Master-Dokument Dateien einbindet, soillten Sie den Schalter B<--force> verwenden, da der Änderungszeitpunkt dieser eingebundenen Dateien nicht mit betrachtet wird.

Die PO-Dateien werden basierend auf der POT-Datei mittels B<msgmerge -U> neu erstellt.

=item B<--stamp>

Sorgt dafür, dass B<po4a> Stempeldateien erstellt, wenn eine Übersetzung nicht erstellt wurde, da sie den Schwellwert nicht erreichte. Diese Stempeldateien werden entsprechend des erwarteten übersetzten Dokuments, mit der Erweiterung F<.po4a-stamp>, benannt.

Hinweis: Dies aktiviert nur die Erstellung der F<.po4a-stamp>-Dateien. Die Stempeldateien werden immer benutzt, falls sie existieren, und sie werden mit B<--rm-translations> oder wenn die Datei schließlich übersetzt ist entfernt.

=item B<--no-translations>

die übersetzten Dokumente nicht erstellen, nur die POT- und PO-Dateien aktualisieren

=item B<--no-update>

die POT- und PO-Dateien nicht ändern, nur die Übersetzung darf aktualisiert werden.

=item B<--keep-translations>

behält die existierenden Übersetzungsdateien, selbst falls die Übersetzung nicht die durch B<--keep> festgelegte Schwelle erreicht. Dies wird keine Übersetzungsdateien mit wenigen Inhalten erstellen, sondern bestehende Dateien sichern, deren Übersetzungen aufgrund von Änderungen an den Master-Dateien verfallen.

WARNUNG: Dieser Schalter ändert das Verhalten von Po4a ziemlich drastisch: Ihre übersetzten Dateien werden überhaupt nicht aktualisiert, bis die Übersetzung verbessert wird. Verwenden Sie diesen Schalter nur, falls Sie die Auslieferung von veralteter Dokumentation gegenüber einer akuraten nicht übersetzten Dokumentation bevorzugen.

=item B<--rm-translations>

entfernt die übersetzten Dateien (impliziert B<--no-translations>)

=item B<--no-backups>

Seit Version 0.41 macht dieser Schalter nichts und könnte daher in zukünftigen Veröffentlichungen entfernt werden.

=item B<--rm-backups>

Seit Version 0.41 macht dieser Schalter nichts und könnte daher in zukünftigen Veröffentlichungen entfernt werden.

=item B<--translate-only> I<übersetzte-Datei>

Nur die angegebene Datei übersetzen. Das kann nützlich sein, um die Verarbeitung zu beschleunigen, falls die Konfigurationsdatei eine Reihe Dateien enthält. Beachten Sie, dass diese Optione die PO- und POT-Dateien nicht aktualisiert. Diese Option kann mehrfach angewandt werden.

=item B<--variable> I<Var>B<=>I<Wert>

Definiert eine Variable, die in der B<po4a>-Konfigurationsdatei expandiert wird. Jedes Vorkommen von I<$(Var)> wird durch I<Wert> ersetzt. Diese Option kann mehrfach verwandt werden.

=item B<--srcdir> I<QUELLVERZ>

setzt das Basisverzeichnis für alle Eingabedokumente, die in der Konfigurationsdatei B<po4a> angegeben sind

Falls sowohl I<ZIELVERZ> als auch I<QUELLVERZ> festgelegt sind, wird in den folgenden Verzeichnissen, in dieser Reihenfolge, nach Eingabedateien gesucht: I<ZIELVERZ>, das aktuelle Verzeichnis und I<QUELLVERZ>. Ausgabedateien werden in das I<ZIELVERZ>, falls angegeben, oder in das aktuelle Verzeichnis geschrieben.

=item B<--destdir> I<ZIELVERZ>

setzt das Basisverzeichnis für alle in der B<po4a>-Konfigurationsdatei angegebenen Dokumente (siehe B<--srcdir> weiter oben).

=back

=head2 Optionen, die die POT-Kopfzeilen verändern

=over 4

=item B<--porefs> I<Typ>

Gibt das Referenzformat an. Das Argument I<Typ> kann entweder B<never> (keine Referenz erzeugen), B<file> (nur die Datei ohne Zeilenzahlen festlegen), B<counter> (alle Zeilennummern durch einen ansteigenden Zähler ersetzen) oder B<full> (komplette Referenzen einbinden) sein. Die Vorgabe ist »full«.

=item B<--wrap-po> B<no>|B<newlines>|I<Zahl> (Vorgabe: 76)

Legt fest, wie die PO-Datei umgebrochen werden soll. Dies ermöglicht die Auswahl zwischen Dateien, die schön umgebrochen sind aber zu GIT-Konflikten führen können oder Dateien, die leichter automatisch handzuhaben, aber schwerer für Menschen zu lesen sind.

Aus kosmetischen Gründen hat die Gettext-Programmsammlung PO-Dateien in der 77.Spalte umgebrochen. Diese Option legt das Verhalten von Po4a fest. Falls auf einen numerischen Wert gesetzt, wird Po4a die PO-Datei nach dieser Spalte und nach Zeilenumbrüchen im Inhalt umbrechen. Falls auf B<newlines> gesetzt, wird Po4a die msgid und msgstr nur nach Zeilenumbrüchen im Inhalt auftrennen. Falls auf B<no> gesetzt, wird Po4a die PO-Datei überhaupt nicht umbrechen. Die Referenzkommentare werden durch die von Po4a intern verwandten Gettext-Werkzeuge immer umgebrochen.

Beachten Sie, dass diese Option keine Auswirkung darauf hat, wie msgid und msgstr umgebrochen werden, d.h. wie Zeilenumbrüche zu dem Inhalt dieser Zeilen hinzugefügt werden.

=item B<--master-language>

Sprache der Quelldateien, die die zu übersetzenden Dokumente enthalten. Beachten Sie, dass alle Master-Dokumente in der gleichen Sprache vorliegen müssen.

=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 Optionen, um PO-Dateien zu verändern

=over 4

=item B<--msgmerge-opt> I<Optionen>

Extraoptionen für B<msgmerge>(1).

Hinweis: B<$lang> wird zur aktuellen Sprache erweitert.

=item B<--no-previous>

Diese Option entfernt B<--previous> aus den an B<msgmerge> übergebenen Optionen. Dies ist notwendig, um Version von B<gettext>-Versionen vor 0.16 zu unterstützen.

=item B<--previous>

Diese Option fügt B<--previous> zu den an B<msgmerge> übergebenen Optionen hinzu. Dies benötigt B<gettext> 0.16 oder neuer und ist standardmäßig aktiviert.

=back

=head1 KONFIGURATIONSDATEI

Po4a erwartet eine Konfigurationsdatei als Argument. Diese Datei muss die folgenden Elemente enthalten:

=over 

=item 

Den Pfad zu den PO-Dateien und der Liste der in dem Projekt existierenden Sprachen.

=item 

Optional, einige globale Optionen und sogenannte Konfigurationsaliase, die als Vorlagen zur Konfiguration individueller Master-Dateien verwandt werden.

=item 

Die Liste der zu übersetzenden Master-Dateien, zusammen mit speziellen Parametern.

=back

Alle Zeilen enthalten einen Befehl zwischen eckigen Klammern, gefolgt von seinen Parametern. Kommentare beginnen mit dem Zeichen »#« und gehen bis zum Zeilenende. Sie können das Zeilenende maskieren, um einen Kommentar über mehrere Zeilen auszubreiten.

In dieser Seite werden einige vollständige Beispiele vorgestellt, andere Beispiele können im Verzeichnis C<t/cfg> der Quelldistribution gefunden werden.

=head2 Finden der PO- und POT-Dateien

Die einfachste Lösung ist die explizite Angabe der Pfade zu den POT- und PO-Dateien, wie folgt:

 [po4a_paths] man/po/project.pot de:man/po/de.po fr:man/po/fr.po

Die speziellen Pfade zu der POT-Datei zuerst, und dann die Pfade zu den deutschen und französischen PO-Dateien.

Die gleiche Information kann wie folgt geschrieben werden, um das Risko von Kopier-/Einfügefehlern zu vermeiden:

 [po4a_langs] fr de
 [po4a_paths] man/po/project.pot $lang:man/po/$lang.po

Die Komponente C<$lang> wird automatisch mittels der bereitgestellten Sprachliste ausgegeben, wodurch das Risiko von Kopieren-/Einfüge-Fehlern reduziert wird, wenn eine neue Sprache hinzugefügt wird.

Die gleiche Information kann noch kompakter geschrieben werden, indem Sie nur die Pfade zu dem Verzeichnis angeben, das Ihr Übersetzungsprojekt enthält, wie folgt:

 [po_directory] man/po/

Das bereitgestellte Verzeichnis muss eine Gruppe von PO-Dateien enthalten, jede mit Namen F<XX.po>, wobei C<XX> der ISO 631-Code der in dieser Datei verwandten Sprache ist. Das Verzeichnis muss auch eine einzelne POT-Datei enthalten, die die Endung C<.pot> trägt. Beim ersten Lauf kann diese Datei leer sein, sie muss aber existieren (Po4a kann den Namen, der vor der Erweiterung zu verwenden ist, nicht erraten).

Beachten Sie, dass Sie nur einen aus C<po_directory> und C<po4a_paths> auswählen dürfen. Ersterer (C<po_directory>) ist kompakter, reduziert das Risiko von Kopieren-/Einfügenfehlern weiter, erzwingt aber die Verwendung von einer erwarteten Projektstruktur und Dateinamen. Die zweite Möglichkeit (C<po4a_paths>) ist expliziter, wahrscheinlich lesbarer und wird empfohlen, wenn Sie Ihr erstes Projekt mit Po4a einrichten.

=head3 Zentralisierte oder getrennte PO-Dateien?

Standardmäßig erstellt Po4a eine einzelne PO-Datei pro Zielsprache, die den gesamten Inhalt Ihres Übersetzungsprojektes enthält. Mit dem Wachstum Ihres Projektes könnte die Größe der Dateien problematisch werden. Bei der Verwendung von Weblate ist es möglich, für jedes Übersetzungssegment (d.h., msgid) Prioritäten festzulegen, so dass wichtige zuerst übersetzt werden. Einige Übersetzungsteams bevorzugen es aber weiterhin, den Inhalt in mehrere Teile zu trennen.

Um eine PO-Datei pro Master-Datei zu erhalten, müssen Sie einfach die Zeichenkette C<$master> im Namen Ihrer PO-Dateien auf der C<[po4a_paths]>-Zeile wie folgt verwenden:

 [po4a_paths] dok/$master/$master.pot $lang:dok/$master/$lang.po

Mit dieser Zeile wird Po4a getrennte POT- und PO-Dateien für jedes zu übersetzende Dokument erstellen. Wenn Sie beispielsweise 3 Dokumente und 5 Sprachen haben, führt dies zu 3 POT-Dateien und 15 PO-Dateien. Diese Dateien werden so benannt, wie sie in der Vorlage C<po4a_paths> festgelegt wurden, wobei C<$master> durch den Basisnamen jedes der zu übersetzenden Dokumente ersetzt wird. Im Falle von Namenskonflikten können Sie mit dem Parameter C<pot=> die zu verwendende POT-Datei festlegen.

Diese Funktionalität kann auch dazu verwandt werden, um mehrere übersetzte Dateien in die gleiche POT-Datei zu gruppieren. Das folgende Beispiel erstellt nur zwei POT-Dateien: F<l10n/po/foo.pot> (dass das Material aus F<foo/gui.xml> enthält) und F<l10n/po/bar.pot> (dass das Material aus sowohl F<bar/gui.xml> als auch F<bar/cli.xml> enthält).

 [po4a_langs] de fr ja
 [po4a_paths] l10n/po/$master.pot $lang:l10n/po/$master.$lang.po
 [type: xml] foo/gui.xml $lang:foo/gui.$lang.xml pot=foo
 [type: xml] bar/gui.xml $lang:bar/gui.$lang.xml pot=bar
 [type: xml] bar/cli.xml $lang:bar/cli.$lang.xml pot=bar

Im getrennten Modus baut B<po4a> während der PO-Aktualisierung ein temporäres Kompendium auf, um die Übersetzungen zwischen allen PO-Dateien gemeinsam zu benutzen. Falls zwei PO-Dateien eine verschiedene Übersetzung der gleichen Zeichenkette haben, wird B<po4a> diese Zeichenkette mit »fuzzy« markieren und beide Übersetzungen in alle PO-Dateien einstellen, die diese Zeichenkette enthalten. Wenn der Übersetzer die Zeichenkette bereinigt, dann wird die Übersetzung automatisch in jede PO-Datei übernommen.

=head2 Angabe der zu übersetzenden Dokumente

Sie müssen auch die zu übersetzenden Dokumente aufführen. Für jede Master-Datei müssen Sie den zu verwendenden Format-Auswerter, den Ort der zu erstellenden Dokumente und optional weitere Konfiguration festlegen. Falls die Dateinamen Leerzeichen enthalten, müssen sie in Anführungszeichen eingeschlossen werden. Beispiel:

 [type: sgml] "dok/mein Zeug.sgml"  "fr:dok/fr/mon truc.sgml"  de:dok/de/mein\ kram.sgml
 [type: man] script fr:dok/fr/script.1 de:dok/de/script.1
 [type: docbook] dok/script.xml fr:dok/fr/script.xml \
             de:dok/de/script.xml

Aber diese drei komplexen Zeilen sind wieder schwer zu lesen und zu verändern, z.B. wenn neue Sprachen hinzugefügt werden. Es ist viel einfacher, die Dinge neu mittels der Vorlage C<$lang> wie folgt zu organisieren:

 [type: sgml]    dok/mein_zeug.sgml $lang:dok/$lang/mein_zeug.sgml
 [type: man]     script.1           $lang:po/$lang/script.1
 [type: docbook] dok/script.xml     $lang:dok/$lang/script.xml

=head2 Angabe der Optionen

Es gibt zwei Arten von Optionen: I<Po4a-Optionen> sind Vorgabewerte für die Po4a-Befehlszeilenoptionen, während I<Formatoptionen> zur Änderung des Verhaltens der Formatauswertprogramme verwandt werden. Als I<Po4a-Option> könnten Sie beispielsweise in Ihrer Konfigurationsdatei festlegen, dass der Vorgabewert für den Befehlszeilenparameter von B<--keep> 50% statt 80% beträgt. I<Formatoptionen> sind in ihren speziellen Handbuchseiten für jedes Auswertmodul dokumentiert, z.B. L<Locale::Po4a::Xml(3pm)>. Sie könnten beispielsweise B<nostrip> an das XML-Auswertprogramm übergeben, um die Leerzeichen rund um herausgelöste Zeichenketten nicht zu entfernen.

Sie können diese Optionen für eine bestimmte Masterdatei oder sogar für eine bestimmte Übersetzung dieser Datei mittels C<opt:> und C<opt_XX:> für die Sprache C<XX> übergeben. Im nachfolgenden Beispiel wird die Option B<nostrip> für den XML-Auswerter (für alle Sprachen) übergeben, während der Schwellwert für die französische Übersetzung auf 0% reduziert wird (diese wird daher immer beibehalten).

 [type:xml] toto.xml $lang:toto.$lang.xml opt:"-o nostrip" opt_fr:"--keep 0"

Auf jeden Fall müssen diese Konfigurationsteile sich am Ende der Zeile befinden. Die Erklärung der Dateien muss zuerst kommen, dann das Addendum, falls vorhanden, (siehe unten) und dann nur die Optionen. Die Gruppierung der Konfigurationsteile ist nicht sehr wichtig, da die Elemente intern als Zeichenketten aneinandergehängt werden. Die folgenden Beispiele sind alle äquivalent:

  [type:xml] toto.xml $lang:toto.$lang.xml opt:"--keep 20" opt:"-o nostrip" opt_fr:"--keep 0"
  [type:xml] toto.xml $lang:toto.$lang.xml opt:"--keep 20 -o nostrip" opt_fr:"--keep 0"
  [type:xml] toto.xml $lang:toto.$lang.xml opt:--keep opt:20 opt:-o opt:nostrip opt_fr:--keep opt_fr:0

Beachten Sie, dass beim Bau von POT-Dateien die sprachspezifischen Optionen nicht verwandt werden. Es ist beispielsweise unmöglich, B<nostrip> nur an das Auswertprogramm zu übergeben, wenn die französische Übersetzung gebaut wird, da die gleiche POT-Datei zur Aktualisierung aller Sprachen verwandt wird. Daher sind die einzigen sprachspezifischen Optionen diejenigen, die bei der Erstellung der Übersetzung verwandt werden können, wie die Option C<--keep>.

=head3 Konfigurationsaliase

Um die gleiche Option an mehrere Dateien zu übergeben, ist es am besten, wie folgt einen Typ-Alias zu definieren. Im nächsten Beispiel wird C<--keep 0> an jede italienische Übersetzung mittels dieses Typs C<test> übergeben, der eine Erweiterung des Typs C<man> ist.

  [po4a_alias:test] man opt_it:"--keep 0"
  [type: test] man/page.1 $lang:man/$lang/page.1

Sie können auch einen bestehenden Typ wie folgt erweitern, um den gleichen Aliasnamen erneut zu benutzen. Dies wird nicht als fehlerhafte rekursive Definition interpretiert.

  [po4a_alias:man] man opt_it:"--keep 0"
  [type: man] man/page.1 $lang:man/$lang/page.1

=head3 Globale Vorgabeoptionen

Sie können auch C<[options]>-Zeilen verwenden, um Optionen zu definieren, die für alle Dateien, unabhängig von deren Typ, verwandt werden müssen.

  [options] --keep 20 --option nostrip

Wie bei Befehlszeilenoptionen können Sie die in der Konfigurationsdatei übergebenen Parameter abkürzen:

  [options] -k 20 -o nostrip

=head3 Optionsprioritäten

Die Optionen jeder Quelle werden aneinandergehängt, wodurch sichergestellt wird, dass die Vorgabewerte leicht durch speziellere Optionen außer Kraft gesetzt werden können. Die Reihenfolge ist wie folgt:

=over 

=item 

C<[options]>-Zeilen stellen Vorgabewerte bereit, die durch jede andere Quelle außer Kraft gesetzt werden können.

=item 

Dann werden Typ-Aliase verwandt. Sprachspezifische Einstellungen setzen die für alle Sprachen angewandten Einstellungen außer Kraft.

=item 

Einstellungen, die für eine gegebene Master-Datei spezifisch sind, setzen sowohl die Vorgabe- als auch die von Typ-Alias kommenden Einstellungen außer Kraft. In diesem Fall setzen auch sprachspezifische Einstellungen die globalen außer Kraft.

=item 

Schließlich setzen auf der B<po4a>-Befehlszeile bereitgestellte Parameter alle Einstellungen aus Konfigurationsdateien außer Kraft.

=back

=head3 Beispiel

Hier ist ein Beispiel, das zeigt, wie Leer- und Anführungszeichen maskiert werden:

 [po_directory] man/po/
 
 [options] --master-charset UTF-8
 
 [po4a_alias:man] man opt:"-o \"mdoc=NAME,SEE ALSO\""
 [type:man] t-05-config/test02_man.1 $lang:tmp/test02_man.$lang.1 \
            opt:"-k 75" opt_it:"-L UTF-8" opt_fr:--verbose

=head2 Addendum: Zusätzliche Inhalte in der Übersetzung hinzufügen

Falls Sie einen zusätzlichen Abschnitt zu der Übersetzung hinzufügen möchten, beispielsweise für Danksagungen an den Übersetzer, müssen Sie ein Addendum für die Zeile, die ihre Master-Datei definiert, hinzufügen. In der Handbuchseite L<po4a(7)> finden Sie weitere Details zu der Syntax von Addendum-Dateien.

 [type: pod] script fr:dok/fr/script.1 \
             add_fr:dok/l10n/script.fr.add

Sie können wie folgt auch Sprachvorlagen verwenden:

 [type: pod] Skript $lang:dok/$lang/script.1 \
             add_$lang:dok/l10n/script.$lang.add

Falls ein Addendum nicht angewandt werden kann, wird die Übersetzung verworfen.

=head3 Attribute für die Addendum-Angabe

Addendum-Attribute können die Konfigurationsdatei in Fällen, in denen nicht alle Sprachen ein Addendum bereitstellen oder wenn sich Addenda von Sprache zu Sprache verändern, vereinfachen. Das Attribut ist ein einzelnes Zeichen, das sich vor dem Dateinamen befindet.

=over 2

=item B<?>

Berücksichtige I<Addendum_Pfad> falls die Datei existiert, andernfalls passiert nichts.

=item B<@>

I<Addendum_Pfad> ist kein reguläres Addendum, sondern eine Datei, die eine Liste von Addenda enthält, eines pro Zeile. Jedem Addendum kann ein Modifikator vorangestellt sein.

=item B<!>

I<Addendum_Pfad> wird verworfen, es wird nicht geladen und wird auch nicht von weiteren Addendumspezifikationen geladen.

=back

Folgendes Beispiel enthält ein Addendum für jede Sprache, aber nur, falls es existiert. Falls es nicht existiert, wird kein Fehler gemeldet.

 [type: pod] script $lang:dok/$lang/script.1  add_$lang:?dok/l10n/script.$lang.add

Folgendes Beispiel enthält eine Liste von Addenda für jede Sprache:

 [type: pod] script $lang:dok/$lang/script.1  add_$lang:@dok/l10n/script.$lang.add

=head2 Übersetzte Zeichenketten filtern

Manchmal möchten Sie einige Zeichenketten vor dem Übersetzungsprozess verstecken. Um dies zu erreichen, können Sie einen C<pot_in>-Parameter an Ihre Masterdatei übegeben, um den Namen der Datei festzulegen, die statt des echten Masters für den Bau der POT-Datei verwandt werden soll. Hier ist ein Beispiel:

  [type:docbook] book.xml          \
          pot_in:book-filtered.xml \
          $lang:book.$lang.xml

Mit dieser Einstellung werden die zu übersetzenden Zeichenketten aus F<book-filtered.xml> herausgelöst (diese Datei muss vor dem Aufruf von B<po4a> erstellt worden sein), während die übersetzten Dateien aus F<book.xml> heraus gebaut werden. Damit wird jede Zeichenkette, die Teil von F<book.xml> ist, aber nicht in F<book-filtered.xml> vorkommt, nicht Teil der PO-Dateien sein und damit verhindert, dass die Übersetzer eine Übersetzung davon bereitstellen. Daher verbleiben diese Zeichenketten bei der Erstellung übersetzter Dokumente unverändert. Damit wird logischerweise der Anteil der Übersetzung reduziert und Sie könnten die Option C<--keep> verwenden müssen, um sicherzustellen, dass das Dokument trotzdem erstellt wird.

=head1 SIEHE AUCH

L<po4a-gettextize(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-2023 SPI, Inc.

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.

