Ubuntu Manpage: po4a-gettextize - een origineel bestand (en zijn vertalingen) omzetten naar een PO-bestand

NAAM

       po4a-gettextize - een origineel bestand (en zijn vertalingen) omzetten naar een PO-bestand

OVERZICHT

       po4a-gettextize -f fmt -m hoofddocument.doc [-l XX.doc] -p XX.po

       (XX.po is de uitvoer, alle andere zijn invoer)

BESCHRIJVING

       po4a (PO for anything - Po voor alles) vergemakkelijkt het onderhoud van de vertaling van documentatie
       met het klassieke gettext-gereedschap. Het belangrijkste kenmerk van po4a is, dat het de vertaling van
       inhoud loskoppelt van de structuur van het document.  Raadpleeg pagina po4a(7) voor een welwillende
       introductie in dit project.

       Het script po4a-gettextize is belast met het converteren van documentatiebestanden naar PO-bestanden. U
       heeft het enkel nodig om uw vertaalproject in te stellen met po4a, nadien nooit meer.

       Als u begint van niets, zal po4a-gettextize de vertaalbare tekstfragmenten uit de documentatie extraheren
       en een POT-bestand schrijven. Indien u een eerder bestaand vertaald bestand opgeeft met de -l-vlag, dan
       zal po4a-gettextize proberen de vertalingen die het bevat, te gebruiken in het geproduceerde PO-bestand.
       Dit blijft een vervelend en manueel proces, zoals hieronder uitgelegd wordt in het onderdeel 'Een
       handmatige vertaling omzetten naar po4a'.

       Indien het hoofddocument niet-ASCII-tekens bevat, zal het nieuw aangemaakt PO-bestand in UTF-8 zijn.
       Anders (indien het hoofddocument volledig in ASCII is), zal het gegenereerde PO-bestand de codering
       gebruiken van het vertaalde invoerdocument, of in UTF-8 indien geen vertaald document verstrekt wordt.

OPTIES

-f, --format
Indeling van de documentatie die u wilt afhandelen. Gebruik de optie --help-format om de lijst van
beschikbare indelingen te zien.

-m, --master
Bestand dat het te vertalen hoofddocument bevat. U kunt deze optie meerdere malen gebruiken, indien u
meerdere documenten wilt verwerken met gettextize.

-M, --master-charset
Tekenset van het bestand met het te vertalen document.

-l, --localized
Bestand met het gelokaliseerde (vertaalde) document. Indien u meerdere hoofdbestanden verstrekte,
wilt u mogelijk meerdere gelokaliseerde bestanden aanleveren door deze optie meerdere keren te
gebruiken.

-L, --localized-charset
Tekenset van het bestand met het gelokaliseerde document.

-p, --po
Bestand waarnaartoe de berichtencatalogus moet worden geschreven. Indien dit niet opgegeven wordt,
zal de berichtencatalogus naar standaarduitvoer geschreven worden.

-o, --option
Extra optie(s) om door te geven aan de indelingsplug-in. Raadpleeg de documentatie bij elke plug-in
voor meer informatie over de geldige opties en hun betekenis. U zou bijvoorbeeld '-o tablecells'
kunnen doorgeven aan de ontleder voor AsciiDoc, terwijl de ontleder voor tekst '-o tabs=split' zou
accepteren.

-h, --help
Een korte hulptekst tonen.

--help-format
De documentatie-indelingen vermelden die door po4a begrepen worden.

-V, --version
De versie van het script tonen en afsluiten.

-v, --verbose
De breedsprakigheid van het programma verhogen.

-d, --debug
Enige foutopsporingsinformatie weergeven.

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

Een handmatige vertaling omzetten naar po4a
po4a-gettextize zal trachten de inhoud te extraheren uit elk verstrekt vertalingsbestand en het zal deze
inhoud gebruiken als msgstr in het geproduceerde PO-bestand. Wees gewaarschuwd dat dit een erg kwetsbaar
proces is: er wordt verondersteld dat het Nde tekstfragment uit het vertaalde bestand de vertaling is
voor het Nde fragment uit het origineel. Dit werkt uiteraard enkel als beide bestanden exact dezelfde
structuur hebben.

Intern rapporteert elke po4a-ontleder het syntactische type van elk geëxtraheerd tekstfragment. Dit is de
wijze waarop desynchronisatie ontdekt wordt tijdens het gettextize-proces. Bijvoorbeeld, indien de
bestanden de volgende structuur hebben, is het erg onwaarschijnlijk dat het 4de tekstfragment uit de
vertaling (van het type 'chapter' (hoofdstuk)) de vertaling is van het 4de tekstfragment uit het
origineel (van het type 'paragraph' (alinea)). Het is waarschijnlijker dat aan het origineel een nieuwe
alinea toegevoegd werd of dat in de vertaling twee originele alinea's samengevoegd werden.

