Snel aan de slag - Beknopte handleiding

Laten we aannemen dat u een programma onderhoudt met de naam foo dat een manpagina man/foo.1 heeft, geschreven in het Engels (de werktaal in de meeste open-bronprojecten, maar po4a kan van of naar elke taal gebruikt worden). Enige tijd geleden zorgde iemand voor een Duitse vertaling genaamd man/foo.de.1 en verdween. Dit is een probleem omdat u net een bugrapport hebt gekregen waarin staat dat uw documentatie ernstig misleidende informatie bevat die in alle talen moet worden verbeterd, maar u spreekt geen Duits, dus u kunt alleen het origineel aanpassen, niet de vertaling. Nu wil een andere medewerker ook een bijdrage leveren met een vertaling naar het Japans, een taal die u evenmin beheerst.

Dan is het tijd om uw documentatie om te zetten naar po4a om uw nachtmerries over documentatieonderhoud op te lossen. U wilt de documentatie bijwerken wanneer dat nodig is, u wilt het werk van uw collega-vertalers verlichten, en u wilt ervoor zorgen dat uw gebruikers nooit verouderde en dus misleidende documentatie te zien krijgen.

Deze omzetting omvat twee stappen: het opzetten van de po4a-infrastructuur en het converteren van de vorige Duitse vertaling om het eerdere werk te redden. Dit laatste deel wordt als volgt gedaan met po4a-gettextize. Zoals beschreven in de documentatie van po4a-gettextize(1), is dit proces zelden volledig automatisch, maar als het eenmaal is voltooid, kan het de.po-bestand met de Duitse vertaling worden geïntegreerd in uw po4a-werkstroom.

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

Laten we nu po4a configureren. Met de juiste bestandsopmaak zou uw configuratiebestand zo eenvoudig als dit kunnen zijn:

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

Het geeft aan dat alle PO-bestanden (die het werk van de vertalers bevatten) in de map man/po4a/ staan, en dat u slechts één hoofdbestand hebt, man/foo.1. Als u meerdere hoofdbestanden had, dan zou u verschillende regels hebben die lijken op de tweede. Elk van die regels geeft ook aan waar de corresponderende vertaalbestanden moeten worden geschreven. Hier staat de Duitse vertaling van man/foo.1 in man/vertaald/foo.de.1.

Het laatste dat we nodig hebben om de configuratie van po4a te voltooien, is een POT-bestand met het sjabloonmateriaal dat moet worden gebruikt om een nieuwe vertaling te starten. Maak gewoon een leeg bestand met de extensie .pot in de opgegeven po_directory (bijv. man/po4a/foo.pot), en po4a vult het met de verwachte inhoud.

Hier volgt een overzicht van de bestanden in deze opstelling:

├── man/
│   ├── foo.1        <- De originele manpagina, in het Engels
│   ├── po4a/
│   │   ├── de.po    <- De Duitse PO-vertaling, afkomstig van gettextisatie
│   │   └── foo.pot  <- Het POT-sjabloon voor toekomstige vertalingen (eerst leeg)
│   └── translated/  <- Map waar de vertalingen worden gemaakt
└── po4a.cfg         <- Het configuratiebestand.

Eenmaal ingesteld, zal het uitvoeren van po4a uw documentatie ontleden, het POT-sjabloonbestand bijwerken, het gebruiken om de PO-vertaalbestanden bij te werken, en deze gebruiken om de documentatievertaalbestanden bij te werken. Alles in één commando:

po4a --verbose po4a.cfg

