Provided by: po4a_0.73-2ubuntu1_all 
NAAM
po4a - raamwerk voor de vertaling van documentatie en ander materiaal
Inleiding
po4a (PO voor alles) vergemakkelijkt het onderhoud van de vertaling van documentatie via het gebruik van
het klassieke gettext-gereedschap. De belangrijkste eigenschap van po4a is dat het de vertaling van de
inhoud loskoppelt van de structuur van het document.
Dit document dient als een inleiding tot het po4a-project met een focus op potentiële gebruikers die zich
afvragen of ze dit hulpmiddel zouden gebruiken, en op nieuwsgierigen die willen begrijpen waarom de
dingen zijn zoals ze zijn.
Waarom po4a?
De filosofie van Vrije Software is om de technologie echt voor iedereen beschikbaar te maken. Maar het
licentie-aspect is niet het enige om in overweging te nemen: voor niet-Engelstaligen is niet-vertaalde
software nutteloos. Daarom hebben we nog steeds wat werk te doen om software voor iedereen beschikbaar te
maken.
Door de meeste projecten wordt deze situatie goed begrepen en iedereen is nu overtuigd van de noodzaak om
alles te vertalen. Niettemin betekent het eigenlijke vertaalwerk een geweldige inspanning voor veel
individuen, gehandicapt door kleine technische moeilijkheden.
Gelukkig wordt opensourcesoftware eigenlijk heel goed vertaald met behulp van de gettext
gereedschapssuite. Dit gereedschap wordt gebruikt om de te vertalen tekstfragmenten uit een programma te
extraheren en deze te vertalen tekstfragmenten aan te bieden in een gestandaardiseerde indeling (PO-
bestanden genoemd, ofwel vertaalcatalogus). Een heel ecosysteem hulpmiddelen is ontstaan om vertalers te
helpen bij het daadwerkelijk vertalen van deze PO-bestanden. Het resultaat wordt vervolgens door gettext
gebruikt om tijdens de programmauitvoering de vertaalde berichten aan de eindgebruiker te tonen.
Met betrekking tot documentatie is de situatie nog steeds enigszins ontgoochelend. Op het eerste gezicht
lijkt het vertalen van documentatie makkelijker dan een programma vertalen, aangezien het erop lijkt dat
je gewoon het bronbestand met de documentatie moet kopiëren en moet beginnen met het vertalen van de
inhoud. Wanneer aan de originele documentatie echter aanpassingen gemaakt worden, wordt het bijhouden van
de wijzigingen al snel een nachtmerrie voor de vertalers. Indien deze taak manueel moet gebeuren is ze
onaangenaam en foutgevoelig.
Verouderde vertalingen zijn vaak erger dan helemaal geen vertaling. Eindgebruikers kunnen misleid worden
door documentatie die een verouderd gedrag van het programma beschrijft. Bovendien kunnen zij niet
rechtstreeks in interactie treden met de onderhouders, omdat zij geen Engels spreken. Daarenboven kan de
onderhouder het probleem niet oplossen, aangezien deze niet elke taal kan kennen waarin de documentatie
vertaald werd. Deze moeilijkheden, vaak veroorzaakt door slecht gereedschap, kan de motivatie van
vertaalvrijwilligers ondermijnen en zo leiden tot een verdere verergering van het probleem.
Het doel van het po4a-project is om het werk van documentatievertalers te vergemakkelijken. In het
bijzonder maakt het documentatievertalingen onderhoudbaar.
Het idee bestaat erin de gettext-aanpak te hergebruiken en aan te passen aan deze sector. Zoals dat met
gettext het geval is, worden teksten geëxtraheerd uit hun originele locatie en aan vertalers voorgelegd
als PO-vertaalcatalogi. De vertalers kunnen gebruik maken van het klassieke gettext-gereedschap om het te
presteren werk op te volgen, om samen te werken en zich als team te organiseren. Daarna injecteert po4a
de vertalingen rechtstreeks in de structuur van de documentatie om vertaalde bronbestanden te produceren
die verwerkt en verspreid kunnen worden, net als de Engelse bestanden. Elke onvertaalde paragraaf blijft
in het uiteindelijke document in het Engels staan, zodat er voor gezorgd wordt dat de eindgebruiker nooit
een verouderde vertaling te zien krijgt in de documentatie.
Dit automatiseert het grootste deel van het zware werk van het onderhoud van vertalingen. Te weten komen
welke paragrafen bijgewerkt moeten worden, wordt erg makkelijk, en het proces van het herordenen van
elementen zonder dat er verder iets wijzigt, verloopt volledig automatisch. Ook kan specifieke
verificatie toegepast worden om de kans op opmaakfouten, welke tot een defect document zouden leiden, te
verkleinen.
Raadpleeg ook de FAQ verder in dit document, voor een meer volledige lijst van de voor- en nadelen van
deze aanpak.
Ondersteunde indelingen
Momenteel werd deze aanpak met succes toegepast voor verschillende soorten tekstopmaakindelingen:
man (voldragen ontleder)
De goede oude man-paginaindeling, welke door zoveel programma's gebruikt wordt. Ondersteuning door
po4a is hier erg welkom, aangezien deze indeling enigszins moeilijk te gebruiken is en niet echt
vriendelijk voor nieuwkomers.
De module Locale::Po4a::Man(3pm) ondersteunt ook de mdoc-indeling, welke door de BSD man-pagina's
gebruikt wordt (deze zijn ook redelijk gebruikelijk onder Linux).
AsciiDoc (voldragen ontleder)
Dit is een lichtgewicht opmaakindeling, bedoeld om het schrijven van documentatie te
vergemakkelijken. Zij wordt bijvoorbeeld gebruikt voor het documenteren van het git-systeem. Deze
man-pagina's worden vertaald met po4a.
Zie Locale::Po4a::AsciiDoc voor details.
pod (voldragen ontleder)
Dit is de indeling voor de Perl Online Documentatie. De computertaal en de uitbreidingen ervan worden
gedocumenteerd met behulp van deze indeling, net als de meeste bestaande Perl-scripts. Het maakt het
makkelijk om de documentatie dicht bij de echte code te houden, door beide in te bedden in hetzelfde
bestand. Het maakt het leven van programmeurs makkelijker, maar jammer genoeg niet dat van vertalers,
tenzij u po4a gebruikt.
Zie Locale::Po4a::Pod voor details.
sgml (voldragen ontleder)
Zelfs als deze indeling tegenwoordig wordt vervangen door XML, wordt ze nog steeds gebruikt voor
documenten van meer dan enkele schermen lang. Ze kan zelfs gebruikt worden voor volledige boeken. Het
kan een hele uitdaging zijn om dergelijk lange documenten bij te werken. diff blijkt vaak niet
bruikbaar te zijn wanneer na het bijwerken het inspringen van de oorspronkelijke tekst opnieuw werd
uitgevoerd. Gelukkig kan po4a u na dit proces behulpzaam zijn.
Momenteel worden enkel DebianDoc en DocBook DTD ondersteund, maar iets anders ondersteunen is erg
gemakkelijk. Het is zelfs mogelijk om zonder de code te wijzigen po4a te gebruiken bij een onbekende
SGML DTD door de nodige informatie op te geven aan de commandoregel. Zie Locale::Po4a::Sgml(3pm) voor
details.
TeX / LaTeX (voldragen ontleder)
De LaTeX-indeling is een heel belangrijke indeling voor documentatie in de vrije-softwarewereld
evenals voor publicaties.
De module Locale::Po4a::LaTeX(3pm) werd getest met de Python-documentatie , een boek en enkele
presentaties.
text (voldragen ontleder)
De indeling Text is de basisindeling voor veel indelingen welke lange blokken tekst bevatten,
waaronder Markdown, fortunes, inleidend gedeelte van YAML, debian/changelog en debian/control.
Dit ondersteunt de indeling die Static Site Generators, README's en andere documentatiesystemen
gebruiken en gemeen hebben.
xml and XHMTL (vermoedelijk voldragen ontleder)
De indeling XML is een basisindeling voor veel documentatie-indelingen.
Momenteel worden DocBook DTD (zie Locale::Po4a::Docbook(3pm) voor details) en XHTML door po4a
ondersteund.
BibTex (vermoedelijk voldragen ontleder)
De BibTex-bestandsindeling wordt naast LaTex gebruikt voor het opmaken van referentielijsten
(bibliografieën).
Zie Locale::Po4a::BibTex voor details.
Docbook (vermoedelijk voldragen ontleder)
Een op XML gebaseerde opmaaktaal die semantische tags gebruikt om documenten te beschrijven.
Zie Locale::Po4a:Docbook voor meer details.
Guide XML (vermoedelijk voldragen ontleder)
Een XML-documentatieformaat. Deze module is speciaal ontwikkeld in functie van het ondersteunen en
onderhouden van vertalingen van Gentoo Linux-documentatie tot ten minste maart 2016 (gebaseerd op de
Wayback Machine). Gentoo is sindsdien overgestapt naar de DevBook XML-bestandsindeling.
Zie Locale::Po4a:Guide voor meer details.
Wml (vermoedelijk voldragen ontleder)
De Web-opmaaktaal (Web Markup Language); verwar WML niet met de WAP-spullen die op mobiele telefoons
worden gebruikt. Deze module is gebaseerd op de Xhtml-module, die zelf weer is gebaseerd op de XmL-
module.
Zie Locale::Po4a::Wml voor meer details.
Yaml (vermoedelijk voldragen ontleder)
Een strikte superset van JSON. YAML wordt vaak gebruikt als systeem- of configuratieproject. YAML
vormt de kern van Red Hat's Ansible.
Zie Locale::Po4a::Yaml voor meer details.
RubyDoc (vermoedelijk voldragen ontleder)
Het Ruby Document (RD) formaat, oorspronkelijk het standaard documentatieformaat voor Ruby en Ruby-
projecten voordat in 2002 werd overgeschakeld naar RDoc, hoewel de Japanse versie van het Ruby
Referentiehandboek blijkbaar nog steeds RD gebruikt.
Zie Locale::Po4a::RubyDoc voor meer details.
Halibut (vermoedelijk experimentele ontleder)
Een documentatieproductiesysteem, met elementen die te vergelijken zijn met TeX, debiandoc-sgml,
TeXinfo, en andere, ontwikkeld door Simon Tatham, de ontwikkelaar van PuTTY.
Zie Locale::Po4a:Halibut voor meer details.
Ini (vermoedelijk experimentele ontleder)
Configuratiebestandsindeling, populair geworden door MS-DOS.
Zie Locale::Po4a::Ini voor meer details.
texinfo (zeer erg experimentele ontleder)
Alle GNU-documentatie wordt in deze indeling geschreven (het is zelfs een vereiste om een officieel
GNU-project te worden). De ondersteuning in po4a voor Locale::Po4a::Texinfo(3pm) zit nog steeds in
zijn beginfase. Gelieve problemen en functieverzoeken te rapporteren.
gemtext (zeer erg experimentele ontleder)
Het oorspronkelijke platte tekstformaat van het Gemini-protocol. De extensie ".gmi" wordt vaak
gebruikt. Ondersteuning voor deze module in po4a staat nog in zijn kinderschoenen. Als u iets vindt,
dien dan een bugrapport of een functieverzoek in.
Andere ondersteunde indelingen
Po4a kan ook overweg met enkele meer zeldzame of gespecialiseerde indelingen, zoals de documentatie
over compilatieopties voor de 2.4+ Linux-kernels (Locale::Po4a::KernelHelp) of de diagrammen die door
het programma dia (Locale::Po4a:Dia) geproduceerd worden. Een nieuwe indeling toevoegen is vaak erg
gemakkelijk en de belangrijkste taak bestaat erin een ontleder aan te brengen voor de beoogde
indeling. Zie Locale::Po4a::TransTractor(3pm) voor meer informatie hierover.
Niet-ondersteunde indelingen
Jammer genoeg biedt po4a nog geen ondersteuning voor verschillende documentaie-indelingen. Voor vele
zou po4a makkelijk ondersteuning kunnen bieden. Het betreft indelingen die niet enkel voor
documentatie gebruikt worden, zoals pakketbeschrijvingen (deb en rpm), vragen van
pakketinstallatiescripts, changelogs van pakketten en alle gespecialiseerde bestandsformaten welke
gebruikt worden door programma's zoals spelscenario's en wine-bronbestanden.
Het gebruik van po4a
De eenvoudigste manier om dit gereedschap in uw project te gebruiken is door een configuratiebestand te
schrijven voor het programma po4a en alleen met dit programma te interageren. Raadpleeg de documentatie
in po4a(1). De rest van deze sectie geeft meer details voor gevorderde gebruikers van po4a die hun
inzicht willen verdiepen.
Gedetailleerd schema van de po4a-werkstroom
Zorg ervoor dat u po4a(1) leest om een vereenvoudigd overzicht te krijgen van de po4a-werkstroom vóór u
aan deze overdreven gedetailleerde sectie begint. Kom naar hier terug als u het volledige schrikwekkend
plaatje wilt zien, met bijna alle details.
In het volgende schema is hoofddocument.doc een voorbeeldnaam voor de te vertalen documentatie; XX.doc is
hetzelfde document, vertaald in taal XX, terwijl doc.XX.po de vertaalcatalogus van dat document is in
taal XX. Auteurs van documentatie zullen zich hoofdzakelijk bezighouden met hoofddocument.doc (dit kan
een man-pagina zijn, een XML-document, een AsciiDoc-bestand, enz.). De vertalers zullen zich
hoofdzakelijk bezighouden met het PO-bestand, terwijl de eindgebruikers uitsluitend het bestand XX.doc
zullen zien.
Overgangen met vierkante haakjes zoals "[po4a werkt po bij]" vertegenwoordigen de uitvoering van een
po4a-tool, terwijl overgangen met accolades zoals "{update hoofddocument.doc}" een handmatige wijziging
van de projectbestanden vertegenwoordigen.
hoofddocument.doc
|
V
+<-----<----+<-----<-----<--------+------->-------->-------+
: | | :
{vertaling} | {update van hoofddocument.doc} :
: | | :
XX.doc | V V
(facultatief) | hoofddocument.doc ->-------->------>+
: | (nieuw) |
V V | |
[po4a-gettextize] doc.XX.po -->+ | |
| (oud) | | |
| ^ V V |
| | [po4a werkt po bij] |
V | | V
vertaling.pot ^ V |
| | doc.XX.po |
| | (onnauwkeurig) |
{vertaling} | | |
| ^ V V
| | {handmatig bewerken} |
| | | |
V | V V
doc.XX.po --->---->+<---<-- doc.XX.po addendum hoofddocument.doc
(initieel) (up-to-date) (facultatief) (up-to-date)
: | | |
: V | |
+----->----->----->------> + | |
| | |
V V V
+------>-----+------<------+
|
V
[po4a updates vertalingen]
|
V
XX.doc
(up-to-date)
Nogmaals, dit schema is veel te ingewikkeld. Raadpleeg po4a(1) voor een vereenvoudigd overzicht.
Het linkerdeel laat zien hoe po4a-gettextize(1) kan worden gebruikt om een bestaand vertaalproject te
converteren naar de po4a-infrastructuur. Dit script gebruikt een origineel document en zijn vertaalde
tegenhanger en tracht het overeenkomstige PO-bestand te bouwen. Een dergelijke handmatige conversie is
nogal omslachtig (zie de documentatie over po4a-gettextize(1) voor meer details), maar ze moet slechts
eenmaal gebruikt worden om uw bestaande vertalingen om te zetten. Indien u geen te converteren
vertalingen heeft, kunt u dit vergeten en u concentreren op het rechterdeel van het schema.
In de rechterbovenhoek wordt de actie van de oorspronkelijke auteur afgebeeld, welke de documentatie
bijwerkt. Het middelste rechterdeel geeft de automatische updates van vertaalbestanden weer. Het nieuwe
materiaal wordt geëxtraheerd en vergeleken met de bestaande vertaling. De vorige vertaling wordt gebruikt
voor de delen welke niet gewijzigd werden, terwijl de gedeeltelijk gewijzigde delen gekoppeld worden aan
de vorige vertaling met de aanduiding "fuzzy" (onnauwkeurig), hetgeen aangeeft dat de vertaling moet
bijgewerkt worden. Nieuw of grondig gewijzigd materiaal blijft onvertaald.
Vervolgens geeft het blok handmatig bewerken de actie van de vertalers weer, welke de PO-bestanden
wijzigen om te voorzien in een vertaling voor elk origineel tekstfragment en alinea. Dit kan gebeuren met
een specifieke editor, zoals de GNOME Translation Editor, KDE's Lokalize of poedit, of met een online
lokalisatieplatform, zoals weblate of pootle. Het resultaat van de vertaling is een aantal PO-bestanden,
één per taal. Raadpleeg de gettext-documentatie voor meer details.
Het onderste deel van de afbeelding toont hoe po4a een vertaald brondocument creëert uit het originele
document hoofddocument.doc en de vertaalcatalogus doc.XX.po die door de vertalers bijgewerkt werd. De
structuur van het document wordt hergebruikt, terwijl de originele inhoud vervangen wordt door de
vertaalde tegenhanger. Facultatief kan een addendum gebruikt worden om aan de vertaling extra tekst toe
te voegen. Dit wordt vaak gebruikt om de naam van de vertaler toe te voegen aan het uiteindelijke
document. Zie hieronder voor details.
Wanneer het aanroepen wordt, werkt po4a zowel de vertaalbestanden als de vertaalde documentatiebestanden
automatisch bij.
Een nieuw vertaalproject starten
Als u vanaf nul begint, hoeft u alleen maar een configuratiebestand voor po4a te schrijven en u bent
klaar. De relevante sjablonen worden aangemaakt voor de ontbrekende bestanden, zodat uw medewerkers uw
project naar hun taal kunnen vertalen. Raadpleeg po4a(1) voor een handleiding waarmee u snel aan de slag
kunt en voor alle details.
Als u een bestaande vertaling heeft, d.w.z. een documentatiebestand dat handmatig is vertaald, kunt u de
inhoud ervan in uw po4a-werkstroom integreren met behulp van po4a-gettextize. Deze taak is een beetje
omslachtig (zoals beschreven in de manpagina van het gereedschap), maar zodra uw project is geconverteerd
naar de po4a-werkstroom, wordt alles automatisch bijgewerkt.
De vertalingen en documenten bijwerken
Eenmaal ingesteld, is het aanroepen van po4a voldoende om zowel de vertalings-PO-bestanden als de
vertaalde documenten bij te werken. U kunt "--no-translations" doorgeven aan po4a om de vertalingen niet
bij te werken (dus alleen de PO-bestanden bij te werken) of "--no-update" om de PO-bestanden niet bij te
werken (dus alleen de vertalingen bij te werken). Dit komt ongeveer overeen met de individuele scripts
po4a-updatepo en po4a-translate die nu verouderd zijn (zie "Waarom zijn de individuele scripts verouderd"
in de FAQ hieronder).
Addenda gebruiken om extra tekst toe te voegen aan vertalingen
Het toevoegen van nieuwe tekst aan de vertaling is waarschijnlijk het enige dat op de lange termijn
gemakkelijker is wanneer u bestanden handmatig vertaalt :). Dit gebeurt wanneer u een extra onderdeel
wilt toevoegen aan het vertaalde document, waarvoor in het originele document geen overeenkomstige inhoud
bestaat. Het klassieke toepassingsgebied is erkenning geven aan het vertaalteam en aangeven hoe
vertaalspecifieke problemen gemeld kunnen worden.
Met po4a moet u addendum-bestanden opgeven, die conceptueel beschouwd kunnen worden als patches die na
verwerking toegepast worden op het gelokaliseerde document. Elk addendum moet als apart bestand
aangereikt worden. De indeling ervan verschilt evenwel erg van klassieke patches. De eerste regel is een
header-regel, die het invoegpunt van het addendum definieert (met een helaas cryptische syntaxis -- zie
hieronder), terwijl de rest van het bestand woordelijk toegevoegd wordt op de aangegeven positie.
De header-regel moet beginnen met de tekst PO4A-HEADER:, gevolgd door een door puntkomma's gescheiden
lijst van I <sleutel> B <=> I <waarde> velden.
Bijvoorbeeld, de volgende header declareert een addendum dat helemaal aan het einde van de vertaling
geplaatst moet worden.
PO4A-HEADER: mode=eof
De zaken zijn complexer wanneer u de extra inhoud wilt toevoegen in het midden van het document. De
volgende header declareert bijvoorbeeld een addendum dat ingevoegd moet worden na de XML-sectie welke het
tekstfragment "Over dit document" bevat in de vertaling.
PO4A-HEADER: position=About this document; mode=after; endboundary=</section>
Wanneer po4a tracht een addendum toe te passen, zoekt het in de praktijk naar de eerste regel die
overeenkomt met het "position"-argument (dit kan een reguliere expressie zijn). Vergeet niet dat po4a
hier rekening houdt met het vertaalde document. Deze documentatie is in het Nederlands (en de originele
versie ervan in het Engels), maar uw regel zou er waarschijnlijk als volgt moeten uitzien, indien u van
plan bent een addendum toe te passen op de Franse vertaling van het document.
PO4A-HEADER: position=À propos de ce document; mode=after; endboundary=</section>
Nadat in het doeldocument de "position" gevonden werd, zoekt po4a naar de eerstvolgende regel na deze
"position" welke overeenkomt met de opgegeven "endboundary". Het addendum wordt ingevoegd net na deze
regel (omdat we een endboundary opgaven, d.w.z. een begrenzing die de huidige sectie afsluit).
Exact hetzelfde effect kan bekomen worden met de volgende header, die gelijkwaardig is:
PO4A-HEADER: position=Over dit document; mode=after; beginboundary=<section>
Hier zoekt po4a naar de eerste regel die overeenkomt met "<section>" na de regel die overeenkomt met
"Over dit document" in de vertaling en voegt het addendum toe voor die regel, omdat we een beginboundary
opgegeven hebben, d.w.z. een begrenzing welke het begin van de volgende sectie markeert. Deze header-
regel vereist dus dat het addendum geplaatst wordt na de sectie waarin "Over dit document" voorkomt, en
informeert po4a dat een sectie begint met een regel welke de tag "<section>" bevat. Dit is het equivalent
van het vorige voorbeeld, want wat u eigenlijk wilt is het addendum in te voegen na "</section>" en voor
"<section>".
U kunt de invoeging mode ook instellen op de waarde "before", met een vergelijkbare semantiek: het
combineren van "mode = before" met een "endboundary" zal het addendum juist na de overeenkomstige
begrenzing plaatsen, welke de laatst mogelijke begrenzing is voor de "position". De combinatie van "mode
= before" met een "beginboundary" zal het addendum juist voor de overeenkomstige begrenzing plaatsen,
welke de laatst mogelijke grensregel is vóór de "position".
Modus | Soort begrenzing | Gebruikte begrenzing | Invoegpunt tegenover begrenzing
========|===============|========================|=========================================
'before'| 'endboundary' | laatste voor 'position' | Juist na de geselecteerde begrenzing
'before'|'beginboundary'| laatste voor 'position' | Juist voor de geselecteerde begrenzing
'after' | 'endboundary' | eerste na 'position' | Juist na de geselecteerde begrenzing
'after' |'beginboundary'| eerste na 'position' | Juist voor de geselecteerde begrenzing
'eof' | (geen) | n.v.t. | Einde van het bestand
Aanwijzingen en kneepjes in verband met addenda
• Denk eraan dat dit reguliere expressies zijn. Indien u bijvoorbeeld het einde van een nroff-sectie
wilt opzoeken welke eindigt met de regel ".fi", moet u niet ".fi" gebruiken als endboundary, omdat
dit een overeenkomst zal opleveren met "the [fi]le", hetgeen duidelijk niet is wat u verwacht. De
juiste endboundary in dit geval is: "^\.fi$".
• Witruimte IS belangrijk in de inhoud van de "position" en de begrenzingen. En dus zijn de twee
volgende zinnen verschillend. De tweede zal slechts gevonden worden als er in het vertaalde document
voldoende nakomende spaties zijn.
PO4A-HEADER: position=Over dit document; mode=after; beginboundary=<section>
PO4A-HEADER: position=Over dit document ; mode=after; beginboundary=<section>
• Hoewel ruwweg zou kunnen aangenomen worden dat deze contextzoekfunctie werkt op elke regel van het
vertaalde document, werkt het in feite op de interne gegevensreeks van het vertaalde document. Deze
interne gegevensreeks kan een tekst zijn die een volledige alinea beslaat en meerdere regels bevat,
of kan ook enkel een XML-tag zijn. Het exacte invoegpunt van het addendum moet voor of na de interne
gegevensreeks komen en kan er niet binnenin liggen.
• Geef het argument "-vv" op aan po4a om te zien hoe de addenda aan de vertaling worden toegevoegd. Dit
kan ook behulpzaam zijn voor het uitvoeren van po4a in debug-modus om de exacte gegevensreeks te
bekijken wanneer het addendum niet toegevoegd wordt.
Voorbeelden van addenda
• Indien u na de volgende nroff-sectie iets wilt toevoegen:
.SH "AUTEURS"
U moet een benadering in twee stappen selecteren door mode = after in te stellen. Vervolgens moet u
de zoekopdracht beperken tot de regel na AUTEURS met de reguliere expressie voor het argument
position. Daarna moet u het begin van de volgende sectie (d.w.z. ^\.SH) laten opzoeken met de
reguliere expressie voor het argument beginboundary. Het is te zeggen:
PO4A-HEADER:mode=after;position=AUTEURS;beginboundary=\.SH
• Indien u iets wilt toevoegen vlak na een bepaalde regel (bijv. na de regel "Copyright Grote Kerel"),
gebruik dan een position die met deze regel overeenkomt, mode=after en geef een beginboundary op die
met om het even welke regel overeenkomt.
PO4A-HEADER:mode=after;position=Copyright Grote Kerel, 2004;beginboundary=^
• Indien u iets wilt toevoegen aan het einde van het document, geef dan een position op die overeenkomt
met om het even welke regel van uw document (maar enkel één regel, omdat po4a niet zal aanvaarden dat
de position niet met één enkele regel overeenkomt), en geef een endboundary op die met niets
overeenkomt. Gebruik hier geen eenvoudige tekenreeks, zoals "EOF", maar geef de voorkeur aan die
welke minder kans maken om in uw document voor te komen.
PO4A-HEADER:mode=after;position=Over dit document;beginboundary=VerzonnenPo4aBegrenzing
Een meer gedetailleerd voorbeeld
Origineel document (POD-indeling):
|=head1 NAAM
|
|dummy - een dummy-programma
|
|=head1 AUTEUR
|
|ik
Dan zal het volgende addendum ervoor zorgen dat een sectie (in het Frans) over de vertaler toegevoegd
wordt aan het eind van het bestand ("TRADUCTEUR" in het Frans betekent "VERTALER", en "moi" betekent
"ik").
|PO4A-HEADER:mode=after;position=AUTEUR;beginboundary=^=head
|
|=head1 TRADUCTEUR
|
|moi
|
Om uw addendum voor de AUTEUR te plaatsen, gebruikt u de volgende header:
PO4A-HEADER:mode=after;position=NAAM;beginboundary=^=head1
Dit werkt omdat de volgende regel die overeenkomt met de beginboundary "/^=head1/" na de sectie "NAME"
(vertaald als "NAAM" in het Nederlands), die is welke de auteurs vermeldt. Dus zal het addendum tussen de
beide secties geplaatst worden. Merk op dat indien later een andere sectie toegevoegd wordt tussen de
secties NAAM en AUTEUR, po4a de addenda ten onrechte zal plaatsen voor de nieuwe sectie.
Om dit te vermijden, kunt u hetzelfde bereiken met behulp van mode=before:
PO4A-HEADER:mode=before;position=^=head1 AUTEUR
Hoe werkt dit?
Dit hoofdstuk geeft u een kort overzicht van de binnenkant van po4a, zodat u met meer zelfvertrouwen ons
kunt helpen het te onderhouden en te verbeteren. Het kan u ook helpen te verstaan waarom het niet doet
wat u verwachtte en hoe u uw problemen kunt oplossen.
TransTractors en projectarchitectuur
In de kern van het po4a-project is de klasse Locale::Po4a::TransTractor(3pm) de gemeenschappelijke
voorouder van alle po4a-ontleders. Deze vreemde naam komt door het feit dat het tegelijk belast is met de
vertaling van het document en het extraheren van tekstfragmenten.
Meer formeel neemt het als invoer een te vertalen document plus een PO-bestand dat de te gebruiken
vertalingen bevat en produceert het twee aparte uitvoerbestanden: een ander PO-bestand (als resultaat van
de extractie van vertaalbare tekstfragmenten uit het invoerdocument) en een vertaald document (met
dezelfde structuur als het invoerdocument, maar waarin alle vertaalbare tekstfragmenten vervangen werden
met inhoud uit het invoer-PO-bestand). Hier volgt een grafische voorstelling ervan:
Invoerdocument --\ /---> Uitvoerdocument
\ TransTractor:: / (vertaald)
+-->-- parse() --------+
/ \
Invoer-PO --------/ \---> Uitvoer-PO
(geëxtraheerd)
Dit kleine botje vormt de kern van de hele po4a-architectuur. Als u zowel invoer verstrekt als de
uitvoer-PO negeert, krijgt u po4a-translate. Als u in plaats daarvan het uitvoerdocument negeert, krijgt
u po4a-updatepo. Het programma po4a gebruikt een eerste TransTractor om een actueel uitvoer-POT-bestand
te verkrijgen (waarbij de uitvoerdocumenten buiten beschouwing worden gelaten), roept msgmerge -U aan om
de vertaal-PO-bestanden op schijf bij te werken en bouwt een tweede TransTractor met deze bijgewerkte PO-
bestanden om de uitvoerdocumenten bij te werken. Kortom, po4a biedt een totaaloplossing om bij te werken
wat bijgewerkt moet worden, met behulp van één enkel configuratiebestand.
po4a-gettextize gebruikt ook twee TransTractors, maar op een andere manier: het bouwt één TransTractor
per taal en bouwt vervolgens een nieuw PO-bestand met de msgid's van het originele document als msgid's,
en de msgid's van het vertaalde document als msgstr's. Er is veel zorg nodig om te verzekeren dat de
tekenreeksen waartussen op deze manier een overeenkomst gevonden wordt ook daadwerkelijk overeenkomen,
zoals beschreven in po4a-gettextize(1).
Indelingsspecifieke ontleders
Alle po4a-indelingsontleders zijn bovenop de TransTractor geïmplementeerd. Sommige zijn heel eenvoudig,
zoals die van Text, Markdown en AsciiDoc. Ze laden de regels één voor één met behulp van
TransTractor::shiftline(), verzamelen de inhoud van de alinea's of wat dan ook. Zodra een tekenreeks
volledig is ontleed, gebruikt de ontleder TransTractor::translate() om (1) deze tekenreeks toe te voegen
aan het uitvoer-PO-bestand en (2) de vertaling op te halen uit het invoer-PO-bestand. De ontleder duwt
het resultaat vervolgens naar het uitvoerbestand met behulp van TransTractor::pushline().
Sommige andere ontleders zijn complexer omdat ze afhankelijk zijn van een externe ontleder om het
invoerdocument te analyseren. De Xml-, HTML-, SGML- en Pod-ontleders zijn gebouwd bovenop SAX-ontleders.
Ze declareren terugroepfuncties naar gebeurtenissen zoals "Ik heb een nieuwe titel gevonden met de
volgende inhoud" om het uitvoerdocument bij te werken en POT-bestanden uit te voeren op basis van de
invoerinhoud met behulp van TransTractor::translate() en "TransTractor::pushline ()". De Yaml-ontleder is
vergelijkbaar maar anders: deze serialiseert een datastructuur geproduceerd door de ontleder YAML::Tiny.
Dit is de reden waarom de Yaml-module van po4a de referentieregels niet kan declareren: de locatie van
elke tekenreeks in het invoerbestand wordt niet bijgehouden door de ontleder en dus kunnen we alleen
"$bestandsnaam:1" opgeven als de locatie van een tekenreeks. De SAX-georiënteerde ontleders gebruiken
globale variabelen en andere trucs om de bestandsnaam en regelnummers van referenties op te slaan.
Een specifiek probleem ontstaat door bestandscoderingen en BOM-markeringen. Eenvoudige ontleders kunnen
dit probleem negeren omdat het wordt afgehandeld door TransTractor::read() (intern gebruikt om de regels
van een invoerdocument op te halen), maar de modules die afhankelijk zijn van een externe ontleder moeten
ervoor zorgen dat alle bestanden worden gelezen met een geschikte PerlIO-decoderingslaag. Het
eenvoudigste is om het bestand zelf te openen en een bestandsaanduiding of rechtstreeks de volledige
tekenreeks mee te geven aan de externe ontleder. Kijk eens naar Pod::read() en Pod::parse() voor een
voorbeeld. De inhoud die wordt gelezen door de TransTractor wordt genegeerd, maar een nieuwe
bestandsaanduiding wordt doorgegeven aan de externe ontleder. Het belangrijke onderdeel is de modus
"<:encoding($charset)" die wordt doorgegeven aan de perl-functie open().
Po-objecten
De klasse Locale::Po4a::Po(3pm) is verantwoordelijk voor het laden en gebruiken van PO- en POT-bestanden.
Kortom, u kunt een bestand lezen, vermeldingen toevoegen, vertalingen ophalen met de gettext()-methode,en
de PO naar een bestand schrijven. Meer geavanceerde functies, zoals het samenvoegen van een PO-bestand
met een POT-bestand of het valideren van een bestand, worden respectievelijk aan msgmerge en msgfmt
gedelegeerd.
Meewerken aan po4a
Zelfs als u nog nooit hebt bijgedragen aan een openbronproject, bent u welkom: we zijn bereid om u hier
te helpen en te begeleiden. po4a wordt tegenwoordig het best onderhouden door zijn gebruikers. Omdat we
te weinig mankracht hebben, proberen we het project gastvrij te maken door de documentatie en de
automatische tests te verbeteren, zodat u met vertrouwen kunt bijdragen aan het project. Raadpleeg het
bestand CONTRIBUTING.md voor meer details.
Openbronprojecten die po4a gebruiken
Hier volgt een zeer gedeeltelijke lijst met projecten die po4a in productie gebruiken voor hun
documentatie. Indien u wenst dat uw project wordt toegevoegd aan de lijst, stuur dan gewoon een e-mail
(of een Merge Request).
• adduser (man): gereedschap voor het beheer van gebruikers en groepen.
• apt (man, docbook): pakketbeheerder in Debian.
• aptitude (docbook, svg): terminalgeoriënteerd pakketbeheerhulpmiddel voor Debian
• F-Droid website <https://gitlab.com/fdroid/fdroid-website> (markdown): installeerbare catalogus van
FOSS (Free and Open Source Software - Vrije en openbronsoftware) toepassingssoftware voor het
Android-platform.
• git <https://github.com/jnavila/git-manpages-l10n> (asciidoc): gedistribueerd versiebeheersysteem
voor het volgen van wijzigingen in de broncode.
• Linux man-pagina's <https://salsa.debian.org/manpages-l10n-team/manpages-l10n> (man)
Dit project voorziet in een infrastructuur voor het vertalen van veel man-pagina's naar verschillende
talen, klaar om geïntegreerd te worden in verschillende belangrijke distributies (Arch Linux, Debian
en derivativen, Fedora).
• Stellarium <https://github.com/Stellarium/stellarium> (HTML): een vrij openbronplanetarium voor uw
computer. po4a wordt gebruikt om de beschrijving van de lucht en de hemellichamen in verschillende
culturen, te vertalen.
• Jamulus <https://jamulus.io/> (markdown, yaml, HTML): een FOSS-toepassing voor online jammen in
realtime. De documentatie van de website wordt in meerdere talen onderhouden met po4a.
• Ander uit te zoeken item: <https://gitlab.com/fdroid/fdroid-website/>
<https://github.com/fsfe/reuse-docs/pull/61>
FAQ
Hoe spreekt men po4a uit?
Zelf spreek ik het uit als pouah <https://en.wiktionary.org/wiki/pouah>, wat een Franse klanknabootsing
is die men gebruikt voor bah :) Misschien heb ik een vreemd gevoel voor humor :)
Waarom zijn de afzonderlijke scripts achterhaald?
po4a-updatepo en po4a-translate werden inderdaad uitgefaseerd ten gunste van po4a. De reden is dat,
hoewel po4a kan worden gebruikt als een directe vervanging voor deze scripts, men er behoorlijk veel
codeduplicatie in aantreft. Individuele scripts bestaan uit ongeveer 150 regels code, terwijl het
programma po4a 1200 regels code bevat. Deze code doet dus veel meer dan de interne onderdelen die beide
gemeenschappelijk hebben. Het dupliceren van code resulteert in bugs die in beide versies voorkomen en
waarvoor twee oplossingen nodig zijn. Een voorbeeld van een dergelijke duplicatie zijn de bugs #1022216
in Debian en de kwestie #442 in GitHub die exact dezelfde oplossing hadden, maar één in po4a en de andere
po4a-updatepo.
Op de lange termijn zou ik de individuele scripts willen laten vallen en slechts één versie van deze code
behouden. Het is zeker dat de individuele scripts niet meer zullen worden verbeterd. Dus alleen po4a zal
nog nieuwe functionaliteit krijgen. Dat gezegd hebbende, is er geen sprake van urgentie wat de
uitfasering betreft. Ik ben van plan de individuele scripts zo lang mogelijk te behouden, en in ieder
geval tot 2030. Mocht uw project in 2030 nog steeds po4a-updatepo en po4a-translate gebruiken, dan heeft
u mogelijk een probleem.
We kunnen op een gegeven moment ook de uitfasering van deze scripts annuleren, als een herwerking de
codeduplicatie tot nul kan reduceren. Als u een idee heeft (of beter, een patch), is uw hulp welkom.
Hoe zit het met de andere vertaalhulpmiddelen voor documentatie die gebruik maken van gettext?
Er zijn er een paar. Hier is een mogelijk onvolledige lijst, en er verschijnen meer hulpmiddelen aan de
horizon.
poxml
Dit gereedschap werd ontwikkeld door mensen van KDE om DocBook XML te verwerken. Voor zover ik weet
was dit het eerste programma dat te vertalen tekstfragmenten uit documentatie extraheerde naar PO-
bestanden en deze na vertaling terug injecteerde.
Het kan enkel XML verwerken, en enkel een specifieke DTD. Ik ben erg ongelukkig met de verwerking van
lijsten welke terechtkomen in één grote msgid. Wanneer de lijst groot wordt, is het moeilijker die
brok door te slikken.
po-debiandoc
Dit door Denis Barbier gemaakt programma is een soort voorloper van de SGML-module van po4a, waardoor
het min of meer achterhaald werd. Zoals de naam het zegt, verwerkt het enkel de DebianDoc DTD,
hetgeen min of meer een achterhaalde DTD is.
xml2po.py
Wordt gebruikt door het GIMP-documentatieteam sinds 2004. Het werkt redelijk goed, zij het, zoals de
naam al doet vermoeden, alleen met XML-bestanden, en het heeft speciaal geconfigureerde makefiles
nodig.
Sphinx
Ook het documentatieproject van Sphinx maakt veelvuldig gebruik van gettext om zijn vertalingen te
beheren. Helaas werkt dit hulpmiddel slechts voor enkele tekstformaten, voor rest en voor markdown,
hoewel het misschien wel het enige hulpmiddel is dat dit beheren van het hele vertaalproces op zich
neemt.
De belangrijkste voordelen van po4a tegenover hen zijn het gemak waarmee extra inhoud toegevoegd kan
worden (wat bij deze andere hulpmiddelen nog moeilijker is) en de mogelijkheid een gettextize-procedure
uit te voeren.
SAMENVATTING van de voordelen van een op gettext gebaseerde benadering
• De vertalingen worden niet samen met het origineel opgeslagen, wat het mogelijk maakt na te gaan of
vertalingen verouderd beginnen te raken.
• De vertalingen worden in aparte bestanden opgeslagen, wat interferentie tussen vertalers van
verschillende talen voorkomt, zowel wanneer deze hun patch indienen als bij de keuze van de
tekstcodering van de bestanden.
• Intern is het gebaseerd op gettext (maar po4a biedt een heel eenvoudige interface, zodat u de interne
werking niet moet kennen om het te gebruiken). Op die manier moeten we het wiel niet terug uitvinden,
en omdat dit gereedschap zo ruim gebruikt wordt, mogen we aannemen dat het min of meer vrij van fouten
is.
• Voor de eindgebruiker verandert er niets (behalve het feit dat vertalingen hopelijk beter onderhouden
zullen worden). Het resulterende documentatiebestand dat verspreid wordt, is exact hetzelfde.
• Vertalers moeten geen nieuwe bestandsyntaxis leren en hun favoriete editor voor PO-bestanden (zoals de
PO-modus in Emacs, Lokalize of Gtranslator) voldoet perfect.
• gettext biedt een eenvoudige manier om statistieken te bekomen over het gepresteerde werk, over wat
nazicht en een update nodig heeft en over wat er nog moet gebeuren. Enkele voorbeelden zijn te vinden
op deze adressen:
- https://docs.kde.org/stable5/en/kdesdk/lokalize/project-view.html
- http://www.debian.org/intl/l10n/
Maar niet alles is rozengeur en deze aanpak heeft ook enkele nadelen waarmee we moeten omgaan.
• Addenda zijn op het eerste gezicht wat vreemd.
• Het is niet mogelijk om de vertaalde tekst naar uw smaak aan te passen, zoals hier een paragraaf
opsplitsen en er daar twee andere samenvoegen. Maar in zekere zin moet het hoe dan ook als een bug
gemeld worden, wanneer er een probleem is met het origineel.
• Zelfs met een gemakkelijke interface blijft het een nieuw gereedschap dat mensen moeten leren
gebruiken.
Een van mijn dromen is om po4a op een of andere manier te integreren in Gtranslator of Lokalize.
Wanneer een documentatiebestand geopend wordt, zouden de tekstfragmenten automatisch geëxtraheerd
worden en een vertaald bestand + po-bestand zouden naar schijf geschreven worden. Indien we erin zouden
slagen een MS Word(TM)-module te ontwikkelen (of minstens een RTF-module), zouden zelfs professionele
vertalers er gebruik van maken.
ZIE OOK
• De documentatie over het alles-in-één gereedschap dat u zou moeten gebruiken: L <po4a (1)>.
• De documentatie van de individuele po4a-scripts: po4a-gettextize(1), po4a-updatepo(1),
po4a-translate(1), po4a-normalize(1).
• De extra ondersteunende scripts: msguntypot(1), po4a-display-man(1), po4a-display-pod(1).
• De ontleders (parsers) voor elke indeling, in het bijzonder om te zien welke opties voor elke van hen
mogelijk zijn: 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).
• De implementatie van de basisinfrastructuur:: Locale::Po4a::TransTractor(3pm) (in het bijzonder van
belang om de organisatie van de code te begrijpen), Locale::Po4a::Chooser(3pm),
Locale::Po4a::Po(3pm), Locale::Po4a::Common(3pm). Bekijk ook het bestand CONTRIBUTING.md in de
broncodeboom.
AUTEURS
Denis Barbier <barbier,linuxfr.org>
Martin Quinson (mquinson#debian.org)
perl v5.38.2 2024-08-28 PO4A.7(1)