Origineel Vertaling

hoofdstuk hoofdstuk
paragraaf paragraaf
paragraaf paragraaf
paragraaf hoofdstuk
hoofdstuk paragraaf
paragraaf paragraaf

po4a-gettextize zal elke desynchronisatie in de structuur met uitgebreide informatie diagnosticeren.
Indien dit gebeurt, moet u de bestanden handmatig bewerken (dit vereist wellicht dat u enige noties heeft
van de doeltaal). U moet in een van de documenten (of in beide) nepparagrafen toevoegen of bepaalde
inhoud verwijderen om de gerapporteerde ongelijkheden te repareren, totdat de structuur van beide
documenten volledig overeenkomt. In het volgende onderdeel worden enkele kneepjes aangereikt.

Zelfs indien het document met succes verwerkt wordt, is het nog steeds mogelijk dat bepaalde
ongelijkheden onopgemerkt bleven en er stilzwijgend fouten inslopen. Dat is de reden waarom elke
vertaling die door po4a-gettextize automatisch gekoppeld werd, gemarkeerd wordt als fuzzy (onduidelijk),
om handmatig menselijk nazicht uit te lokken. Men moet controleren of elke opgehaalde msgstr wel degelijk
de vertaling is voor het eraan gekoppelde msgid, en niet van het tekstfragment ervoor of erna.

Zoals u kunt zien, gaat het erom om exact dezelfde structuur te hebben in het vertaalde document als in
het originele document. Het beste is om het gettextize-proces uit te voeren op exact die versie van
hoofddocument.doc welke gebruikt werd voor de vertaling, en pas nadien, na een succesvol gettextize-
proces, het PO-bestand te updaten naar het meest recente hoofdbestand.

Indien u het geluk heeft dat de bestandsstructuren perfect overeenkomen, is het bouwen van een correct
PO-bestand een kwestie van seconden. In het andere geval zult u vlug begrijpen waarom dit proces zulk een
lelijke naam heeft:) Maar onthoud dat dit werk dat u laat brommen, de prijs is die u moet betalen om
daarna het comfort van po4a te krijgen. Eens de omzetting achter de rug is, zal de synchronisatie tussen
hoofddocumenten en vertalingen steeds volautomatisch verlopen.

Zelfs als zaken fout lopen, blijft het gettextize-proces sneller dan alles opnieuw vertalen. Ik was in
staat om in één dag de bestaande Franse vertaling van de volledige Perl-documentatie om te zetten met
gettextize, ook al was de structuur van veel documenten gedesynchroniseerd. Het betrof meer dan 2
megabytes originele tekst (2 miljoen lettertekens): de vertaling helemaal opnieuw maken zou verschillende
maanden werk gevraagd hebben.

Aanwijzingen en kneepjes voor het gettextize-proces
Het gettextize-proces stopt van zodra er een desynchronisatie ontdekt wordt. In theorie zou het
waarschijnlijk mogelijk moeten zijn om later in de documenten het gettextize-proces opnieuw te
synchroniseren aan de hand van bijvoorbeeld het algoritme dat gehanteerd wordt door het hulpprogramma
diff(1). Maar een handmatige interventie zou nog steeds noodzakelijk zijn om de elementen welke niet
automatisch in overeenstemming gebracht konden worden, handmatig met elkaar in overeenstemming te
brengen, en dit verklaart waarom automatische hersynchronisatie (nog?) niet geïmplementeerd werd.

Als dit zich voordoet, komt alles hierop neer dat de structuur van deze verdomde bestanden via handmatige
bewerkingen gealigneerd moet worden. po4a-gettextize geeft behoorlijk veel informatie over wat er fout
liep, als dit gebeurt. Het rapporteert de tekstfragmenten welke niet overeenstemmen, hun positie in de
tekst en van elk van hen het type. Daarenboven wordt het tot dusver gegenereerde PO-bestand gedumpt als
gettextization.failed.po voor verdere inspectie.

Hier volgen enkele andere knepen om u bij dit saai proces te helpen:

• Verwijder alle extra inhoud van de vertalers, zoals het onderdeel dat erkenning geeft aan de
vertalers. U kunt dit nadien terug toevoegen in po4a met addenda (zie po4a(7)).

• Indien u de bestanden moet bewerken om hun structuur te aligneren, moet u er de voorkeur aan geven om
zo mogelijk de vertaling te bewerken. Als de wijzigingen aan het origineel inderdaad te ingrijpend
zijn, zal het niet lukken om bij de PO-update de oude en de nieuwe versie met elkaar in
overeenstemming te brengen, en de bijbehorende vertaling zal hoe dan ook gedumpt worden. Maar aarzel
niet om zo nodig ook het originele document te bewerken: het belangrijkste is een eerste PO-bestand
te hebben waarmee gestart kan worden.