Dit is het. po4a is nu volledig geconfigureerd. Zodra u uw fout in man/foo.1 hebt hersteld, zal de gewraakte paragraaf in de Duitse vertaling worden vervangen door de gecorrigeerde tekst in het Engels. Het mengen van talen is niet optimaal, maar het is de enige manier om fouten in vertalingen die u niet eens begrijpt te verwijderen en ervoor te zorgen dat de aan de gebruikers gepresenteerde inhoud nooit misleidend is. Het bijwerken van de Duitse vertaling is ook veel gemakkelijker in het overeenkomstige PO-bestand, zodat de taalvermenging mogelijk niet lang zal duren. Tenslotte, als een Japanse vertaler wil bijdragen met een nieuwe vertaling, moet deze de naam foo.pot hernoemen naar ja.po en de vertaling voltooien. Eens u dat bestand gekregen heeft, plaatst u het gewoon in man/po4a/po/. Wanneer u po4a opnieuw uitvoert, zal een vertaalde pagina tevoorschijn komen als man/translated/foo.jp.1 (op voorwaarde dat er voldoende inhoud is vertaald).

Opties die de POT-header wijzigen

--porefs type

Het referentieformaat specificeren. Het argument type kan één van de volgende zijn: never om geen enkele referentie te produceren, file om enkel het bestand zonder het lijnnummer te specificeren, counter om het regelnummer te vervangen door een oplopende teller, en full om volledige referenties op te nemen (standaard: full).

--wrap-po no|newlines|getal (standaard: 76)

Specificeren hoe de regelafbreking voor po-bestanden er moet uitzien. Dit geeft de keuze tussen bestanden met een mooie regelafbreking, die echter kunnen leiden tot git-conflicten en bestanden die makkelijker automatisch te behandelen zijn, maar voor mensen moeilijker leesbaar.

Vanouds brak de gettext-suite uit cosmetische overwegingen de regels van po-bestanden af bij de 77e kolom. Deze optie specificeert het gedrag van po4a. Indien dit ingesteld wordt op een numerieke waarde, zal po4a de regels van het po-bestand afbreken na deze kolom en na regeleinden die in de inhoud voorkomen. Indien dit ingesteld wordt op newlines, zal po4a de msgid en msgstr enkel afbreken na regeleinden die in de inhoud voorkomen. Indien dit ingesteld wordt op no, zal po4a helemaal geen regelafbreking toepassen in het po-bestand. De regelafbreking in het referentiecommentaar gebeurt steeds door het gettext-gereedschap dat we intern gebruiken.

Merk op dat deze optie geen impact heeft op de wijze waarop regelafbreking in msgid en msgstr gebeurt, d.w.z. op hoe einderegels toegevoegd worden aan de inhoud van deze tekstfragmenten.

--master-language

Taal van de bronbestanden die de te vertalen documenten bevatten. Merk op dat alle hoofddocumenten dezelfde taal moeten gebruiken.

--msgid-bugs-address email@adres

Het adres instellen voor het rapporteren van msgid-bugs. Standaard bevatten de gecreëerde POT-bestanden niet het veld Report-Msgid-Bugs-To.

--copyright-holder tekenreeks

Instellen van de copyrighthouder in de POT-header. De standaardwaarde is "Free Software Foundation, Inc."

--package-name tekenreeks

Instellen van de pakketnaam voor de POT-header. Standaard is dat "PACKAGE".

--package-version tekenreeks

Instellen van de pakketversie voor de POT-header. Standaard is dat "VERSION".

Opties om de PO-bestanden te wijzigen

--msgmerge-opt opties

Extra opties voor msgmerge(1).

Opmerking: $lang zal vervangen worden door de huidige taal.

--no-previous

Deze optie verwijdert --previous uit de opties die doorgegeven worden aan msgmerge. Dit is nodig om versies van gettext te ondersteunen, eerder dan 0.16.

--previous

Met deze optie voegt men --previous toe aan de opties die aan msgmerge doorgegeven worden. De optie heeft versie 0.16 of recenter van gettext nodig en is standaard geactiveerd.

De PO- en POT-bestanden vinden

De eenvoudigste manier is om als volgt expliciet het pad op te geven naar het POT-bestand en de PO-bestanden:

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

Dit specificeert eerst het pad naar het POT-bestand, en daarna de paden naar de Nederlandse en Franse PO-bestanden.

