.\" 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 1p"
.TH PO4A 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 \- PO\-Dateien und übersetzte Dokumente auf einen Rutsch aktualisieren
.SH "ÜBERSICHT"
.IX Header "ÜBERSICHT"
\&\fBpo4a\fR [\fIOptionen\fR] \fIKonfig_Datei\fR
.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
Wenn Sie das Programm \fBpo4a\fR erstmalig mit nur einer Konfigurationsdatei
und den zu übersetzenden Dokumenten (genannt Master-Dokumenten) ausführen,
wird ein POT-Datei (auch Übersetzungsvorlage genannt) erstellt, die alle
übersetzbaren Zeichenketten in dem Dokument in einem Format, das die Arbeit
der Übersetzer erleichtert, erstellt.
.PP
Diese POT-Dateien können dann entweder mit einem dedizierten Editor wie dem
\&\fBGNOME\-Übersetzungs\-Editor\fR, KDEs \fBLokalize\fR oder \fBpoedit\fR übersetzt
werden oder sie können in eine Online-Lokalisierungsplattform wie \fBweblate\fR
oder \fBpootle\fR integriert werden. Das Ergebnis der Übersetzung ist eine
Reihe von PO-Dateien, eine pro Sprache.
.PP
Wenn Sie das Programm \fBpo4a\fR sowohl mit dem Master-Dokument als auch den
PO-Dateien ausführen, werden die übersetzten Dokumente erstellt, indem der
Inhalt der Übersetzung (wie er sich in den PO-Dateien befindet) in die
Struktur des ursprünglichen Master-Dokumentes eingespeist wird.
.PP
Falls sich das Master-Dokument zwischenzeitlich geändert hat, wird Po4a die
\&\s-1PO\-\s0 und POT-Dateien entsprechend aktualisieren, so dass die Übersetzer
leicht die Änderungen erkennen und ihre Arbeit aktualisieren
können. Abhängig von Ihren Einstellungen wird Po4a die teilweise übersetzten
Dokumente verwerfen oder Dokumente erzeugen, die Englisch (für die neuen
oder veränderten Absätze) und die Zielsprache (für die Absätze, für die
Übersetzungen bereits in der PO-Datei waren) mischt.
.PP
Standardmäßig werden die übersetzten Dokumente erstellt, wenn mindestens 80%
ihres Inhaltes übersetzt ist (siehe die nachfolgende Option
\&\fI\-\-keep\fR). Verwerfen von Übersetzungen, sobald sie nicht mehr zu 100%
erfüllt sind, kann für die Übersetzer entmutigend sein, während die
Erstellung von »Übersetzungen«, die zu unvollständig sind, bei Endbenutzer
zu Verdruß führen kann.
.SS "Graphischer Überblick"
.IX Subsection "Graphischer Überblick"
.Vb 11
\& Masterdokumente \-\-\-+\-\-\-\->\-\-\-\-\-\-\-\->\-\-\-\-\-\->\-\-\-\-\-\->\-\-\-\-+
\& (Dokumentenerstellung) | |
\& V (Po4a\-Ausführung) >\-\-\-\-\-+\-\-> Übersetzungen
\& | | |
\& bestehende PO\-Dateien \->\-\-\-> aktualisierte PO\-Dateien >\-+ |
\& ^ | |
\& | V |
\& +\-\-\-\-\-\-\-\-\-\-<\-\-\-\-\-\-\-\-\-\-<\-\-\-\-\-\-\-\-\-+ ^
\& (manueller Übersetzungsprozess) |
\& |
\& Addendum \-\->\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
.Ve
.PP
Die Master-Dokumente werden von den Dokumentenautoren geschrieben. Alle
Änderungen werden durch Po4a automatisch in den PO-Dateien wiedergegeben,
die dann durch die Übersetzer aktualisiert werden. Alle Änderungen an den
PO-Dateien (entwender manuell oder durch Po4a) werden in den übersetzten
Dokumenten wiedergespiegelt. Sie können dieses Verhalten mittels der Skripte
\&\fBpo4a\-updatepo\fR\|(1) und \fBpo4a\-translate\fR\|(1) in Make-Steuerdateien
nachahmen, aber dies wird schnell nervend und wiederholend (siehe
\&\fBpo4a\fR\|(7)). Wir legen Ihnen die Verwendung des Programms \fBpo4a\fR zum
Einsatz in Ihrem Bauprogramm ans Herz.
.SH "OPTIONEN"
.IX Header "OPTIONEN"
.IP "\fB\-k\fR, \fB\-\-keep\fR" 4
.IX Item "-k, --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.
.IP "\fB\-h\fR, \fB\-\-help\fR" 4
.IX Item "-h, --help"
zeigt eine kurze Hilfemeldung an
.IP "\fB\-M\fR, \fB\-\-master\-charset\fR" 4
.IX Item "-M, --master-charset"
Zeichensatz der Dateien, die die zu übersetzenden Dokumente
enthalten. Beachten Sie, dass alle Master-Dokumente im gleichen Zeichensatz
vorliegen müssen.
.IP "\fB\-L\fR, \fB\-\-localized\-charset\fR" 4
.IX Item "-L, --localized-charset"
Zeichensatz der Dateien, die die lokalisierten Dokumente enthalten. Beachten
Sie, dass alle übersetzte Dateien den gleichen Zeichensatz verwenden werden.
.IP "\fB\-A\fR, \fB\-\-addendum\-charset\fR" 4
.IX Item "-A, --addendum-charset"
Zeichensatz der Addenda. Beachten Sie, dass alle Addenda im gleichen
Zeichensatz vorliegen sollten.
.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\-q\fR, \fB\-\-quiet\fR" 4
.IX Item "-q, --quiet"
Verringern der Ausführlichkeit des Programms
.IP "\fB\-d\fR, \fB\-\-debug\fR" 4
.IX Item "-d, --debug"
Fehlersuch\- (Debug\-)Informationen ausgeben
.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\-f\fR, \fB\-\-force\fR" 4
.IX Item "-f, --force"
immer die \s-1POT\-\s0 und PO-Dateien erstellen, selbst wenn \fBpo4a\fR dies nicht für
notwendig betrachtet
.Sp
Das Standardverhalten (wenn \fB\-\-force\fR nicht angegeben ist) ist wie folgt:
.RS 4
.Sp
.RS 4
Falls die POT-Datei bereits existiert, wird sie neu erstellt, falls ein
Master-Dokument oder die Konfigurationsdatei neuer ist (außer \fB\-\-no\-update\fR
ist angegeben). Die POT-Datei wird auch in ein temporäres Dokument
geschrieben und \fBpo4a\fR überprüft, dass die Änderungen wirklich benötigt
werden.
.Sp
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 \fB\-\-keep\fR), kann
eine Datei mit der Erweiterung \fI.po4a\-stamp\fR erstellt werden (siehe
\&\fB\-\-stamp\fR).
.RE
.RE
.RS 4
.Sp
Falls ein Master-Dokument Dateien einbindet, soillten Sie den Schalter
\&\fB\-\-force\fR verwenden, da der Änderungszeitpunkt dieser eingebundenen Dateien
nicht mit betrachtet wird.
.Sp
Die PO-Dateien werden basierend auf der POT-Datei mittels \fBmsgmerge \-U\fR neu
erstellt.
.RE
.IP "\fB\-\-stamp\fR" 4
.IX Item "--stamp"
Sorgt dafür, dass \fBpo4a\fR 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 \fI.po4a\-stamp\fR, benannt.
.Sp
Hinweis: Dies aktiviert nur die Erstellung der \fI.po4a\-stamp\fR\-Dateien. Die
Stempeldateien werden immer benutzt, falls sie existieren, und sie werden
mit \fB\-\-rm\-translations\fR oder wenn die Datei schließlich übersetzt ist
entfernt.
.IP "\fB\-\-no\-translations\fR" 4
.IX Item "--no-translations"
die übersetzten Dokumente nicht erstellen, nur die \s-1POT\-\s0 und PO-Dateien
aktualisieren
.IP "\fB\-\-no\-update\fR" 4
.IX Item "--no-update"
die \s-1POT\-\s0 und PO-Dateien nicht ändern, nur die Übersetzung darf aktualisiert
werden.
.IP "\fB\-\-keep\-translations\fR" 4
.IX Item "--keep-translations"
behält die existierenden Übersetzungsdateien, selbst falls die Übersetzung
nicht die durch \fB\-\-keep\fR 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.
.Sp
\&\s-1WARNUNG:\s0 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.
.IP "\fB\-\-rm\-translations\fR" 4
.IX Item "--rm-translations"
entfernt die übersetzten Dateien (impliziert \fB\-\-no\-translations\fR)
.IP "\fB\-\-no\-backups\fR" 4
.IX Item "--no-backups"
Seit Version 0.41 macht dieser Schalter nichts und könnte daher in
zukünftigen Veröffentlichungen entfernt werden.
.IP "\fB\-\-rm\-backups\fR" 4
.IX Item "--rm-backups"
Seit Version 0.41 macht dieser Schalter nichts und könnte daher in
zukünftigen Veröffentlichungen entfernt werden.
.IP "\fB\-\-translate\-only\fR \fIübersetzte\-Datei\fR" 4
.IX Item "--translate-only ü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 \s-1PO\-\s0 und POT-Dateien
nicht aktualisiert. Diese Option kann mehrfach angewandt werden.
.IP "\fB\-\-variable\fR \fIVar\fR\fB=\fR\fIWert\fR" 4
.IX Item "--variable Var=Wert"
Definiert eine Variable, die in der \fBpo4a\fR\-Konfigurationsdatei expandiert
wird. Jedes Vorkommen von \fI$(Var)\fR wird durch \fIWert\fR ersetzt. Diese Option
kann mehrfach verwandt werden.
.IP "\fB\-\-srcdir\fR \fI\s-1QUELLVERZ\s0\fR" 4
.IX Item "--srcdir QUELLVERZ"
setzt das Basisverzeichnis für alle Eingabedokumente, die in der
Konfigurationsdatei \fBpo4a\fR angegeben sind
.Sp
Falls sowohl \fI\s-1ZIELVERZ\s0\fR als auch \fI\s-1QUELLVERZ\s0\fR festgelegt sind, wird in den
folgenden Verzeichnissen, in dieser Reihenfolge, nach Eingabedateien
gesucht: \fI\s-1ZIELVERZ\s0\fR, das aktuelle Verzeichnis und
\&\fI\s-1QUELLVERZ\s0\fR. Ausgabedateien werden in das \fI\s-1ZIELVERZ\s0\fR, falls angegeben,
oder in das aktuelle Verzeichnis geschrieben.
.IP "\fB\-\-destdir\fR \fI\s-1ZIELVERZ\s0\fR" 4
.IX Item "--destdir ZIELVERZ"
setzt das Basisverzeichnis für alle in der \fBpo4a\fR\-Konfigurationsdatei
angegebenen Dokumente (siehe \fB\-\-srcdir\fR weiter oben).
.SS "Optionen, die die POT-Kopfzeilen verändern"
.IX Subsection "Optionen, die die POT-Kopfzeilen verändern"
.IP "\fB\-\-porefs\fR \fITyp\fR" 4
.IX Item "--porefs Typ"
Gibt das Referenzformat an. Das Argument \fITyp\fR kann entweder \fBnever\fR
(keine Referenz erzeugen), \fBfile\fR (nur die Datei ohne Zeilenzahlen
festlegen), \fBcounter\fR (alle Zeilennummern durch einen ansteigenden Zähler
ersetzen) oder \fBfull\fR (komplette Referenzen einbinden) sein. Die Vorgabe
ist »full«.
.IP "\fB\-\-wrap\-po\fR \fBno\fR|\fBnewlines\fR|\fIZahl\fR (Vorgabe: 76)" 4
.IX Item "--wrap-po no|newlines|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 zu handhaben, aber
schwerer für Menschen zu lesen sind.
.Sp
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 \fBnewlines\fR
gesetzt, wird Po4a die msgid und msgstr nur nach Zeilenumbrüchen im Inhalt
auftrennen. Falls auf \fBno\fR gesetzt, wird Po4a die PO-Datei überhaupt nicht
umbrechen. Die Referenzkommentare werden durch die von Po4a intern
verwandten Gettext-Werkzeuge immer umgebrochen.
.Sp
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.
.IP "\fB\-\-master\-language\fR" 4
.IX Item "--master-language"
Sprache der Quelldateien, die die zu übersetzenden Dokumente
enthalten. Beachten Sie, dass alle Master-Dokumente in der gleichen Sprache
vorliegen müssen.
.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 "Optionen, um PO-Dateien zu verändern"
.IX Subsection "Optionen, um PO-Dateien zu verändern"
.IP "\fB\-\-msgmerge\-opt\fR \fIOptionen\fR" 4
.IX Item "--msgmerge-opt Optionen"
Extraoptionen für \fBmsgmerge\fR(1).
.Sp
Hinweis: \fB\f(CB$lang\fB\fR wird zur aktuellen Sprache erweitert.
.IP "\fB\-\-no\-previous\fR" 4
.IX Item "--no-previous"
Diese Option entfernt \fB\-\-previous\fR aus den an \fBmsgmerge\fR übergebenen
Optionen. Dies erlaubt die Unterstützung von \fBgettext\fR\-Versionen vor 0.16.
.IP "\fB\-\-previous\fR" 4
.IX Item "--previous"
Diese Option fügt \fB\-\-previous\fR zu den an \fBmsgmerge\fR übergebenen Optionen
hinzu. Dies benötigt \fBgettext\fR 0.16 oder neuer und ist standardmäßig
aktiviert.
.SH "KONFIGURATIONSDATEI"
.IX Header "KONFIGURATIONSDATEI"
Po4a erwartet eine Konfigurationsdatei als Argument. Diese Datei muss die
folgenden Elemente enthalten:
.IP "\(bu" 4
Den Pfad zu den PO-Dateien und der Liste der in dem Projekt existierenden
Sprachen.
.IP "\(bu" 4
Optional, einige globale Optionen und sogenannte Konfigurationsaliase, die
als Vorlagen zur Konfiguration individueller Master-Dateien verwandt werden.
.IP "\(bu" 4
Die Liste der zu übersetzenden Master-Dateien, zusammen mit speziellen
Parametern.
.PP
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.
.SS "Finden der \s-1PO\-\s0 und POT-Dateien"
.IX Subsection "Finden der PO- und POT-Dateien"
Die einfachste Lösung ist die Angabe der Pfade zu dem Verzeichnis, das Ihr
Übersetzungsprojekt enthält, wie folgt:
.PP
.Vb 1
\& [po_directory] man/po/
.Ve
.PP
Das bereitgestellte Verzeichnis muss eine Gruppe von PO-Dateien enthalten,
jede mit Namen \fI\s-1XX\s0.po\fR, wobei \f(CW\*(C`XX\*(C'\fR der \s-1ISO\s0 631\-Code der in dieser Datei
verwandten Sprache ist. Das Verzeichnis muss auch eine einzelne POT-Datei
enthalten, die die Endung \f(CW\*(C`.pot\*(C'\fR trägt.
.PP
Falls Sie es bevorzugen, können Sie die gleichen Information explizit
bereitstellen:
.PP
.Vb 1
\& [po4a_paths] man/po/project.pot de:man/po/de.po fr:man/po/fr.po
.Ve
.PP
Die speziellen Pfade zu der POT-Datei zuerst, und dann die Pfade zu den
deutschen und französischen PO-Dateien.
.PP
Schließlich kann die gleiche Information wie folgt geschrieben werden:
.PP
.Vb 2
\& [po4a_langs] fr de
\& [po4a_paths] man/po/project.pot $lang:man/po/$lang.po
.Ve
.PP
Die Komponente \f(CW$lang\fR wird automatisch mittels der bereitgestellten
Sprachliste ausgegeben, wodurch das Risiko von Kopieren\-/Einfüge\-Fehlern
reduziert wird, wenn eine neue Sprache hinzugefügt wird.
.PP
\fIZentralisierte oder getrennte PO-Dateien?\fR
.IX Subsection "Zentralisierte oder getrennte PO-Dateien?"
.PP
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.
.PP
Um eine PO-Datei pro Master-Datei zu erhalten, müssen Sie einfach die
Zeichenkette \f(CW$master\fR im Namen Ihrer PO-Dateien auf der
\&\f(CW\*(C`[po4a_paths]\*(C'\fR\-Zeile wie folgt verwenden:
.PP
.Vb 1
\& [po4a_paths] dok/$master/$master.pot $lang:dok/$master/$lang.po
.Ve
.PP
Falls es Namenskonflikte gibt, da mehrere Dateien den gleichen Dateinamen
haben, kann der Name der Masterdatei über das Hinzufügen der Option
\&\f(CW\*(C`master:file=\*(C'\fR\fIName\fR festgelegt werden:
.PP
.Vb 4
\& [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 master:file=foo\-gui
\& [type: xml] bar/gui.xml $lang:bar/gui.$lang.xml master:file=bar\-gui
.Ve
.PP
Im getrennten Modus baut \fBpo4a\fR 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 \fBpo4a\fR 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.
.SS "Angabe der zu übersetzenden Dokumente"
.IX Subsection "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. Beispiel:
.PP
.Vb 5
\& [type: sgml] dok/mein_zeug.sgml fr:dok/fr/mon_truc.sgml \e
\& 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 \e
\& de:dok/de/script.xml
.Ve
.PP
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 \f(CW$lang\fR wie folgt zu
organisieren:
.PP
.Vb 3
\& [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
.Ve
.SS "Angabe der Optionen"
.IX Subsection "Angabe der Optionen"
Es gibt zwei Arten von Optionen: \fIPo4a\-Optionen\fR sind Vorgabewerte für die
Po4a\-Befehlszeilenoptionen, während \fIFormatoptionen\fR zur Änderung des
Verhaltens der Formatauswertprogramme verwandt werden. Als \fIPo4a\-Option\fR
könnten Sie beispielsweise in Ihrer Konfigurationsdatei festlegen, dass der
Vorgabewert für den Befehlszeilenparameter von \fB\-\-keep\fR 50% statt 80%
beträgt. \fIFormatoptionen\fR sind in ihren speziellen Handbuchseiten für jedes
Auswertmodul dokumentiert, z.B. \fBLocale::Po4a::Xml\fR\|(3pm). Sie könnten
beispielsweise \fBnostrip\fR an das XML-Auswertprogramm übergeben, um die
Leerzeichen rund um herausgelöste Zeichenketten nicht zu entfernen.
.PP
Sie können diese Optionen für eine bestimmte Masterdatei oder sogar für eine
bestimmte Übersetzung dieser Datei mittels \f(CW\*(C`opt:\*(C'\fR und \f(CW\*(C`opt_XX:\*(C'\fR für die
Sprache \f(CW\*(C`XX\*(C'\fR übergeben. Im nachfolgenden Beispiel wird die Option
\&\fBnostrip\fR 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).
.PP
.Vb 1
\& [type:xml] toto.xml $lang:toto.$lang.xml opt:"\-o nostrip" opt_fr:"\-\-keep 0"
.Ve
.PP
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:
.PP
.Vb 3
\& [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
.Ve
.PP
Beachten Sie, dass beim Bau von POT-Dateien die sprachspezifischen Optionen
nicht verwandt werden. Es ist beispielsweise unmöglich, \fBnostrip\fR 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
\&\f(CW\*(C`\-\-keep\*(C'\fR.
.PP
\fIKonfigurationsaliase\fR
.IX Subsection "Konfigurationsaliase"
.PP
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 \f(CW\*(C`\-\-keep 0\*(C'\fR
an jede italienische Übersetzung mittels dieses Typs \f(CW\*(C`test\*(C'\fR übergeben, der
eine Erweiterung des Typs \f(CW\*(C`man\*(C'\fR ist.
.PP
.Vb 2
\& [po4a_alias:test] man opt_it:"\-\-keep 0"
\& [type: test] man/page.1 $lang:man/$lang/page.1
.Ve
.PP
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.
.PP
.Vb 2
\& [po4a_alias:man] man opt_it:"\-\-keep 0"
\& [type: man] man/page.1 $lang:man/$lang/page.1
.Ve
.PP
\fIGlobale Vorgabeoptionen\fR
.IX Subsection "Globale Vorgabeoptionen"
.PP
Sie können auch \f(CW\*(C`[options]\*(C'\fR\-Zeilen verwenden, um Optionen zu definieren,
die für alle Dateien, unabhängig von deren Typ, verwandt werden müssen.
.PP
.Vb 1
\& [options] \-\-keep 20 \-\-option nostrip
.Ve
.PP
Wie bei Befehlszeilenoptionen können Sie die in der Konfigurationsdatei
übergebenen Parameter abkürzen:
.PP
.Vb 1
\& [options] \-k 20 \-o nostrip
.Ve
.PP
\fIOptionsprioritäten\fR
.IX Subsection "Optionsprioritäten"
.PP
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:
.IP "\(bu" 4
\&\f(CW\*(C`[options]\*(C'\fR\-Zeilen stellen Vorgabewerte bereit, die durch jede andere
Quelle außer Kraft gesetzt werden können.
.IP "\(bu" 4
Dann werden Typ-Aliase verwandt. Sprachspezifische Einstellungen setzen die
für alle Sprachen angewandten Einstellungen außer Kraft.
.IP "\(bu" 4
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.
.IP "\(bu" 4
Schließlich setzen auf der \fBpo4a\fR\-Befehlszeile bereitgestellte Parameter
alle Einstellungen aus Konfigurationsdateien außer Kraft.
.PP
\fIBeispiel\fR
.IX Subsection "Beispiel"
.PP
Hier ist ein Beispiel, das zeigt, wie Leer\- und Anführungszeichen maskiert
werden:
.PP
.Vb 1
\& [po_directory] man/po/
\&
\& [options] \-\-master\-charset UTF\-8
\&
\& [po4a_alias:man] man opt:"\-o \e"mdoc=NAME,SEE ALSO\e""
\& [type:man] t\-05\-config/test02_man.1 $lang:tmp/test02_man.$lang.1 \e
\& opt:"\-k 75" opt_it:"\-L UTF\-8" opt_fr:\-\-verbose
.Ve
.SS "Addendum: Zusätzliche Inhalte in der Übersetzung hinzufügen"
.IX Subsection "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 \fBpo4a\fR\|(7) finden Sie weitere Details zu der Syntax von
Addendum-Dateien.
.PP
.Vb 2
\& [type: pod] script fr:dok/fr/script.1 \e
\& add_fr:dok/l10n/script.fr.add
.Ve
.PP
Sie können wie folgt auch Sprachvorlagen verwenden:
.PP
.Vb 2
\& [type: pod] Skript $lang:dok/$lang/script.1 \e
\& add_$lang:dok/l10n/script.$lang.add
.Ve
.PP
Falls ein Addendum nicht angewandt werden kann, wird die Übersetzung
verworfen.
.PP
\fIAttribute für die Addendum-Angabe\fR
.IX Subsection "Attribute für die Addendum-Angabe"
.PP
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.
.IP "\fB?\fR" 2
.IX Item "?"
Berücksichtige \fIAddendum_Pfad\fR falls die Datei existiert, andernfalls
passiert nichts.
.IP "\fB@\fR" 2
.IX Item "@"
\&\fIAddendum_Pfad\fR 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.
.IP "\fB!\fR" 2
.IX Item "!"
\&\fIAddendum_Pfad\fR wird verworfen, es wird nicht geladen und wird auch nicht
von weiteren Addendumspezifikationen geladen.
.PP
Folgendes Beispiel enthält ein Addendum für jede Sprache, aber nur, falls es
existiert. Falls es nicht existiert, wird kein Fehler gemeldet.
.PP
.Vb 1
\& [type: pod] script $lang:dok/$lang/script.1 add_$lang:?dok/l10n/script.$lang.add
.Ve
.PP
Folgendes Beispiel enthält eine Liste von Addenda für jede Sprache:
.PP
.Vb 1
\& [type: pod] script $lang:dok/$lang/script.1 add_$lang:@dok/l10n/script.$lang.add
.Ve
.SS "Übersetzte Zeichenketten filtern"
.IX Subsection "Übersetzte Zeichenketten filtern"
Manchmal möchten Sie einige Zeichenketten vor dem Übersetzungsprozess
verstecken. Um dies zu erreichen, können Sie einen \f(CW\*(C`pot_in\*(C'\fR\-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:
.PP
.Vb 3
\& [type:docbook] book.xml \e
\& pot_in:book\-filtered.xml \e
\& $lang:book.$lang.xml
.Ve
.PP
Mit dieser Einstellung werden die zu übersetzenden Zeichenketten aus
\&\fIbook\-filtered.xml\fR herausgelöst (diese Datei muss vor dem Aufruf von
\&\fBpo4a\fR erstellt worden sein), während die übersetzten Dateien aus
\&\fIbook.xml\fR heraus gebaut werden. Damit wird jede Zeichenkette, die Teil von
\&\fIbook.xml\fR ist, aber nicht in \fIbook\-filtered.xml\fR 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 \f(CW\*(C`\-\-keep\*(C'\fR verwenden müssen,
um sicherzustellen, dass das Dokument trotzdem erstellt wird.
.SS "\s-1KONFIGURATIONSBEISPIEL\s0"
.IX Subsection "KONFIGURATIONSBEISPIEL"
\&\s-1TODO:\s0 Ist dieser Abschnitt wirklich nützlich?
.PP
Nehmen wir an, Sie betreuen ein Paket namens \fBfoo\fR mit der Handbuchseite
\&\fIman/foo.1\fR, die naturgemäß nur auf Englisch gewartet wird. Als
(Distributions\-)Betreuer wollen Sie jetzt Übersetzungen erstellen und
betreuen. Zuerst müssen Sie die POT-Datei mittels \fBpo4a\-gettextize\fR\|(1)
erstellen, die zum Senden an die Übersetzer notwendig ist.
.PP
In diesem Fall würde folgender Aufruf erfolgen:
.PP
.Vb 1
\& cd man && po4a\-gettextize \-f man \-m foo.1 \-p foo.pot
.Ve
.PP
Diese Datei schicken Sie dann an die entsprechenden Sprachlisten oder bieten
sie auf Ihrer Website zum Herunterladen an.
.PP
Nehmen wir jetzt an, dass Sie drei Übersetzungen vor Ihrer nächsten
Veröffentlichung erhalten haben: \fIde.po\fR (mit einem Addendum \fIde.add\fR),
\&\fIsv.po\fR und \fIpt.po\fR. Da Sie Ihre \fIMakefile\fR(s) nicht ändern möchten,
wenn eine neue Übersetzung eintrifft, können Sie \fBpo4a\fR mit einer
geeigneten Konfigurationsdatei (in diesem Beispiel \fIpo4a.cfg\fR) in Ihrer
\&\fIMakefile\fR aufrufen. In unserem Beispiel würde diese Konfigurationdatei
dann wie folgt aussehen:
.PP
.Vb 1
\& [po_directory] man/po4a/po/
\&
\& [type: man] man/foo.1 $lang:man/translated/$lang/foo.1 \e
\& add_$lang:?man/po4a/add_$lang/$lang.add opt:"\-k 80"
\&In diesem Beispiel wird angenommen, dass die erstellte Handbuchseite (und
\&alle PO\- und Addenda\-Dateien) in F (respektive
\&F und F) unterhalb des aktuellen
\&Verzeichnisses gespeichert werden. In diesem Beispiel würde dann das
\&Verzeichnis F die Dateien F, F und F
\&enthalten und das Verzeichnis F die Datei F.
.Ve
.PP
Beachten Sie die Verwendung des Modifikators \fB?\fR, da nur die deutsche
Übersetzung (\fIde.po\fR) von einem Addendum begleitet wird.
.PP
Um dann die übersetzten Handbuchseiten tatsächlich zu bauen, würde
(einmalig!) die folgende Zeile in das \fBbuild\fR\-Ziel der entsprechenden
\&\fIMakefile\fR eingebaut werden:
.PP
.Vb 1
\& po4a po4a.cfg
.Ve
.PP
Sobald dies eingerichtet ist, müssen Sie die \fIMakefile\fR nicht mehr
anfassen, wenn eine neue Übersetzung eintrifft, d.h. falls das französische
Team Ihnen \fIfr.po\fR und \fIfr.add\fR schickt, dann packen Sie diese einfach in
\&\fIman/po4a/po/\fR respektive \fIman/po4a/add_fr/\fR und beim nächsten Mal, wenn
das Programm gebaut wird, wird auch die französische Übersetzung automatisch
in \fIman/translated/fr/\fR gebaut.
.PP
Beachten Sie, dass Sie weiterhin ein geeignetes Ziel in der \fIMakefile\fR
benötigen, um die übersetzten Handbuchseiten zusammen mit den englischen zu
installieren.
.PP
Falls Sie die automatisch erstellten Dateien nicht in Ihrem
Versionskontrollsystem speichern wollen, benötigen Sie schließlich noch eine
Zeile zum Ziel \fBclean\fR:
\-rm \-rf man/translated
.SH "SIEHE AUCH"
.IX Header "SIEHE AUCH"
\&\fBpo4a\-gettextize\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.