• Aarzel niet om eventuele originele inhoud welke in de vertaalde versie niet voorkomt, te vernietigen.
Deze inhoud zal nadien automatisch opnieuw ingevoegd worden, wanneer het PO-bestand gesynchroniseerd
wordt met het document.

• Waarschijnlijk zult u de originele auteur moeten informeren over eventuele structuurveranderingen in
de vertaling, welke verantwoord lijken. Problemen in het originele document zouden gemeld moeten
worden aan de auteur. Deze enkel in de vertaling repareren, repareert ze slechts voor een deel van de
gemeenschap. Bovendien is het met po4a onmogelijk om iets dergelijks te doen;)

• Soms komt de inhoud van de alinea's overeen, maar niet hun type. Dit repareren is eerder
indelingsafhankelijk. In POD en man komt dit vaak door het feit dat een van beide een regel bevat die
begint met een witruimte en het andere niet. In deze indelingen kan een alinea geen dergelijke
regelafbreking hebben en wordt ze dus een ander type. Verwijder gewoon de witruimte om de zaak op te
lossen. Bij XML kan het ook een typefout in een tag-naam betreffen.

Evenzo worden in POD mogelijk twee paragrafen samengevoegd wanneer de scheidingsregel enige spaties
bevat, of wanneer er geen lege regel is tussen de =item-regel en de inhoud van dat item.

• Soms lijkt het desynchronisatiebericht vreemd, omdat de vertaling aan de verkeerde originele alinea
is toegevoegd. Het is het teken dat eerder in het proces een probleem onopgemerkt bleef. Ga op zoek
naar het echte desynchronisatiepunt door gettextization.failed.po na te kijken en los het probleem op
waar het zich echt bevindt.

• In een aantal ongelukkige situaties kunt u het gevoel krijgen dat po4a sommige delen van de tekst van
het origineel of de vertaling opgegeten heeft. gettextization.failed.po geeft aan dat beide bestanden
zoals verwacht overeenkwamen tot paragraaf N. Maar dan is een (niet succesvolle) poging gedaan om
paragraaf N+1 van het originele bestand te vergelijken, niet met paragraaf N+1 van de vertaling,
zoals zou moeten, maar wel met paragraaf N+2. Net alsof paragraaf N+1 welke u in het document ziet,
gewoon uit het bestand verdween tijdens het proces.

Deze ongelukkige situatie ontstaat wanneer dezelfde alinea herhaald wordt in het document. In dat
geval wordt in het PO-bestand geen nieuw item gecreëerd, maar wordt in plaats daarvan aan het
bestaande item een nieuwe referentie toegevoegd.

De voorgaande situatie ontstaat dus wanneer twee gelijkaardige, maar verschillende paragrafen op
exact dezelfde manier vertaald worden. Dit zorgt er blijkbaar voor dat een paragraaf uit de vertaling
verwijderd wordt. Om het probleem op te lossen volstaat het om een van de vertalingen in het document
lichtjes te veranderen. U kunt er ook voor kiezen om de tweede paragraaf uit het originele document
te verwijderen.

Omgekeerd, indien dezelfde alinea welke tweemaal in het originele document voorkomt, niet op beide
plaatsen exact op dezelfde manier vertaald wordt, zult u het gevoel krijgen dat een alinea verdween
uit het originele document. Kopieer gewoon de beste vertaling over de andere in het vertaalde
document om het probleem op te lossen.

• Een laatste opmerking: wees niet al te verrast indien de eerste synchronisatie van uw PO-bestand veel
tijd in beslag neemt. Dit is omdat de meeste msgid's uit het PO-bestand, dat het resultaat is van het
gettextize-proces, niet exact overeenkomen met een element uit het POT-bestand dat uit de recente
hoofdbestanden gebouwd werd. Dit dwingt gettext ertoe om met een kostelijk tekstfragment-nabijheids-
algoritme op zoek te gaan naar het dichtstbij aanleunende element.

Bijvoorbeeld, de eerste po4a-updatepo van de Franse vertaling van de Perl-documentatie (PO-bestand
van 5.5 MB), nam ongeveer 48 uur (twee dagen, inderdaad) in beslag, terwijl de daaropvolgende slechts
een dozijn seconden duren.

ZIE OOK

       po4a(1), po4a-normalize(1), po4a-translate(1), po4a-updatepo(1), po4a(7).

AUTEURS

        Denis Barbier <barbier@linuxfr.org>
        Nicolas Francois <nicolas.francois@centraliens.net>
        Martin Quinson (mquinson#debian.org)

COPYRIGHT EN LICENTIE

       Copyright 2002-2020 door SPI, inc.

       Dit programma is vrije software; u kunt het verder verspreiden en/of aanpassen onder de bepalingen van de
       GPL (zie het bestand COPYING).

Po4a-hulpmiddelen                                  2022-01-02                                PO4A-GETTEXTIZE(1p)