Dezelfde informatie kan als volgt geschreven worden om het risico op kopiëren/plakken-fouten te verkleinen:

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

De component $lang wordt automatisch vervangen door gebruik te maken van de opgegeven taallijst. Dit beperkt het risico op een fout van het type kopiëren/plakken wanneer een nieuwe taal toegevoegd wordt.

U kunt dezelfde informatie nog compacter maken door als volgt enkel het pad op te geven naar de map die uw vertaalproject bevat.

[po_directory] man/po/

De opgegeven map moet een aantal PO-bestanden bevatten, elk met een naam XX.po, waarbij "XX" de ISO 639-1-code is van de taal die in dit bestand wordt gebruikt. De map moet ook één enkel POT-bestand bevatten, met als bestandsextensie ".pot". Voor de eerste doorloop mag dit bestand leeg zijn, maar het moet wel bestaan (po4a kan de naam die voor de extensie moet worden gebruikt, niet raden).

Merk op dat u enkel een van beide moet kiezen: "po_directory" of "po4a_paths". Het eerste ("po_directory") is compacter en vermindert nog meer het risico op kopiëren/plakken-fouten, maar dwingt u de verwachte projectstructuur en bestandsnamen te gebruiken. Het tweede ("po4a_paths") is explicieter en wellicht makkelijker leesbaar en wordt aanbevolen als u uw eerste project opzet met po4a.

Centrale of gesplitste PO-bestanden?

Standaard produceert po4a één enkel PO-bestand per doeltaal. Dit bevat de volledige inhoud van uw vertaalproject. Als uw project uitgebreider wordt, kan de omvang van deze bestanden problematisch worden. Indien weblate gebruikt wordt , is het mogelijk specifieke prioriteiten op te geven voor elk vertalingssegment (d.w.z. msgid), zodat de belangrijkste eerst vertaald worden. Nochtans geven sommige vertaalteams er de voorkeur aan de inhoud op te splitsen in verschillende bestanden.

Om één PO-bestand per hoofdbestand te hebben, moet u gewoon op de volgende manier de tekenreeks $master gebruiken in de naam van uw PO-bestanden op de regel "[po4a_paths]".

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

Met deze regel zal po4a afzonderlijke POT- en PO-bestanden produceren voor elk te vertalen document. Bijvoorbeeld, als u 3 documenten en 5 talen heeft, zal dit resulteren in 3 POT-bestanden en 15 PO-bestanden. Deze bestanden worden genoemd zoals in het sjabloon "po4a_paths" gespecificeerd werd, waarbij $master vervangen wordt door de basisnaam van elk te vertalen document. In geval van een naamconflict kunt u het te gebruiken POT-bestand als volgt specificeren met de parameter "pot=".

Deze functionaliteit kan ook worden gebruikt om meerdere vertaalde bestanden te groeperen in hetzelfde POT-bestand. Het volgende voorbeeld levert slechts 2 POT-bestanden op: l10n/po/foo.pot (met het materiaal van foo/gui.xml) en l10n/po/bar.pot (met het materiaal van zowel bar/gui.xml als bar/cli.xml).

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

In gesplitste modus bouwt po4a een tijdelijk compendium op tijdens het bijwerken van de PO-bestanden, om de vertaling met alle PO-bestanden te delen. Indien twee PO-bestanden voor hetzelfde tekstfragment verschillende vertalingen bevatten, zal po4a dit tekstfragment als onnauwkeurig (fuzzy) markeren en beide vertalingen invoegen in alle PO-bestanden die dat tekstfragment bevatten. Wanneer de vertaler de vertaling ontwart, zal deze vertaling automatisch is elk PO-bestand gebruikt worden.

De te vertalen documenten specificeren

U moet ook de documenten die vertaald moeten worden, vermelden. Voor elk hoofdbestand moet u de te gebruiken indelingsontleder opgeven, de locatie van het te produceren vertaalde bestand en facultatief enige configuratie. Bestandsnamen moeten tussen aanhalingstekens worden geplaatst als ze spaties bevatten, ofwel moeten deze gemaskeerd worden met een escape-teken. Hier volgt een voorbeeld:

