PO4A-GETTEXTIZE.1P(1)

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 (2 MB 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-2023 door SPI, inc.

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