PO4A-GETTEXTIZE(1p)

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