[type: sgml] "doc/my stuff.sgml"   "fr:doc/fr/mon truc.sgml"   nl:doc/nl/mijn\ spullen.sgml
[type: man] script fr:doc/fr/script.1 nl:doc/nl/script.1
[type: docbook] doc/script.xml fr:doc/fr/script.xml \
            nl:doc/nl/script.xml

Maar ook hier zijn deze complexe regels moeilijk te lezen en aan te passen, bijvoorbeeld bij het toevoegen van een nieuwe taal. Het is veel eenvoudiger om deze zaken als volgt te herorganiseren met behulp van het $lang-sjabloon:

[type: sgml]    doc/my_stuff.sgml $lang:doc/$lang/my_stuff.sgml
[type: man]     script.1          $lang:po/$lang/script.1
[type: docbook] doc/script.xml    $lang:doc/$lang/script.xml

Opties specificeren

Er bestaan twee types opties: po4a-opties zijn standaardwaarden voor de po4a commandoregelopties, terwijl opmaakopties gebruikt worden om het gedrag van de opmaakontleders te beïnvloeden. U zou bijvoorbeeld in uw configuratiebestand kunnen specificeren dat de standaardwaarde voor de commandoregelparameter --keep 50% is in plaats van 80%. Opmaakopties worden gedocumenteerd op de specifieke pagina van iedere ontleedmodule, bijv. Locale::Po4a::Xml(3pm). U zou bijvoorbeeld nostrip kunnen meegeven aan de XML-ontleder om de spaties rond de geëxtraheerde tekstfragmenten niet te laten weghalen.

U kunt deze opties meegeven voor een specifiek hoofdbestand, of zelfs voor een specifieke vertaling van dat bestand met "opt:" of met "opt_XX:" voor de taal "XX". In het volgende voorbeeld wordt de optie nostrip meegegeven aan de XML-ontleder (voor alle talen), terwijl de drempelwaarde tot 0% teruggebracht wordt voor de Franse vertaling (welke dus steeds behouden blijft).

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

Deze configuratieonderdelen moeten in ieder geval aan het einde van de regel staan. Eerst moet de declaratie van bestanden komen, dan het eventuele addendum (zie hierna) en dan pas de opties. Het groeperen van configuratieonderdelen is niet erg belangrijk, omdat elementen intern samengevoegd worden tot tekenreeksen. De volgende voorbeelden zijn allemaal gelijkwaardig:

