PO4A.7(1) User Contributed Perl Documentation PO4A.7(1) NAME Po4a - Rahmenwerk zur Ubersetzung von Dokumentation und anderen Materialien Einleitung Po4a (PO fur alles) erleichtert die Pflege von Dokumentationsubersetzungen mittels der klassischen Gettext-Werkzeuge. Die Hauptfunktionalitat von Po4a ist, dass sie die Ubersetzung des Inhaltes von der Dokumentenstruktur trennt. Dieses Dokument dient als Einfuhrung in das Po4a-Projekt mit einem Fokus auf mogliche Benutzer, die uberlegen, ob sie dieses Werkzeug verwenden sollten und den Neugierigen, die verstehen mochten, warum die Dinge so sind, wie sie sind. Warum Po4a? Die Philosophie Freier Software ist es, die Technik wirklich fur jeden verfugbar zu machen. Aber Lizenzierung ist nicht die einzige Betrachtung: nicht ubersetzte Freie Software ist fur nicht englisch sprechende Personen nutzlos. Daher haben wir noch einiges zu tun, Software fur jede Person verfugbar zu machen. Von den meisten Projekten wird diese Situation sehr gut verstanden und jeder ist jetzt von der Notwendigkeit, alles zu ubersetzen, uberzeugt. Allerdings stellt die eigentliche Ubersetzung einen riesengrossen Aufwand durch viele Beteiligte dar, die zudem von kleinen technischen Schwierigkeiten behindert werden. Dankenswerterweise ist Open-Source-Software mittels der Gettext- Werkzeugsammlung sehr gut ubersetzt. Diese Werkzeuge werden zum Entnehmen der zu ubersetzenden Zeichenketten aus einem Programm verwandt und dann werden diese Zeichenketten in einem standardisierten Format dargestellt (genannt PO-Dateien oder Ubersetzungskataloge). Ein gesamtes Okosystem an Werkzeugen ist entstanden, um Ubersetzern beim eigentlichen Ubersetzen dieser PO-Dateien zu helfen. Das Ergebnis wird dann von Gettext zur Laufzeit verwandt, um dem Endbenutzer die ubersetzten Meldungen anzuzeigen. Im Hinblick auf Dokumentation ist die Situation allerdings immer noch etwas entauschend. Anfangs erscheint die Ubersetzung der Dokumentation leichter als die Ubersetzung eines Programms, da es so aussieht, als mussten Sie nur das Ursprungsdokument kopieren und anfangen, den Inhalt zu ubersetzen. Wenn allerdings das Ursprungsdokument verandert wird, wird die Nachverfolgung der Anderungen schnell zu einem Albtraum fur Ubersetzer. Falls dies manuell erfolgt, ist die Aufgabe unschon und fehlerbehaftet. Veraltete Ubersetzungen sind oft schlimmer als gar keine. Endbenutzer konnen durch Dokumentation, die veraltetes Verhalten des Programms beschreibt, verwirrt werden. Sie konnen zudem nicht direkt mit dem Betreuer in Kontakt treten, da sie kein Englisch sprechen. Zusatzlich kann der Betreuer keine Probleme beheben, da er nicht jede Sprache spricht, in die seine Dokumentation ubersetzt ist. Diese Schwierigkeiten, die oft durch schlechte Werkzeuge hervorgerufen werden, konnen die Motivation fur freiwillige Ubersetzer unterminieren, wodurch das Problem weiter verschlimmert wird. Das Ziel des Po4a-Projektes ist es, die Arbeit der Dokumentenubersetzer zu erleichtern. Insbesondere macht es die Dokumentenubersetzungen pflegbar. Die Idee besteht darin, den Gettext-Ansatz fur dieses Feld wiederzuverwenden und anzupassen. Wie bei Gettext werden Texte aus ihren ursprunglichen Orten herausgelost und den Ubersetzern als PO-Ubersetzungskataloge dargestellt. Die Ubersetzer konnen die klassischen Gettext-Werkzeuge wirksam einsetzen, um die zu erledigende Arbeit zu uberwachen, zusammenzuarbeiten und sich als Teams zu organisieren. Po4a fugt dann die Ubersetzung direkt in die Dokumentationsstruktur ein, um ubersetzte Quelldateien zu erstellen, die dann genau wie die englischen Dateien verarbeitet und verteilt werden konnen. Jeder Absatz, der nicht ubersetzt ist, verbleibt im entstehenden Dokument auf englisch, wodurch sichergestellt ist, dass die Endbenutzer niemals veraltete Ubersetzungen in der Dokumentation sehen. Dies automatisiert den grossten Teil der Routinearbeit bei der Wartung von Ubersetzungen. Es wird sehr leicht, die zu aktualisierenden Absatze zu erkennen und der Prozess ist vollstandig automatisiert, wenn Elemente ohne weitere Anderungen neu sortiert werden. Es konnen auch spezielle Uberprufungen verwandt werden, um die Moglichkeit von Formatierungsfehlern zu verringern, die zu einem defekten Dokument fuhren wurden. Bitte lesen Sie auch die FAQ weiter unten in diesem Dokument fur eine komplette Liste der Vor- und Nachteile dieser Vorgehensweise. Unterstutzte Formate Derzeit wurde diese Vorgehensweise erfolgreich fur mehrere Arten von Textformatierungsformaten umgesetzt: man (ausgereiftes Auswertprogramm) Das gute alte Handbuchformat, verwandt von vielen Programmen da draussen. Die Unterstutzung durch Po4a wird hier sehr begrusst, da dieses Format etwas schwierig zu benutzen und fur Neulinge nicht wirklich einladend ist. Das Modul Locale::Po4a::Man(3pm) unterstutzt das Format >>mdoc<<, das von den BSD-Handbuchseiten verwandt wird (diese sind auch unter Linux recht haufig anzutreffen). AsciiDoc (ausgereiftes Auswertprogramm) Dieses Format ist ein leichtgewichtiges Textauszeichnungsformat, um das Schreiben von Dokumentation zu erleichtern. Es wird beispielsweise von dem Git-System verwandt. Dessen Handbuchseiten werden mittels Po4a ubersetzt. Siehe Locale::Po4a::AsciiDoc fur Details. pod (ausgereiftes Auswertprogramm) Das ist das >>Perl Online Documentation<<-Format. Die Sprache und Erweiterungen selbiger sind in diesem Format dokumentiert sowie die meisten existierenden Perl-Skripte. Sie erleichtert es, die Dokumentation nahe beim eigentlichen Code zu halten, indem beide in die gleiche Datei eingebettet werden. Es erleichtert Programmierern die Arbeit, aber unglucklicherweise nicht den Ubersetzern, bis sie Po4a verwenden. Siehe Locale::Po4a::Pod fur Details. sgml (ausgereiftes Auswertprogramm) Obwohl dieses Format heutzutage von XML verdrangt wurde, wird es noch fur Dokumente verwandt, die mehr als ein paar Bildschirmseiten lang sind. Es kann sogar fur komplette Bucher verwandt werden. Die Ubersetzung so langer Dokumente zu aktualisieren kann eine echte Herausforderung werden. diff stellt sich oft als nutzlos raus, wenn der ursprungliche Text nach der Aktualisierung neu eingeruckt wurde. Glucklicherweise kann Ihnen Po4a nach diesem Prozess helfen. Derzeit werden nur die DebianDoc- und DocBook-DTD unterstutzt, aber das Hinzufugen einer Unterstutzung fur eine neue DTD ist wirklich leicht. Es ist sogar moglich, Po4a fur eine unbekannte SGML-DTD zu verwenden, ohne den Code zu verandern, indem die benotigten Informationen auf der Befehlszeile ubergeben werden. Lesen Sie Locale::Po4a::Sgml(3pm) fur weitere Details. TeX / LaTeX (ausgereiftes Auswertprogramm) Das LaTeX-Format ist ein wichtiges Dokumentationsformat, das in der Welt der Freien Software und fur Veroffentlichungen genutzt wird. Das Modul Locale::Po4a::LaTeX(3pm) wurde mit der Python- Dokumentation, einem Buch und ein paar Prasentationen ausprobiert. text (ausgereiftes Auswertprogramm) Das Text-Format ist das Grundlagenformat fur viele Formate, die langere Textblocke enthalten wie Markdown, Glucksspruche, YAML- Deckblattabschnitte, debian/changelog und debian/control. Dies unterstutzt das haufige in >>Static Site Generators<<, READMEs und anderen Dokumentationssystemen verwandte Format. Siehe Locale::Po4a::Text(3pm) fur Details. xml und XHMTL (wahrscheinlich ausgereiftes Auswertprogramm) Das XML-Format liegt vielen Dokumentationsformaten zu Grunde. Derzeit werden die DocBook-DTD (siehe Locale::Po4a::Docbook(3pm) fur weitere Details) und XHTML von Po4a unterstutzt. BibTex (wahrscheinlich ausgereiftes Auswertprogramm) Das BibTex-Format wird zusammen mit LaTex zur Formatierung von Fundstellen (Bibliographien) verwandt. Siehe Locale::Po4a::BibTex fur Details. Docbook (wahrscheinlich ausgereiftes Auswertprogramm) Ein XML-basierte Auszeichnungssprache, die semantische Markierungen zur Beschreibung von Dokumenten verwendet. Siehe Locale::Po4a:Docbook fur genauere Details. Anleitungs-XML (wahrscheinlich ausgereiftes Auswertprogramm) Ein XML-Dokumentationsformat. Dieses Modul wurde speziell entwickelt, um bei der Unterstutzung und Betreuung der Gentoo- Linux-Dokumentation bis mindestens einschliesslich Marz 2016 (laut der Wayback Machine) zu helfen. Gentoo ist seitdem auf das Format DevBook XML umgestiegen. Siehe Locale::Po4a:Guide fur genauere Details. Wml (wahrscheinlich ausgereiftes Auswertprogramm) Die Web-Auszeichnungssprache, verwechseln Sie WML nicht dem WAP- Zeug, das auf Handys verwendet wird. Dieses Modul baut auf dem Xhtml-Modul auf, das wiederum auf dem XmL-Modul aufbaut. Siehe Locale::Po4a::Wml fur genauere Details. Yaml (wahrscheinlich ausgereiftes Auswertprogramm) Eine strikte Obermenge von JSON. YAML wird oft als System- oder Konfigurationsprojekt verwandt. YAML ist der Kern von Red Hats Ansible. Siehe Locale::Po4a::Yaml fur genauere Details. RubyDoc (wahrscheinlich ausgereiftes Auswertprogramm) Das Ruby-Dokument (RD-)Format, ursprunglich das Standarddokumentationsformat von Ruby und Ruby-Projekten, bevor die Umstellung auf RDoc in 2002 erfolgte. Obwohl anscheinend die japanische Version des Ruby-Referenzhandbuches immer noch RD verwendet. Siehe Locale::Po4a::RubyDoc fur genauere Details. Halibut (wahrscheinlich experimentelles Auswertprogramm) Ein Dokumentenerstellungssystem, mit Elementen, die TeX, debiandoc- sgml, TeXinfo und anderen ahneln. Entwickelt von Simon Tatham, dem Entwickler von PuTTY. Siehe Locale::Po4a:Halibut fur genauere Details. Ini (wahrscheinlich experimentelles Auswertprogramm) Konfigurationsdateiformat, durch MS-DOS beliebt geworden. Siehe Locale::Po4a::Ini fur genauere Details. texinfo (sehr hoch experimentelles Auswertprogramm) Die gesamte GNU-Dokumentation ist in diesem Format geschrieben (dies ist sogar eine der Voraussetzungen, um ein offizielles GNU- Projekt zu werden). Die Unterstutzung fur Locale::Po4a::Texinfo(3pm) in Po4a ist noch ganz am Anfang. Bitte berichten Sie Fehler und Funktionalitatswunsche. gemtext (sehr hoch experimentelles Auswertprogramm) Das native schlichte Textformat des Gemini-Protokolls. Die Erweiterung >>.gmi<< wird haufig verwandt. Unterstutzung fur dieses Modul ist in Po4a noch in fruhen Anfangen. Falls Sie etwas finden, reichen Sie bitte (auf Englisch) einen Fehler oder eine Funktionalitatsbitte ein. Andere unterstutzte Formate Po4a kann auch mit einigen selteneren oder spezialisierten Formaten umgehen, wie dem Dokumentationsformat der Kompilierungsoptionen des 2.4+-Linux-Kernels (Locale::Po4A::KernelHelp) oder der vom Dia- Werkzeug erstellten Diagramme (Locale::Po4a:Dia). Das Hinzufugen eines neuen Formats ist oft sehr leicht und die Hauptaufgabe besteht darin, einen Parser fur Ihr Zielformat zu entwickeln. Lesen Sie Locale::Po4a::TransTractor(3pm) fur mehr Informationen dazu. Nicht unterstutzte Formate Unglucklicherweise fehlen Po4a immer noch Unterstutzung fur eine Reihe von Dokumentationsformaten. Viele davon konnten leicht in Po4a unterstutzt werden. Dazu gehoren auch Formate, die nicht nur fur die Dokumentation verwandt werden, wie Paketbeschreibungen (Deb und RPM), Paketinstallationsskriptfragen, Paket-Anderungsprotokolle (>>Changelogs<<) und alle spezialisierten Dateiformate, die von Programmen verwandt werden, wie Spieleszenarien oder WINE- Ressource-Dateien. Po4a verwenden Am einfachsten verwenden Sie dieses Werkzeug in Ihrem Projekt, indem Sie eine Konfigurationsdatei fur das Programm po4a schreiben und nur mit diesem Programm interagieren. Bitte lesen Sie dessen Dokumentation in po4a(1). Der Rest dieses Abschnitts stellt eine detailliertere Beschreibung fur fortgeschrittenere Benutzer von Po4a bereit, die ihr Verstandnis vertiefen mochten. Detailliertes Schema des Po4a-Arbeitsablaufs Lesen Sie auf jeden Fall vor diesem sehr detaillierten Abschnitt erst po4a(1), um einen vereinfachten Uberblick uber den Po4a-Arbeitsablauf zu bekommen. Kommen Sie hierher zuruck, wenn Sie das vollstandige, gruselige Bild mit fast allen Datails bekommen mochten. Im nachfolgende Schema steht master.dok als Beispielname fur die zu ubersetzende Dokumentation; XX.dok das gleiche Dokument ubersetzt in die Sprache XX wahrend doc.XX.po der Ubersetzungskatalog fur das Dokument in der Sprache XX ist. Dokumentationsautoren kummern sich hauptsachlich um master.dok (dies kann eine Handbuchseite, ein XML- Dokument, eine AsciiDoc-Datei usw. sein); die Ubersetzer kummern sich hauptsachlich um die PO-Dateien, wahrend die Endbenutzer nur die Datei XX.dok sehen werden. Ubergange mit eckigen Klammern wie "[po4a updates po]" stellen die Ausfuhrung eines Po4a-Werkzeugs dar, wahrend Ubergange mit geschweiften Klammern wie "{Aktualisierung von Master.dok}" eine handische Veranderung der Projektdateien darstellt. Master.dok | V +<-----<----+<-----<-----<--------+------->-------->-------+ : | | : {Ubersetzung} | {Aktualisierung von Master.dok} : : | | : XX.dok | V V (optional) | Master.dok ->-------->------>+ : | (neu) | V V | | [po4a-gettextize] dok.XX.po--->+ | | | (alt) | | | | ^ V V | | | [po4a aktualisiert po] | V | | V Ubersetzung.pot ^ V | | | dok.XX.po | | | (unscharf) | {Ubersetzung} | | | | ^ V V | | {manuelle Bearbeitung} | | | | | V | V V dok.XX.po --->---->+<---<---- doc.XX.po Addendum Master.dok (anfanglich) (aktuell) (optional) (aktuell) : | | | : V | | +----->----->----->------> + | | | | | V V V +------>-----+------<------+ | V [po4a aktualisiert Ubersetzungen] | V XX.dok (aktuell) Wiederum ist dieses Schema ubermassig kompliziert. Lesen Sie po4a(1) fur einen vereinfachten Uberblick. Der linke Teil stellt dar, wie po4a-gettextize(1) verwandt werden kann, um ein bestehendes Ubersetzungsprojekt in die Po4a-Infrastruktur zu uberfuhren. Dieses Skript akzeptiert ein Ursprungsdokument und sein ubersetztes Gegenstuck und versucht, eine entsprechende PO-Datei daraus zu bauen. Eine solche manuelle Umwandlung ist recht beschwerlich (lesen Sie die Dokumentation von po4a-gettextize(1) fur weitere Details), sie wird aber nur einmalig notwendig, um Ihre bestehende Ubersetzungen zu uberfuhren. Falls Sie keine Ubersetzungen uberfuhren mussen, konnen Sie diesen Schritt ignorieren und sich auf den rechten Teil des Schemas konzentrieren. Ganz oben rechts wird die Aktion der Ursprungsautors dargestellt, der die Dokumentation aktualisiert. Der mittel-rechte Teil stellt die automatischen Aktualisierungen der Ubersetzungsdateien dar: Das neue Material wird herausgelost und mit der bestehenden Ubersetzung verglichen. Die vorherige Ubersetzung wird fur unveranderte Teile verwandt, wahrend teilweise geanderte Teile mit der vorherigen Ubersetzung mit einer >>fuzzy<<-Markierung verbunden sind, die anzeigt, dass die Ubersetzung aktualisiert werden muss. Neues oder stark verandertes Material verbleibt unubersetzt. Dann stellt der Block manuelle Bearbeitung die Aktionen der Ubersetzer dar, die die PO-Dateien verandern, um Ubersetzungen fur jede Ursprungszeichenkette und jeden Absatz bereitzustellen. Dies kann entweder mit einem speziellen Editor wie dem GNOME-Ubersetzungseditor, KDEs Lokalize oder poedit erfolgen, oder mittels einer Online- Lokalisierungsplattform wie Weblate oder Pootle. Das Ubersetzungsergebnis ist eine Gruppe von PO-Dateien, eine pro Sprache. Bitte lesen Sie die Gettext-Dokumentation fur weitere Details. Der untere Teil der Abbildung zeigt, wie po4a ein ubersetztes Quelldokument aus dem ursprunglichen Dokument master.doc und dem Ubersetzungskatakog doc.XX.po, der durch die Ubersetzer aktualisiert wurde, erstellt. Die Struktur des Dokuments wird wiederverwandt, wahrend der ursprungliche Inhalt durch sein ubersetztes Gegenstuck ersetzt wird. Optional kann ein Addendum verwandt werden, um einigen Extratext zu der Ubersetzung hinzuzufugen. Dies wird oft dazu verwandt, den Namen des Ubersetzers zum finalen Dokument hinzuzufugen. Sie finden Details hierzu weiter unten. Beim Aufruf aktualisiert po4a die Ubersetzungsdateien und die ubersetzen Dokumentationsdateien automatisch. Ein neues Ubersetzungsprojekt beginnen Falls Sie auf der grunen Wiese anfangen, mussen Sie nur eine Konfigurationsdatei fur Po4a schreiben und das wars. Die wichtigen Vorlagen fur die fehlenden Dateien werden automatisch erstellt und erlauben es Ihren Beitragenden, Ihr Projekt in ihre Sprache zu ubersetzen. Lesen Sie bitte po4a(1) fur eine Schnellstartanleitung und alle Details. Falls Sie bereits eine bestehende Ubersetzung haben, d.h. eine Dokumentationsdatei, die manuell ubersetzt wurde, konnen Sie den Inhalt in Ihren Po4a-Arbeitsablauf mittels po4a-gettextize integrieren. Diese Aufgabe ist ein bisschen muhselig, aber sobald Ihr Projekt in den Po4a-Arbeitsablauf konvertiert ist, wird alles automatisch aktualisiert. Aktualisierungen der Ubersetzungen und Dokumente Sobald eingerichtet reicht der Aufruf von po4a, um sowohl die Ubersetzungs-PO-Dateien als auch die ubersetzten Dokumente zu aktualisieren. Sie konnen "--no-translations" an po4a ubergeben, um die PO-Dateien nicht zu aktualisieren (und somit nur die Ubersetzungen zu aktualisieren). Dies entspricht grob den einzelnen Skripten po4a-updatepo und po4a-translate, die jetzt veraltet sind (siehe >>Warum die einzelnen Skripte veraltet sind<< in der nachstehenden FAQ). Verwendung von Addenda, um zusatzlichen Text zu Ubersetzungen hinzuzufugen Hinzufugen von neuem Text zu der Ubersetzung ist wahrscheinlich das einzige, was langfristig bei der manuellen Ubersetzung einfacher ist :). Dies kommt vor, wenn Sie einen zusatzlichen Abschnitt zu dem ubersetzten Dokument hinzufugen mochten, der nicht zu Inhalten im Ursprungsdokument passt. Der klassische Anwendungsfall ist die Danksagung an das Ubersetzungs-Team und die Information, wie ubersetzungsspezifische Fehler berichtet werden sollen. Mit Po4a mussen Sie addendum-Dateien angeben, die konzeptionell als Patches angesehen werden konnen, die auf das lokalisierte Dokument nach der Verarbeitung angewandt werden. Jedes Addendum muss als separate Datei bereitgestellt werden, wobei das Format sich allerdings deutlich von klassischen Patches unterscheidet. Die erste Zeile ist eine Kopfzeile, die den Einschubpunkt des Addendums definiert (mit einer unglucklicherweise kryptischen Syntax -- siehe unten), wahrend der Rest der Datei unverandert an der festgelegten Position eingefugt wird. Die Kopfzeile muss mit der Zeichenkette PO4A-HEADER: beginnen, gefolgt von einer durch Semikola getrennten Liste von Schlussel=Wert-Paaren. Beispielsweise erklart die folgende Kopfzeile, dass ein Addendum ganz am Ende der Ubersetzung abgelegt werden muss. PO4A-HEADER: mode=eof Die Dinge werden komplexer, wenn Sie den zusatzlichen Inhalt in der Mitte des Dokuments hinzufugen wollen. Die folgende Kopfzeile erklart, dass nach dem XML-Abschnitt, der die Zeichenkette Uber dieses Dokument in der Ubersetzung enthalt, ein Addendum abgelegt werden muss. PO4A-HEADER: position=Uber dieses Dokument; mode=after; endboundary= In der Praxis wird Po4a beim Versuch, ein Addendum anzuwenden, nach der ersten Zeile, die auf das Argument "Position" passt, suchen ("Position" kann ein regularer Ausdruck sein). Vergessen Sie nicht, dass Po4a hier das ubersetzte Dokument betrachtet. Das Ursprungsdokument ist auf Englisch, aber Ihre Zeile sollte wahrscheinlich wie folgt aussehen, falls Sie mochten, dass sie auf die franzosische Ubersetzung des Dokuments angewandt wird. PO4A-HEADER: position=A propos de ce document; mode=after; endboundary= Sobald die "Position" im Zieldokument gefunden wurde, sucht Po4a fur die nachste Zeile nach der "Position", die auf das bereitgestellte "endboundary" passt. Das Addendum wird direkt nach dieser Zeile eingefugt (da wir eine endboundary bereitstellten, d.h. eine Begrenzung, die den aktuellen Abschnitt beendet). Der genau gleiche Effekt konnte mit den nachfolgenden Kopfzeilen erreicht werden, die aquivalent sind: PO4A-HEADER: position=Uber dieses Dokument; mode=after; beginboundary=
Hier sucht Po4a in der Ubersetzung nach der ersten Zeile, die auf "
" passt und nach der auf "Uber dieses Dokument" passenden Zeile liegt, und fugt das Addendum vor dieser Zeile ein, da wir ein beginboundary bereitgestellt haben, d.h. eine Begrenzungsmarkierung, die den Anfang des nachsten Abschnitts markiert. Daher verlangt diese Kopfzeile, dass das Addendum nach dem Abschnitt, der "Uber dieses Dokument" enthalt, gesetzt wird, und weist Po4a an, dass dieser Abschnitt mit einer Zeile, die die Markierung "
" enthalt, beginnt. Dies ist zum vorherigen Beispiel aquivalent, da Sie in Wirklichkeit mochten, dass dieses Addendum entweder nach "
" oder vor "
" hinzugefugt wird. Sie konnen den Einfuge-Modus auch auf den Wert "before" setzen, mit einer ahnlichen Semantik: Kombinierung von "mode=before" mit einem "endboundary" wird das Addendum genau nach der passenden Begrenzung setzen. Dies ist die letzte mogliche Begrenzungszeile vor der "Position". Kombinierung von "mode=before" mit einer "beginboundary" setzt das Addendum genau vor die passende Begrenzung. Dies ist die letzte mogliche Begrenzungszeile vor der "Position". Modus | Begrenzungsart | Verwandte Begrenzung | Einfugepunkt im Vergleich zur Begrenzung ========|================|=======================|========================================= 'before'| 'endboundary' | letzte vor 'Position' | direkt nach der ausgewahlten Begrenzung 'before'|'beginboundary' | letzte vor 'Position' | direkt vor der ausgewahlten Begrenzung 'after' | 'endboundary' | erste nach 'Position' | direkt nach der ausgewahlten Begrenzung 'after' |'beginboundary' | erste nach 'Position' | direkt vor der ausgewahlten Begrenzung 'eof' | (keine) | n.Z. | Dateiende Tipps und Tricks rund um Addenda o Denken Sie daran, dass dies regulare Ausdrucke sind. Falls Sie beispielsweise das Ende eines Nroff-Abschnittes, das auf die Zeile ".fi" endet, vergleichen wollen, verwenden Sie nicht ".fi" als endboundary, da es auf "the[ fi]le" passen wird, was sie offensichtlich nicht erwarten wurden. Das korrekte endboundary ist in diesem Fall: ^\.fi$. o Leerzeichen SIND im Inhalt von "position" und Begrenzungen wichtig. Daher unterscheiden sich die beiden nachfolgenden Zeilen. Die zweite wird nur gefunden, falls im ubersetzen Dokument ausreichend angehangte Leerzeichen sind. PO4A-HEADER: position=Uber dieses Dokument; mode=after; beginboundary=
PO4A-HEADER: position=Uber dieses Dokument ; mode=after; beginboundary=
o Obwohl diese Kontextsuche so betrachtet werden konnte, als ob sie ungefahr auf jeder Zeile des ubersetzten Dokuments arbeiten wurde, arbeitet sie tatsachlich auf der internen Datenzeichenkette des ubersetzten Dokuments. Diese interne Datenzeichenkette kann ein Text sein, der mehrere Absatze mit mehreren Zeilen umfasst oder kann eine einzelne XML-Markierung selbst sein. Der genaue Einfugepunkt des Addendums muss vor oder nach der internen Datenzeichenkette und kann nicht innerhalb der internen Datenzeichenkette liegen. o Ubergeben Sie das Argument "-vv" an po4a, um zu verstehen, wie Addenda zu der Ubersetzung hinzugefugt werden. Es kann auch helfen, po4a im Fehlersuchmodus zu betreiben, um die tatsachlichen internen Datenzeichenketten zu sehen, wenn Ihr Addendum nicht angewandt wird. Addenda-Beispiele o Falls Sie etwas hinter den folgenden Nroff-Abschnitt hinzufugen mochten: .SH "AUTOREN" Sie sollten den zweischrittigen Zugang durch Setzen von mode=after wahlen. Dann sollten Sie mit dem regularen Argumentenausdruck Position die Suche auf die Zeile nach AUTOREN eingrenzen. Dann sollten Sie eine Ubereinstimmung mit dem Anfang des nachsten Abschnittes (d.h. ^\.SH) mit dem regularen Argumentenausdruck beginboundary erzielen. Mit anderen Worten: PO4A-HEADER:mode=after;position=AUTOREN;beginboundary=\.SH o Falls Sie etwas direkt nach einer Zeile hinzufugen mochten (etwa hinter >>Copyright Grosser Kerl<<), verwenden Sie eine Position, die auf diese Zeile passt und geben Sie ein beginboundary an, das zu irgendeiner Zeile passt. PO4A-HEADER:mode=after;position=Copyright Grosser Kerl, 2004;beginboundary=^ o Falls Sie am Ende des Dokuments etwas hinzufugen mochten, geben Sie eine Position an, die zu einer Zeile Ihres Dokuments passt (aber nur eine Zeile - Po4a wird nicht fortfahren, wenn sie nicht eindeutig ist) und geben Sie ein endboundary an, das zu nichts passt. Verwenden Sie hier keine einfachen Zeichenketten wie >>EOF<<, aber nehmen Sie bevorzugt solche, bei denen es unwahrscheinlich ist, dass sie sich in Ihrem Dokument befinden. PO4A-HEADER:mode=after;position=Uber dieses Dokument;beginboundary=FakePo4aBoundary Ein ausfuhrlicheres Beispiel Originaldokument (POD-formatiert): |=head1 BESCHREIBUNG | |dummy - Ein Platzhalterprogramm | |=head1 AUTOR | |ich Dann wird das folgende Addendum sicherstellen, dass ein Abschnitt (auf Franzosisch) uber den Ubersetzer an das Ende der Datei hinzugefugt wird (auf Franzosisch heisst >>UBERSETZER<< >>TRADUCTEUR<< und >>moi<< heisst >>ich<<). |PO4A-HEADER:mode=after;position=AUTEUR;beginboundary=^=head | |=head1 TRADUCTEUR | |moi | Um Ihr Addendum vor dem AUTOR einzufugen, verwenden Sie die folgende Kopfzeile: PO4A-HEADER:mode=after;position=NOM;beginboundary=^=head1 Dies funktioniert, da die nachste auf das beginboundary "/^=head1/" passende Zeile nach dem Abschnitt >>BESCHREIBUNG<< (ubersetzt zu >>NOM<< auf Franzosisch) diejenige ist, die die Autoren deklariert. Daher wird das Addendum zwischen beide Abschnitte gelegt. Beachten Sie: Falls spater ein anderer Abschnitt zwischen den Abschnitten NAME und AUTHOR hinzugefugt wird, wird Po4a das Addendum fehlerhafterweise vor den neuen Abschnitt legen. Um dies zu vermeiden, konnen Sie das gleiche mittels mode=before erreichen: PO4A-HEADER:mode=before;position=^=head1 AUTEUR Wie funktioniert es? Dieses Kapitel gibt Ihnen einen kurzen Uberblick uber die Interna von Po4a, so dass Sie sich sicherer fuhlen, es zu warten und zu verbessern. Es konnte Ihnen auch dabei helfen, zu verstehen, warum es nicht das tut, was Sie erwarten, und wie Sie Ihre Probleme beheben konnen. TransTractoren und Projektarchitektur Im Herzen des Po4a-Projekt ist die Klasse Locale::Po4a::TransTractor(3pm) der gemeinsame Vorfahr von allen Auswertungsklassen. Dieser merkwurdige Name ist der Tatsache zu verdanken, dass er gleichzeitig fur das Ubersetzen des Dokuments und das Extrahieren von Zeichenketten zustandig ist. Formlicher ausgedruckt nimmt es ein Dokument zum Ubersetzen plus eine PO-Datei, die die Ubersetzungen enthalt, als Eingabe, wahrend es zwei getrennte Ausgaben erzeugt: Eine weitere PO-Datei (die das Ergebnis des Extrahierens ubersetzbarer Zeichenketten vom Eingabedokument ist) und einem ubersetzen Dokument (mit der gleichen Struktur, wie der aus der Eingabe, bei der aber alle ubersetzbaren Zeichenketten durch den Inhalt der Eingabe-PO-Datei ersetzt wurden). Hier eine grafische Darstellung davon: Eingabedokument -- \ /---> Ausgabedokument \ TransTractor:: / (ubersetzt) +-->-- parse() --------+ / \ Eingabe-PO-Datei---/ \---> Ausgabe-PO-Datei (extrahiert) Dieser kleine Knochen ist der Kern der Po4a-Architektur. Falls Sie sowohl die Eingabe bereitstellen und die Ausgabe-PO ignorieren, erhalten Sie po4a-translate. Falls Sie stattdessen das Augabedokument ignorieren, erhalten Sie po4a-updatepo. po4a verwendet einen ersten TransTractor, um eine aktuelle Ausgabe-POT-Datei zu erhalten (und ignoriert die Ausgabedokumente), ruft msgmerge -U auf, um die Ubersetzungs-PO-Dateien auf Platte zu aktualisieren und baut einen zweiten TransTractor mit diesen aktualisierten PO-Dateien, um die Ausgabedokumente zu aktualisieren. Kurz gesagt, po4a stellt eine integrierte Losung bereit, alles notwendige mittels einer einzigen Konfigurationsdatei zu aktualisieren. po4a-gettextize verwendet auch zwei TransTractoren, aber auf eine andere Art: Es baut einen TransTractor pro Sprache und baut dann eine neue PO-Datei mittels der Msgids des ursprunglichen Dokuments als Msgids und den Msgids des ubersetzten Dokuments als Msgstrs. Es bedarf grosser Sorgfalt sicherzustellen, dass alle Zeichenketten, die so zueiander kommen auch tatsachlich zueinander passen, wie in po4a-gettextize(1) beschrieben. Format-spezifische Auswerter Alle Po4a-Formatauswerter sind auf dem TransTractor implementiert. Einige von ihnen sind sehr einfach, wie die fur Text, Markdown und AsciiDoc. Sie laden die Zeilen nacheinander mittels TransTractor::shiftline() und sammeln den Inhalt des Absatzes oder was auch immer auf. Sobald eine Zeichenkette komplett ausgewertet ist, verwendet der Auswerter TransTractor::translate() um (1) diese Zeichenkette zu der Ausgabe-PO-Datei hinzuzufugen und (2) die Ubersetzung aus der Eingabe-PO-Datei zu erhalten. Der Auswerter schiebt das Ergebnis mittels TransTractor::pushline() in die Ausgabedatei. Einige andere Auswerter sind komplexer, da sie auf externe Auswerter angewiesen sind, um das Eingabedokument auszuwerten. Die Auswerter fur XML, HTML, SGML und Pod bauen auf den SAX-Auswerter auf. Sie erklaren Rucksprunge zu Ereignissen wie >>Ich habe einen neuen Titel mit folgendem Inhalt gefunden<<, um gemass des Eingabeinhalts mittels TransTractor::translate() und TransTractor::pushline() das Ausgabedokument und die Ausgabe-POT-Dateien zu aktualisieren. Der Yaml- Auswerter ist ahnlich aber anders: er serialisiert eine durch den Auswerter YAML::Tiny erzeugte Datenstruktur. Daher schlagt das Yaml- Modul von Po4a beim Erklaren der Referenzzeilen fehl: der Ort jeder Zeichenkette in der Eingabedatei wird durch den Auswerter nicht aufgehoben, so dass nur >>$filename:1<< als Zeichenkettenort bereitgestellt werden kann. Die SAX-orientierten Auswerter verwenden >>globals<< und andere Tricks, um den Dateinamen und die Zeilennummer von Referenzen zu speichern. Ein besonderes Problem tritt durch Dateikodierungen und BOM- Markierungen auf. Einfache Auswerter konnen das Problem ignorieren, um das sich TransTractor::read() kummert (intern verwandt, um die Zeilen eines Eingabedokuments zu erhalten), aber Module, die sich auf einen externen Auswerter Auswerter verlassen, mussen sicherstellen, dass alle Dateien mit einen geeigneten PerlIO-Decoding-Layer gelesen werden. Am einfachsten offen sie die Datei selbst und stellen einen Filehandle oder direkt die gesamte Zeichenkette an den externen Auswerter bereit. Schauen Sie in Pod::read() und Pod::parse() fur ein Beispiel. Der vom TransTractor gelesene Inhalt wird ignoriert, aber ein frischer Filehandle wird an das externe Auswerteprogramm ubergeben. Der wichtige Teil ist der Modus "<:encoding($charset)", der an die Perl-Funktion open() ubergeben wird. Po-Objekte Die Klasse Locale::Po4a::Po(3pm) kummert sich um das Laden und verwenden von PO- und POT-Dateien. Im wesentlichen kann eine Datei gelesen, Eintrage hinzugefugt, Ubersetzungen mit der Methode gettext() erhalten und die PO in eine Datei geschrieben werden. Fortgeschrittenere Funktionalitaten wie das Zusammenfuhren einer PO- Datei mittels einer POT-Datei oder das Uberprufen einer Datei werden an msgmerge bzw. msgfmt delegiert. Zu Po4a beitragen Selbst wenn Sie in der Vergangenheit noch nie zu einem Open-Source- Projekt beigetragen haben, sind Sie willkommen: Wir helfen Ihnen gerne und beraten Sie gerne. Da uns Mitarbeitende fehlen, versuchen wir eine Willkommensinfrastruktur zu schaffen, indem wir die Dokumentation und die automatischen Tests verbessern, um Ihnen Zuversicht beim Beitragen zum Projekt zu geben. Bitte lesen Sie die Datei CONTRIBUTING.md fur weitere Details. Open-Source-Projekte, die Po4a verwenden Es folgt eine unvollstandige Liste von Projekten, die Po4a fur ihre Dokumentation im Einsatz haben. Falls Sie Ihre Projekt in diese Liste aufgenommen haben mochten, schicken Sie uns auf Englisch eine E-Mail (oder einen >>Merge Request<<). o adduser (man): Benutzer- und Gruppenverwaltungswerkzeug. o apt (man, docbook): Debian-Paketverwalter. o aptitude (docbook, svg): Terminal-baierter Paketverwalter fur Debian o F-Droid website (markdown): installierbarer Katalog an FOSS (Free and Open Source Software) Anwendungen fur die Android-Plattform. o git (asciidoc): verteiltes Versionssteuersystem zur Nachverfolgung von Quellcodeanderungen. o Linux manpages (man) Dieses Projekt stellt die Infrastruktur zur Ubersetzung vieler Handbuchseiten in verschiedene Sprachen bereit, mit Integration in viele grosse Distributionen (Arch Linux, Debian und abgeleitete, Fedora). o Stellarium (HTML): ein freies, Open-Source-Planetarium fur Ihren Rechner. Po4a wird zur Ubersetzung der Himmelskulturbeschreibungen verwandt. o Jamulus (Markdown, YAML, HTML): eine FOSS- Anwendung zum Online-Jamming in Echtzeit. Die Dokumentation des Webauftritts wird mittels Po4a in mehreren Sprachen verwaltet. o Anderer zu sortierender Eintrag: Haufig gestellte Fragen Wie wird Po4a ausgesprochen? Ich personlich spreche es als pouah aus, was auf Franzosich lautmalerisch anstelle von >>Bah<< verwandt wird :) Vielleicht habe ich einen merkwurdigen Humor :) Warum sind die einzelnen Skripte veraltet? Tatsachlich sind po4a-updatepo und po4a-translate zugunsten po4a veraltet. Dies liegt daran, dass po4a als direkter Ersatz fur diese Skripte verwandt werden kann und es hier eine Menge an doppelten Code gibt. Die einzelnen Skripte sind rund 150 Code-Zeilen, wahrend das Programm po4a 1200 Zeilen lang ist, daher machen sie eine Menge zusatzliches neben den gemeinsamen Interna. Der doppelte Code fuhrt dazu, dass Fehler in beiden Versionen auftreten und zwei Korrekturen benotigen. Ein Beispiel fur eine solche Doppelung sind die Fehler #1022216 in Debian und das Problem #442 in GitHub, die beide die exakt gleiche Korrektur hatten, aber die eine in po4a und die andere in po4a-updatepo. Langfristig wurde ich gerne die einzelnen Skripte entfernen und nur eine Version des Codes verwalten. Die einzelnen Skripte werden auf jeden Fall nicht mehr verbessert, daher wird nur po4a neue Funktionalitaten bekommen. Damit sei aber angemerkt, dass es keine Dringlichkeit fur das Veralten gibt. Ich habe vor, die einzelnen Skripte so lange wie moglich beizubehalten, mindestens bis 2030. Falls Ihr Projekt 2030 immer noch po4a-updatepo und po4a-translate verwendet, konnten Sie ein Problem haben. Es konnte auch sein, dass wir die Veraltung dieser Skripte irgendwann aufheben, falls eine Restrukturierung die Code-Dopplung auf Null reduziert. Falls Sie dazu eine Idee (oder besser: einen Patch) haben, wurden wir uns uber Ihre Hilfe freuen. Was ist mit den anderen Ubersetzungswerkzeugen fur Dokumentation, die Gettext benutzen? Es gibt eine Reihe davon. Hier ist eine unvollstandige Liste und weitere Werkzeuge erscheinen am Horizont. poxml Dies ist das durch KDE-Leute entwickelte Werkzeug, um DocBook-XML zu handhaben. Soweit bekannt, war es das erste Programm zum Extrahieren von Zeichenketten aus der Dokumentation in PO-Dateien und um sie nach dem Ubersetzen wieder einzuspeisen. Es kann nur XML und eine spezielle DTD handhaben. Der Verfasser ist ziemlich unglucklich mit der Handhabung von Listen, die in einer grossen Msgid enden. Wenn die Liste gross wird, wird es schwerer, mit dem grossen Stuck umzugehen. po-debiandoc Dieses von Denis Barbier erstellte Programm ist so eine Art Vorlaufer des Po4a-SGML-Moduls, wodurch ersteres mehr oder weniger missbilligt ist. Wie der Name sagt, handhabt es nur die DebianDoc- DTD, die mehr oder weniger eine missbilligte DTD ist. xml2po.py Vom GIMP-Dokumentationsteam seit 2004 verwandt. Funktioniert recht gut, selbst wenn es, wie es der Name andeutet, nur mit XML-Dateien funktioniert und besonders konfigurierte Makefiles benotigt. Sphinx Das Sphinx-Dokumentationsprojekt verwendet Gettext auch intensiv, um seine Ubersetzungen zu verwalten. Unglucklicherweise funktioniert es nur fur einige wenige Textformate, Rest und Markdown, obwohl es wahrscheinlich das einzige Werkzeug ist, das den gesamten Ubersetzungsprozess verwaltet. Die Hauptvorteile von Po4a demgegenuber sind die Erleichterung beim Hinzufugen zusatzlichen Inhalts (was dort sogar schlechter ist) und die Fahigkeit, Gettext zu verwenden. ZUSAMMENFASSUNG der Vorteile der Gettext-basierten Herangehensweise o Die Ubersetzungen werden nicht zusammen mit dem Original gespeichert, wodurch es moglich wird, festzustellen, ob Ubersetzungen nicht mehr aktuell sind. o Die Ubersetzungen werden jeweils in separaten Dateien gespeichert, was verhindert, dass sich Ubersetzer unterschiedlicher Sprachen, sowohl beim Senden des Patches als auch auf der Ebene des Dateikodierung, storen. o Es basiert intern auf Gettext (Po4a bietet aber eine sehr einfache Schnittstelle, so dass Sie die Interna nicht verstehen mussen, um es zu benutzen). Auf diese Art muss das Rad nicht neu erfunden werden und aufgrund ihrer weiten Verbreitung kann davon ausgegangen werden, dass diese Werkzeuge mehr oder weniger fehlerfrei sind. o Fur den Endanwender hat sich nichts geandert (ausser der Tatsache, dass Ubersetzungen hoffentlich besser gepflegt werden). Die resultierende Dokumentationsdatei, die verteilt wird, ist exakt dieselbe. o Es ist nicht notig, dass Ubersetzer eine neue Dateisyntax lernen und ihr bevorzugter PO-Editor (wie der PO-Modus von Emacs, Lokalize oder Gtranslator) wird gut funktionieren. o Gettext bietet eine einfache Moglichkeit, Statistiken daruber zu erhalten, was erledigt ist, was uberpruft und aktualisiert werden sollte und was noch zu erledigen ist. Einige Beispiele konnen unter den folgenden Adressen gefunden werden: - https://docs.kde.org/stable5/en/kdesdk/lokalize/project-view.html - http://www.debian.org/intl/l10n/ Aber nicht alles ist rosig und diese Herangehensweise hat auch einige Nachteile, die bewaltigt werden mussen. o Addenda sind auf den ersten Blick etwas merkwurdig. o Sie konnen den ubersetzten Text nicht nach Ihren Praferenzen anpassen, wie das Aufteilen eines Absatzes hier und das Zusammensetzen zwei anderer dort. Aber, falls es in einem gewissen Sinn ein Problem mit dem Original gibt, sollte es sowieso als Fehler gemeldet werden. o Sogar mit der einfachen Oberflache bleibt es ein neues Werkzeug, das Leute lernen mussen. Es ware traumhaft, wenn jemand Po4a in Gtranslator oder Lokalize einbinden wurde. Wenn eine Dokumentationsdatei geoffnet wird, werden die Zeichenketten automatisch extrahiert. Wenn sie gespeichert wird, kann eine ubersetzte Datei + PO-Datei auf die Platte geschrieben werden. Falls es fertiggebracht wird, ein MS-Word-Modultm (oder zumindest RTF) zu erstellen, konnen es sogar professionelle Ubersetzer nutzen. SIEHE AUCH o Die Dokumentation des Komplettwerkzeuges, das Sie verwenden sollen: po4a(1). o Die Dokumentation der individuellen Po4a-Skripte: po4a-gettextize(1), po4a-updatepo(1), po4a-translate(1), po4a-normalize(1). o Die zusatzlichen Helferskripte: msguntypot(1), po4a-display-man(1), po4a-display-pod(1). o Die Auswertprogramme fur jedes Format, insbesondere, um die durch jedes akzeptierten Optionen zu sehen: Locale::Po4a::AsciiDoc(3pm) Locale::Po4a::Dia(3pm), Locale::Po4a::Guide(3pm), Locale::Po4a::Ini(3pm), Locale::Po4a::KernelHelp(3pm), Locale::Po4a::Man(3pm), Locale::Po4a::RubyDoc(3pm), Locale::Po4a::Texinfo(3pm), Locale::Po4a::Text(3pm), Locale::Po4a::Xhtml(3pm), Locale::Po4a::Yaml(3pm), Locale::Po4a::BibTeX(3pm), Locale::Po4a::Docbook(3pm), Locale::Po4a::Halibut(3pm), Locale::Po4a::LaTeX(3pm), Locale::Po4a::Pod(3pm), Locale::Po4a::Sgml(3pm), Locale::Po4a::TeX(3pm), Locale::Po4a::Wml(3pm), Locale::Po4a::Xml(3pm). o Die Implementierung der Kerninfrastruktur: Locale::Po4a::TransTractor(3pm) (insbesondere zum Verstandnis der Code-Organisation wichtig), Locale::Po4a::Chooser(3pm), Locale::Po4a::Po(3pm), Locale::Po4a::Common(3pm). Prufen Sie bitte auch die Datei CONTRIBUTING.md im dem Quellbaum. AUTOREN Denis Barbier Martin Quinson (mquinson#debian.org) perl v5.38.2 2024-06-26 PO4A.7(1)