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 helpt u bij het omzetten van uw reeds bestaande vertalingen
       naar een op po4a gebaseerde werkstroom. Dit moet slechts één keer worden gedaan om een
       bestaande vertaling te behouden bij de omzetting naar po4a, en niet op regelmatige basis
       na de omzetting van uw project. Dit vervelende proces wordt in detail uitgelegd in de
       sectie 'Een handmatige vertaling omzetten naar po4a' hieronder.

       U moet zowel een hoofdbestand (bijv. de bron in het Engels) als een bestaand vertaald
       bestand (bijv. een eerdere vertaalpoging zonder po4a) aanleveren. Als u meer dan één
       hoofd- of vertaalbestand aanlevert, zullen ze opeenvolgend worden gebruikt, maar het kan
       gemakkelijker zijn om elke pagina of elk hoofdstuk afzonderlijk te verwerken met
       gettextize en dan msgmerge te gebruiken om alle geproduceerde PO-bestanden samen te
       voegen. Het is zoals u verkiest.

       Indien het hoofddocument niet-ASCII-tekens bevat, zal het nieuw aangemaakt PO-bestand in
       UTF-8 zijn. Indien het hoofddocument volledig in ASCII is, zal het gegenereerde PO-bestand
       de codering gebruiken van het vertaalde invoerdocument.

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.

       -k --keep-temps
           Bewaar de tijdelijke hoofd- en gelokaliseerde POT-bestanden die gebouwd werden
           voorafgaand aam het samenvoegen.  Dit kan nuttig zijn als u wilt begrijpen waarom deze
           bestanden gedesynchroniseerd raken, wat leidt tot gettextisatieproblemen

       -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 synchroniseert de hoofd- en gelokaliseerde bestanden om hun inhoud uit te
       pakken in een PO-bestand. De inhoud van het hoofdbestand geeft de msgid terwijl de inhoud
       van het gelokaliseerde bestand de msgstr geeft. Dit proces is enigszins kwetsbaar: de N-de
       tekenreeks van het vertaalde bestand wordt verondersteld de vertaling te zijn van de N-de
       tekenreeks in het origineel.

       Gettextisatie werkt het best als u erin slaagt om de exacte versie van het originele
       document dat voor de vertaling is gebruikt, te achterhalen. Zelfs dan kan het zijn dat u
       zowel het hoofdbestand als de gelokaliseerde bestanden moet bewerken om hun structuur op
       elkaar af te stemmen als die door de oorspronkelijke vertaler werd gewijzigd. Dus is het
       raadzaam om op kopieën van bestanden te werken.

       Intern rapporteert elke po4a-ontleder het syntactische type van elk geëxtraheerd
       tekstfragment. Dit is de wijze waarop desynchronisatie ontdekt wordt tijdens het
       gettextisatie-proces. In het onderstaande voorbeeld 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 om hier en daar
       nepparagrafen toe tevoegen of bepaalde inhoud te verwijderen, totdat de structuur van
       beide bestanden werkelijk overeenkomt. Hieronder worden enkele kneepjes aangereikt om het
       meeste van de bestaande vertaling te redden terwijl u dit doet.

       Indien u het geluk heeft dat de bestandsstructuren vanzelf perfect overeenkomen, dan 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:) Toch blijft gettextisatie
       vaak sneller dan alles opnieuw vertalen. Ik heb de gettextisatie van de Franse vertaling
       van de hele Perl-documentatie in één dag gerealiseerd, ondanks de vele
       synchronisatieproblemen. Gezien de hoeveelheid tekst (2Mb aan originele tekst), zou het
       opnieuw starten van de vertaling zonder eerst de oude vertalingen te redden, meerdere
       maanden werk hebben gekost. Bovendien is dit werk dat u doet morren, de prijs 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.

       Na een succesvolle gettextisatie moeten de geproduceerde documenten handmatig worden
       gecontroleerd op niet-gedetecteerde verschillen en stille fouten, zoals hieronder wordt
       uitgelegd.

       Aanwijzingen en kneepjes voor het gettextize-proces

       De gettextisatie stopt zodra een desynchronisatie wordt gedetecteerd. Wanneer dit gebeurt,
       moet u de bestanden zo vaak bewerken als nodig is om de structuur van de bestanden opnieuw
       op één lijn te krijgen. po4a-gettextize geeft behoorlijk veel informatie wanneer er zaken
       fout lopen. 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 knepen om u te helpen bij dit saai proces en om ervoor te zorgen dat u
       het meeste van de eerdere vertaling behoudt:

       •   Verwijder alle extra inhoud uit de vertalingen, zoals het onderdeel dat erkenning
           geeft aan de vertalers. Zij moet afzonderlijk aan po4a worden toegevoegd als addenda
           (zie po4a(7)).

       •   Bij het bewerken van de bestanden om hun structuur op één lijn te krijgen, 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 bij de eerste uitvoering van po4a
           na de gettextisatie (zie hieronder) niet lukken om de oude en de nieuwe versie met
           elkaar in overeenstemming te brengen. Hoe dan ook zal elke vertaling die niet in
           overeenstemming is, gedumpt worden. Dat gezegd zijnde, zult u nog steeds het originele
           document willen bewerken als het anders te moeilijk is om de gettextisatie te laten
           doorgaan, zelfs als dat betekent dat een paragraaf van de vertaling wordt gedumpt. 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;) Maar u wilt waarschijnlijk
           wachten tot het einde van de omzetting naar po4a voordat u de originele bestanden
           wijzigt.

       •   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 het bestand
           gettextization.failed.po dat gemaakt werd, na te kijken en los het probleem op waar
           het zich echt bevindt.

       •   Andere problemen kunnen het gevolg zijn van dubbele tekenreeksen in het origineel of
           in de vertaling. Gedupliceerde tekenreeksen worden in PO-bestanden samengevoegd, met
           twee referenties. Dit vormt een moeilijkheid voor het gettextisatie-algoritme, dat een
           eenvoudige een-op-een koppeling maakt tussen de msgid's van zowel het hoofdbestand als
           van de gelokaliseerde bestanden. Er wordt echter aangenomen dat recente versies van
           po4a correct omgaan met dubbele tekenreeksen, dus zou u elk overblijvend probleem dat
           u tegenkomt moeten melden.

   Controleren van door po4a-gettextize geproduceerde bestanden
       Elk bestand dat door po4a-gettextize wordt geproduceerd, moet handmatig worden
       gecontroleerd, zelfs als het script met succes wordt afgesloten. U moet het PO-bestand
       overlopen en ervoor zorgen dat de msgid en msgstr daadwerkelijk overeenkomen. Het is niet
       nodig ervoor te zorgen dat de vertaling reeds helemaal correct is, aangezien alle items
       sowieso als vage vertalingen worden gemarkeerd. U hoeft alleen te controleren op
       duidelijke overeenstemmingsproblemen, omdat slecht overeenkomende vertalingen in de
       volgende stappen worden gedumpt terwijl u ze wilt redden.

       Gelukkig hoeft u voor deze stap de doeltalen niet te beheersen, aangezien u alleen
       vergelijkbare elementen in elke msgstr en de bijbehorende msgstr wilt herkennen. Omdat ik
       zelf Frans, Engels en een beetje Duits spreek, kan ik dit in ieder geval voor alle
       Europese talen doen, zelfs als ik van de meeste van deze talen geen woord spreek. Ik slaag
       er soms in om overeenstemmingsproblemen in niet-Latijnse talen op te sporen door te kijken
       naar de lengte van de tekenreeks, naar zinsstructuren (komt het aantal vraagtekens
       overeen?) en naar andere aanwijzingen, maar ik heb liever dat iemand anders die talen
       nakijkt.

       Als u wat overeenkomsten betreft, een fout ontdekt, bewerk dan het origineel en de
       vertalingsbestanden alsof po4a-gettextize een fout meldde, en probeer het opnieuw. Als u
       eenmaal een fatsoenlijk PO-bestand hebt voor uw vroegere vertaling, maak er dan een back-
       up van totdat u er in slaagt po4a correct te laten werken.

   po4a voor het eerst uitvoeren
       De eenvoudigste manier om po4a in te stellen is om een configuratiebestand po4a.conf te
       schrijven, en het geïntegreerde po4a programma te gebruiken (po4a-updatepo en
       po4a-translate zijn verouderd). Raadpleeg het onderdeel "CONFIGURATIEBESTAND" in de
       documentatie van po4a(1) voor meer details.

       Wanneer po4a voor de eerste keer wordt uitgevoerd, wordt de huidige versie van de
       hoofddocumenten gebruikt om de PO-bestanden bij te werken die de oude vertalingen bevatten
       die u via gettextisatie hebt gered. Dit kan behoorlijk lang duren, omdat veel van de
       msgid's uit de gettextisatie niet exact overeenkomen met de elementen van het POT-bestand
       dat is opgebouwd uit de recente hoofdbestanden. Dit dwingt gettext om met behulp van een
       kostelijk tekenreeksverwantschapsalgoritme te zoeken naar wat er het dichtst bij aanleunt.
       Zo duurde de eerste doorloop van de Franse vertaling van de Perl-documentatie (PO-bestand
       van 5,5 MB) bijvoorbeeld ongeveer 48 uur (ja, twee dagen), terwijl de daaropvolgende
       slechts enkele seconden in beslag nemen.

   Uw vertalingen inschakelen in het productieproces
       Na deze eerste doorloop zijn de PO-bestanden klaar om door vertalers gecontroleerd te
       worden. Alle items in het PO-bestand werden door po4a-gettextization als vaag gemarkeerd,
       zodat ze vóór gebruik zorgvuldig moeten worden nagekeken. Vertalers moeten bij elke invoer
       nagaan of de geredde vertaling daadwerkelijk overeenstemt met de huidige originele tekst,
       ze moeten de vertaling indien nodig bijwerken en de vaag-markeringen verwijderen.

       Zodra er voldoende vaag-markeringen zijn verwijderd, begint po4a met het genereren op
       schijf van de vertalingsbestanden en bent u klaar om uw vertaalwerkstroom in het
       productieproces in te schakelen. Sommige projecten vinden het nuttig om beroep te doen op
       weblate voor de coördinatie tussen vertalers en beheerders, maar dat valt buiten het
       bereik van po4a.

ZIE OOK

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

AUTEURS

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

COPYRIGHT EN LICENTIE

       Copyright 2002-2022 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).