[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

Merk op dat taalspecifieke opties niet gebruikt worden bij het bouwen van het POT-bestand. Het is bijvoorbeeld niet mogelijk om de optie nostrip mee te geven aan de ontleder wanneer enkel de Franse vertaling wordt gebouwd, omdat het POT-bestand gebruikt wordt om elke taal te updaten. Dus zijn de enige opties die taalspecifiek kunnen zijn, die opties welke gebruikt worden bij het produceren van de vertaling, zoals de optie "--keep".

Configuratiealiassen

De beste manier om dezelfde optie mee te geven aan verschillende bestanden is als volgt een alias voor een type te definiëren. In het volgende voorbeeld wordt de optie "--keep 0" aan iedere Italiaanse vertaling meegegeven met dit "test"-type, welke een uitbreiding is van het "man"-type.

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

U kunt een bestaand type ook uitbreiden door als volgt dezelfde naam te gebruiken voor de alias. Dit wordt niet geïnterpreteerd als een foutieve recursieve definitie.

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

Globale standaardopties

U kunt ook "[options]"-regels gebruiken om opties te definiëren welke voor alle bestanden gebruikt moeten worden, ongeacht hun type.

[options] --keep 20 --option nostrip

Zoals het geval is voor de commandoregelopties, kunt u de parameters die in het configuratiebestand meegegeven worden, afkorten:

[options] -k 20 -o nostrip

Optieprioriteiten

De opties voor alle bronnen worden samengevoegd, zodat de standaardwaarden gemakkelijk kunnen worden overschreven door meer specifieke opties. De volgorde is de volgende:

• "[options]"-regels bieden standaardwaarden die door elke andere bron overschreven kunnen worden.
• Daarna worden aliassen voor types gebruikt. Taalspecifieke instellingen overschrijven die welke van toepassing zijn op alle talen.
• Instellingen welke specifiek zijn voor een bepaald hoofdbestand overschrijven zowel de standaardinstellingen als die welke afkomstig zijn van de type-alias. Ook in dit geval overschrijven taalspecifieke instellingen de globale instellingen.
• Tenslotte overschrijven parameters welke opgegeven worden aan de po4a-commandoregel, eventuele instellingen uit het configuratiebestand.

Voorbeeld

Hier volgt een voorbeeld dat laat zien hoe u de spaties en aanhalingstekens moet citeren:

[po_directory] man/po/

[options] --master-charset UTF-8

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

Addendum: extra inhoud toevoegen aan de vertaling

Indien u aan de vertaling een extra sectie wilt toevoegen, bijvoorbeeld om erkenning te geven aan de vertaler, moet u een addendum definiëren bij de regel welke uw hoofdbestand definieert, Raadpleeg pagina po4a(7) voor meer informatie over de syntaxis van addendumbestanden.

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

U kunt ook als volgt gebruik maken van taalsjablonen:

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

Indien het toepassen van een addendum mislukt, wordt de vertaling verwijderd.

Wijzigingselementen voor de addendumdeclaratie

Met addendumwijzigingselementen kan het configuratiebestand vereenvoudigd worden in het geval er niet voor elke taal een addendum is, of wanneer de lijst met addenda verschilt naargelang de taal. Het wijzigingselement is één enkele letter die voor de bestandsnaam staat.

?

pad_naar_addendum toevoegen indien dit bestand bestaat; in het ander geval niets doen.

@

pad_naar_addendum is geen gewoon addendum, maar een bestand dat een lijst met addenda bevat, één per regel. Elk addendum kan voorafgegaan worden door wijzigingselementen.

!

pad_naar_addendum wordt weggelaten; het wordt niet geladen en zal niet geladen worden bij eventuele verdere addendumspecificaties.

Met het volgende wordt voor elke taal een addendum toegevoegd, maar enkel indien het bestaat. Er wordt geen fout gerapporteerd indien het addendum niet bestaat.

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

Met het volgende wordt een lijst met addenda toegevoegd voor elke taal:

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

De vertaalde tekstfragmenten filteren

Soms wilt u bepaalde tekstfragmenten voor het vertaalproces verborgen houden. Met dit doel kunt u een "pot_in"-parameter opgeven aan uw hoofdbestand om de naam op te geven van het bij het bouwen van het POT-bestand te gebruiken bestand in plaats van het echte hoofdbestand. Hier volgt een voorbeeld:

[type:docbook] boek.xml          \
        pot_in:boek-gefilterd.xml \
        $lang:boek.$lang.xml

Met deze instelling zullen de te vertalen tekstfragmenten geëxtraheerd worden uit het bestand boek-gefilterd.xml (dat aangemaakt moet worden vooraleer po4a aangeroepen wordt), terwijl de vertaalde bestanden gebouwd worden vanuit boek.xml. Als gevolg daarvan zullen alle tekstfragmenten welke in boek.xml voorkomen maar niet in boek-gefilterd.xml, niet opgenomen worden in de PO-bestanden, waardoor voorkomen wordt dat vertalers er een vertaling voor geven. Deze tekstfragmenten zullen dus ongewijzigd blijven bij het aanmaken van de vertaalde documenten. Dit verlaagt natuurlijk de graad van vertaling, waardoor u mogelijk de optie "--keep" zult moeten aanpassen om ervoor te zorgen dat het document desondanks aangemaakt wordt.