Provided by: po4a_0.67-2_all 
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.
= item -k --keep-temps
Keep the temporary master and localized POT files built before merging. This can be
useful to understand why these files get desynchronized, leading to gettextization
problems
-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 some case, po4a adds a space at the end of either the original or the translated
strings. This is because every string must be deduplicated during the gettextize
process. Imagine that a string appearing several times unmodified in the original, but
is translated in differing way, or that different paragraphs are translated in the
exact same way.
Without deduplication, such case would break the gettexization algorithm, as it is a
simple one to one pairing between the msgids of both the master and the localized
files. Since one of the PO files would miss an entry (that would be reported as
duplicate, with two references), the pairing would fail.
Since po4a uses the entry type ("title" or "plain paragraph", etc) to detect whether
the parsing streams got desynchronized, similar issues could occur if two identical
entries (same content but differing type) of the master file are translated in the
exact same way in the localized file. po4a would detect a fake desyncronization in
such case.
In most cases, the extra space added by po4a to deduplicate the strings has no impact
on the formatting. Strings are fuzzied anyway, and msgmerge will probably match the
strings accordingly afterward.
• 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).