Ondersteunde indelingen¶

Momenteel werd deze aanpak met succes toegepast voor verschillende soorten tekstopmaakindelingen:

man (voldragen ontleder)

De goede oude man-paginaindeling, welke door zoveel programma's gebruikt wordt. Ondersteuning door po4a is hier erg welkom, aangezien deze indeling enigszins moeilijk te gebruiken is en niet echt vriendelijk voor nieuwkomers.

De module Locale::Po4a::Man(3pm) ondersteunt ook de mdoc-indeling, welke door de BSD man-pagina's gebruikt wordt (deze zijn ook redelijk gebruikelijk onder Linux).

AsciiDoc (voldragen ontleder)

Dit is een lichtgewicht opmaakindeling, bedoeld om het schrijven van documentatie te vergemakkelijken. Zij wordt bijvoorbeeld gebruikt voor het documenteren van het git-systeem. Deze man-pagina's worden vertaald met po4a.

pod (voldragen ontleder)

Dit is de indeling voor de Perl Online Documentatie. De computertaal en de uitbreidingen ervan worden gedocumenteerd met behulp van deze indeling, net als de meeste bestaande Perl-scripts. Het maakt het makkelijk om de documentatie dicht bij de echte code te houden, door beide in te bedden in hetzelfde bestand. Het maakt het leven van programmeurs makkelijker, maar jammer genoeg niet dat van vertalers, tenzij u po4a gebruikt.

sgml (voldragen ontleder)

Zelfs als deze indeling tegenwoordig wordt vervangen door XML, wordt ze nog steeds gebruikt voor documenten van meer dan enkele schermen lang. Ze kan zelfs gebruikt worden voor volledige boeken. Het kan een hele uitdaging zijn om dergelijk lange documenten bij te werken. diff blijkt vaak niet bruikbaar te zijn wanneer na het bijwerken het inspringen van de oorspronkelijke tekst opnieuw werd uitgevoerd. Gelukkig kan po4a u na dit proces behulpzaam zijn.

Momenteel worden enkel DebianDoc en DocBook DTD ondersteund, maar iets anders ondersteunen is erg gemakkelijk. Het is zelfs mogelijk om zonder de code te wijzigen po4a te gebruiken bij een onbekende SGML DTD door de nodige informatie op te geven aan de commandoregel. Zie Locale::Po4a::Sgml(3pm) voor details.

TeX / LaTeX (voldragen ontleder)

De LaTeX-indeling is een heel belangrijke indeling voor documentatie in de vrije-softwarewereld evenals voor publicaties.

De module Locale::Po4a::LaTeX(3pm) werd getest met de Python-documentatie , een boek en enkele presentaties.

text (voldragen ontleder)

De indeling Text is de basisindeling voor veel indelingen welke lange blokken tekst bevatten, waaronder Markdown, debian/changelog en debian/control.

Dit ondersteunt de indeling die Static Site Generators, README's en andere documentatiesystemen gebruiken en gemeen hebben.

xml and XHMTL (vermoedelijk voldragen ontleder)

De indeling XML is een basisindeling voor veel documentatie-indelingen.

Momenteel worden DocBook DTD (zie Locale::Po4a::Docbook(3pm) voor details) en XHTML door po4a ondersteund.

texinfo (zeer erg experimentele ontleder)

Alle GNU-documentatie wordt in deze indeling geschreven (het is zelfs een vereiste om een officieel GNU-project te worden). De ondersteuning in po4a voor Locale::Po4a::Texinfo(3pm) zit nog steeds in zijn beginfase. Gelieve problemen en functieverzoeken te rapporteren.

Andere ondersteunde indelingen

Po4a kan ook overweg met enkele meer zeldzame of gespecialiseerde indelingen, zoals de documentatie over compilatieopties voor de 2.4+ Linux-kernels of de diagrammen die door het programma dia geproduceerd worden. Een nieuwe indeling toevoegen is vaak erg gemakkelijk en de belangrijkste taak bestaat erin een ontleder aan te brengen voor de beoogde indeling. Zie Locale::Po4a::TransTractor(3pm) voor meer informatie hierover.

Niet-ondersteunde indelingen

Jammer genoeg biedt po4a nog geen ondersteuning voor verschillende documentaie-indelingen. Voor vele zou po4a makkelijk ondersteuning kunnen bieden. Het betreft indelingen die niet enkel voor documentatie gebruikt worden, zoals pakketbeschrijvingen (deb en rpm), vragen van pakketinstallatiescripts, changelogs van pakketten en alle gespecialiseerde bestandsformaten welke gebruikt worden door programma's zoals spelscenario's en wine-bronbestanden.

Grafisch overzicht van de po4a-scripts¶

Het volgende schema geeft een overzicht van hoe elk po4a-script gebruikt kan worden. Hier is hoofddocument.doc een voorbeeldnaam voor de te vertalen documentatie; XX.doc is hetzelfde document, vertaald in taal XX, terwijl doc.XX.po de vertaalcatalogus van dat document is in taal XX. Auteurs van documentatie zullen zich hoofdzakelijk bezighouden met hoofddocument.doc (dit kan een man-pagina zijn, een XML-document, een asciidoc-bestand of iets dergelijks). De vertalers zullen zich hoofdzakelijk bezighouden met het PO-bestand, terwijl de eindgebruikers uitsluitend het bestand XX.doc zullen zien.

                                   hoofddocument.doc
                                       |
                                       V
     +<-----<----+<-----<-----<--------+------->-------->-------+
     :           |                     |                        :
{vertaling}      |         { update van hoofddocument.doc }         :
     :           |                     |                        :
   XX.doc        |                     V                        V
 (facultatief)   |              hoofddocument.doc ->-------->------>+
     :           |                   (nieuw)                      |
     V           V                     |                        |
  [po4a-gettextize]   doc.XX.po -->+   |                        |
          |            (oud)       |   |                        |
          |              ^         V   V                        |
          |              |     [po4a-updatepo]                  |
          V              |           |                          V
   vertaling.pot         ^           V                          |
          |              |        doc.XX.po                     |
          |              |         (onnauwkeurig)                 |
   { vertaling }         |           |                          |
          |              ^           V                          V
          |              |     {handmatig bewerken}              |
          |              |           |                          |
          V              |           V                          V
      doc.XX.po --->---->+<---<-- doc.XX.po    addendum     hoofddocument.doc
      (initieel)                 (up-to-date)  (facultatief)   (up-to-date)
          :                          |            |             |
          :                          V            |             |
          +----->----->----->------> +            |             |
                                     |            |             |
                                     V            V             V
                                     +------>-----+------<------+
                                                  |
                                                  V
                                           [po4a-translate]
                                                  |
                                                  V
                                                XX.doc
                                             (up-to-date)

Dit schema is gecompliceerd, maar in de praktijk wordt enkel het rechterdeel gebruikt (waarbij po4a-updatepo(1) en po4a-translate(1) betrokken zijn) nadat het project opgezet en geconfigureerd is.

Het linkerdeel laat zien hoe po4a-gettextize(1) kan worden gebruikt om een bestaand vertaalproject te converteren naar de po4a-infrastructuur. Dit script gebruikt een origineel document en zijn vertaalde tegenhanger en tracht het overeenkomstige PO-bestand te bouwen. Een dergelijke handmatige conversie is nogal omslachtig (zie de documentatie over po4a-gettextize(1) voor meer details), maar ze moet slechts eenmaal gebruikt worden om uw bestaande vertalingen om te zetten. Indien u geen te converteren vertalingen heeft, kunt u dit vergeten en u concentreren op het rechterdeel van het schema.

In de rechterbovenhoek wordt de actie van de oorspronkelijke auteur afgebeeld, welke de documentatie bijwerkt. Het middelste rechterdeel geeft de automatische acties van po4a-updatepo(1) weer. Het nieuwe materiaal wordt geëxtraheerd en vergeleken met de bestaande vertaling. De vorige vertaling wordt gebruikt voor de delen welke niet gewijzigd werden, terwijl de gedeeltelijk gewijzigde delen gekoppeld worden aan de vorige vertaling met de aanduiding "fuzzy" (onnauwkeurig), hetgeen aangeeft dat de vertaling moet bijgewerkt worden. Nieuw of grondig gewijzigd materiaal blijft onvertaald.

Vervolgens geeft het gerapporteerde handmatig bewerken de actie van de vertalers weer, welke de PO-bestanden wijzigen om te voorzien in een vertaling voor elk origineel tekstfragment en alinea. Dit kan gebeuren met een specifieke editor, zoals de GNOME Translation Editor, KDE's Lokalize of poedit, of met een online lokalisatieplatform, zoals weblate of pootle. Het resultaat van de vertaling is een aantal PO-bestanden, één per taal. Raadpleeg de gettext-documentatie voor meer details.

Het onderste deel van de afbeelding toont hoe po4a-translate(1) een vertaald brondocument creëert uit het originele document hoofddocument.doc en de vertaalcatalogus doc.XX.po die door de vertalers bijgewerkt werd. De structuur van het document wordt hergebruikt, terwijl de originele inhoud vervangen wordt door de vertaalde tegenhanger. Facultatief kan een addendum gebruikt worden om aan de vertaling extra tekst toe te voegen. Dit wordt vaak gebruikt om de naam van de vertaler toe te voegen aan het uiteindelijke document. Zie hieronder voor details.

Zoals voordien reeds aangegeven werd, combineert het programma po4a(1) de effecten van de aparte scripts en werkt de PO-bestanden en het vertaalde document bij in één beweging. De onderliggende logica blijft dezelfde.

Beginnen met een nieuwe vertaling¶

Indien u po4a(1) gebruikt, bestaat er geen specifieke stap voor het starten van een vertaling. U moet gewoon de talen vermelden in het configuratiebestand en de ontbrekende PO-bestanden worden automatisch gecreëerd. Natuurlijk moet de vertaler dan voor de vertaling zorgen van alle inhoud uit uw documenten. po4a(1) creëert ook een POT-bestand, hetgeen een PO-sjabloonbestand is. Potentiële vertalers kunnen uw project naar een nieuwe taal vertalen door dit bestand te hernoemen en te zorgen voor de vertaling ervan in hun taal.

Indien u verkiest om de individuele scripts apart te gebruiken, moet u po4a-gettextize(1) als volgt gebruiken om het POT-bestand te creëren. Dit bestand kan dan gekopieerd worden naar XX.po om een nieuwe vertaling te starten.

  $ po4a-gettextize --format <indeling> --master <hoofddocument.doc> --po <vertaling.pot>

Het hoofddocument wordt als invoer gebruikt, terwijl het POT-bestand de uitvoer van dit proces is.

Wijzigingen in het originele document integreren¶

Het script dat daarvoor gebruikt moet worden is po4a-updatepo(1) (raadpleeg de erbij horende documentatie voor details):

  $ po4a-updatepo --format <indeling> --master <nieuw_hoofddocument.doc> --po <oud_doc.XX.po>

Het hoofddocument wordt gebruikt als invoer, terwijl het PO-bestand bijgewerkt wordt: het wordt gebruikt als invoer en als uitvoer.

Een vertaald document genereren¶

Als u klaar bent met de vertaling, wilt u de vertaalde documentatie nemen en deze samen met het origineel verdelen naar de gebruikers. Daarvoor moet u het programma po4a-translate(1) als volgt gebruiken:

  $ po4a-translate --format <indeling> --master <hoofddocument.doc> --po <doc.XX.po> --localized <XX.doc>

Zowel het hoofddocument als de PO-bestanden worden als invoer gebruikt, terwijl het gelokaliseerde bestand de uitvoer is van dit proces.

Addenda gebruiken om extra tekst toe te voegen aan vertalingen¶

Het toevoegen van nieuwe tekst aan de vertaling is waarschijnlijk het enige dat op de lange termijn gemakkelijker is wanneer u bestanden handmatig vertaalt :). Dit gebeurt wanneer u een extra onderdeel wilt toevoegen aan het vertaalde document, waarvoor in het originele document geen overeenkomstige inhoud bestaat. Het klassieke toepassingsgebied is erkenning geven aan het vertaalteam en aangeven hoe vertaalspecifieke problemen gemeld kunnen worden.

Met po4a moet u addendum-bestanden opgeven, die conceptueel beschouwd kunnen worden als patches die na verwerking toegepast worden op het gelokaliseerde document. Elk addendum moet als apart bestand aangereikt worden. De indeling ervan verschilt evenwel erg van klassieke patches. De eerste regel is een header-regel, die het invoegpunt van het addendum definieert (met een helaas cryptische syntaxis -- zie hieronder), terwijl de rest van het bestand woordelijk toegevoegd wordt op de aangegeven positie.

De header-regel moet beginnen met de tekst PO4A-HEADER:, gevolgd door een door puntkomma's gescheiden lijst van I <sleutel> B <=> I <waarde> velden.

Bijvoorbeeld, de volgende header declareert een addendum dat helemaal aan het einde van de vertaling geplaatst moet worden.

 PO4A-HEADER: mode=eof

De zaken zijn complexer wanneer u de extra inhoud wilt toevoegen in het midden van het document. De volgende header declareert bijvoorbeeld een addendum dat ingevoegd moet worden na de XML-sectie welke het tekstfragment "Over dit document" bevat in de vertaling.

 PO4A-HEADER: position=About this document; mode=after; endboundary=</section>

Wanneer po4a tracht een addendum toe te passen, zoekt het in de praktijk naar de eerste regel die overeenkomt met het "position"-argument (dit kan een reguliere expressie zijn). Vergeet niet dat po4a hier rekening houdt met het vertaalde document. Deze documentatie is in het Nederlands (en de originele versie ervan in het Engels), maar uw regel zou er waarschijnlijk als volgt moeten uitzien, indien u van plan bent een addendum toe te passen op de Franse vertaling van het document.

 PO4A-HEADER: position=À propos de ce document; mode=after; endboundary=</section>

Nadat in het doeldocument de "position" gevonden werd, zoekt po4a naar de eerstvolgende regel na deze "position" welke overeenkomt met de opgegeven "endboundary". Het addendum wordt ingevoegd net na deze regel (omdat we een endboundary opgaven, d.w.z. een begrenzing die de huidige sectie afsluit).

Exact hetzelfde effect kan bekomen worden met de volgende header, die gelijkwaardig is:

 PO4A-HEADER: position=Over dit document; mode=after; beginboundary=<section>

Hier zoekt po4a naar de eerste regel die overeenkomt met "<section"> na de regel die overeenkomt met "Over dit document" in de vertaling en voegt het addendum toe voor die regel, omdat we een beginboundary opgegeven hebben, d.w.z. een begrenzing welke het begin van de volgende sectie markeert. Deze header-regel vereist dus dat het addendum geplaatst wordt na de sectie waarin "Over dit document" voorkomt, en informeert po4a dat een sectie begint met een regel welke de tag "<section"> bevat. Dit is het equivalent van het vorige voorbeeld, want wat u eigenlijk wilt is het addendum in te voegen na "</section"> en voor "<section">.

U kunt de invoeging mode ook instellen op de waarde "before", met een vergelijkbare semantiek: het combineren van "mode = before" met een "endboundary" zal het addendum juist na de overeenkomstige begrenzing plaatsen, welke de laatst mogelijke begrenzing is voor de "position". De combinatie van "mode = before" met een "beginboundary" zal het addendum juist voor de overeenkomstige begrenzing plaatsen, welke de laatst mogelijke grensregel is vóór de "position".

  Modus   | Soort begrenzing |     Gebruikte begrenzing      | Invoegpunt tegenover begrenzing
 ========|===============|========================|=========================================
 'before'| 'endboundary' | laatste voor 'position' | Juist na de geselecteerde begrenzing
 'before'|'beginboundary'| laatste voor 'position' | Juist voor de geselecteerde begrenzing
 'after' | 'endboundary' | eerste na 'position' | Juist na de geselecteerde begrenzing
 'after' |'beginboundary'| eerste na 'position' | Juist voor de geselecteerde begrenzing
 'eof'   |   (geen)      |  n.v.t.                   | Einde van het bestand

Aanwijzingen en kneepjes in verband met addenda

• Denk eraan dat dit reguliere expressies zijn. Indien u bijvoorbeeld het einde van een nroff-sectie wilt opzoeken welke eindigt met de regel ".fi", moet u niet ".fi" gebruiken als endboundary, omdat dit een overeenkomst zal opleveren met "the [fi]le", hetgeen duidelijk niet is wat u verwacht. De juiste endboundary in dit geval is: "^\.fi$".
• Witruimte IS belangrijk in de inhoud van de "position" en de begrenzingen. En dus zijn de twee volgende zinnen verschillend. De tweede zal slechts gevonden worden als er in het vertaalde document voldoende nakomende spaties zijn.

   PO4A-HEADER: position=Over dit document; mode=after; beginboundary=<section>
   PO4A-HEADER: position=Over dit document ; mode=after; beginboundary=<section>
      

• Hoewel ruwweg zou kunnen aangenomen worden dat deze contextzoekfunctie werkt op elke regel van het vertaalde document, werkt het in feite op de interne gegevensreeks van het vertaalde document. Deze interne gegevensreeks kan een tekst zijn die een volledige alinea beslaat en meerdere regels bevat, of kan ook enkel een XML-tag zijn. Het exacte invoegpunt van het addendum moet voor of na de interne gegevensreeks komen en kan er niet binnenin liggen.
• Geef het argument -vv op aan po4a om te zien hoe de addenda aan de vertaling worden toegevoegd. Dit kan ook behulpzaam zijn voor het uitvoeren van po4a in debug-modus om de exacte gegevensreeks te bekijken wanneer het addendum niet toegevoegd wordt.

Voorbeelden van addenda

• Indien u na de volgende nroff-sectie iets wilt toevoegen:

    .SH "AUTEURS"
      

  U moet een benadering in twee stappen selecteren door mode = after in te stellen. Vervolgens moet u de zoekopdracht beperken tot de regel na AUTEURS met de reguliere expressie voor het argument position. Daarna moet u het begin van de volgende sectie (d.w.z. ^\.SH) laten opzoeken met de reguliere expressie voor het argument beginboundary. Het is te zeggen:

   PO4A-HEADER:mode=after;position=AUTEURS;beginboundary=\.SH
      

• Indien u iets wilt toevoegen vlak na een bepaalde regel (bijv. na de regel "Copyright Grote Kerel"), gebruik dan een position die met deze regel overeenkomt, mode=after en geef een beginboundary op die met om het even welke regel overeenkomt.

   PO4A-HEADER:mode=after;position=Copyright Grote Kerel, 2004;beginboundary=^
      

• Indien u iets wilt toevoegen aan het einde van het document, geef dan een position op die overeenkomt met om het even welke regel van uw document (maar enkel één regel, omdat po4a niet zal aanvaarden dat de position niet met één enkele regel overeenkomt), en geef een endboundary op die met niets overeenkomt. Gebruik hier geen eenvoudige tekenreeks, zoals "EOF", maar geef de voorkeur aan die welke minder kans maken om in uw document voor te komen.

   PO4A-HEADER:mode=after;position=Over dit document;beginboundary=VerzonnenPo4aBegrenzing
      

Een meer gedetailleerd voorbeeld

Origineel document (POD-indeling):

 |=head1 NAAM
 |
 |dummy - een dummy-programma
 |
 |=head1 AUTEUR
 |
 |ik

Dan zal het volgende addendum ervoor zorgen dat een sectie (in het Frans) over de vertaler toegevoegd wordt aan het eind van het bestand ("TRADUCTEUR" in het Frans betekent "VERTALER", en "moi" betekent "ik").

 |PO4A-HEADER:mode=after;position=AUTEUR;beginboundary=^=head
 |
 |=head1 TRADUCTEUR
 |
 |moi
 |

Om uw addendum voor de AUTEUR te plaatsen, gebruikt u de volgende header:

 PO4A-HEADER:mode=after;position=NAAM;beginboundary=^=head1

Dit werkt omdat de volgende regel die overeenkomt met de beginboundary /^=head1/ na de sectie "NAME" (vertaald als "NAAM" in het Nederlands), die is welke de auteurs vermeldt. Dus zal het addendum tussen de beide secties geplaatst worden. Merk op dat indien later een andere sectie toegevoegd wordt tussen de secties NAAM en AUTEUR, po4a de addenda ten onrechte zal plaatsen voor de nieuwe sectie.

Om dit te vermijden, kunt u hetzelfde bereiken met behulp van mode=before:

 PO4A-HEADER:mode=before;position=^=head1 AUTEUR

Hoe spreekt men po4a uit?¶

Zelf spreek ik het uit als pouah <https://en.wiktionary.org/wiki/pouah>, wat een Franse klanknabootsing is die men gebruikt voor bah :) Misschien heb ik een vreemd gevoel voor humor :)

Hoe zit het met de andere vertaalhulpmiddelen voor documentatie die gebruik maken van gettext?¶

Voor zover ik weet bestaan er zo maar twee:

poxml

Dit gereedschap werd ontwikkeld door mensen van KDE om DocBook XML te verwerken. Voor zover ik weet was dit het eerste programma dat te vertalen tekstfragmenten uit documentatie extraheerde naar PO-bestanden en deze na vertaling terug injecteerde.

Het kan enkel XML verwerken, en enkel een specifieke DTD. Ik ben erg ongelukkig met de verwerking van lijsten welke terechtkomen in één grote msgid. Wanneer de lijst groot wordt, is het moeilijker die brok door te slikken.

po-debiandoc

Dit door Denis Barbier gemaakt programma is een soort voorloper van de SGML-module van po4a, waardoor het min of meer achterhaald werd. Zoals de naam het zegt, verwerkt het enkel de DebianDoc DTD, hetgeen min of meer een achterhaalde DTD is.

De belangrijkste voordelen van po4a tegenover hen zijn het gemak waarmee extra inhoud toegevoegd kan worden (wat bij deze andere hulpmiddelen nog moeilijker is) en de mogelijkheid een gettextize-procedure uit te voeren.

SAMENVATTING van de voordelen van een op gettext gebaseerde benadering¶

• De vertalingen worden niet samen met het origineel opgeslagen, wat het mogelijk maakt na te gaan of vertalingen verouderd beginnen te raken.
• De vertalingen worden in aparte bestanden opgeslagen, wat interferentie tussen vertalers van verschillende talen voorkomt, zowel wanneer deze hun patch indienen als bij de keuze van de tekstcodering van de bestanden.
• Intern is het gebaseerd op gettext (maar po4a biedt een heel eenvoudige interface, zodat u de interne werking niet moet kennen om het te gebruiken). Op die manier moeten we het wiel niet terug uitvinden, en omdat dit gereedschap zo ruim gebruikt wordt, mogen we aannemen dat het min of meer vrij van fouten is.
• Voor de eindgebruiker verandert er niets (behalve het feit dat vertalingen hopelijk beter onderhouden zullen worden). Het resulterende documentatiebestand dat verspreid wordt, is exact hetzelfde.
• Vertalers moeten geen nieuwe bestandsyntaxis leren en hun favoriete editor voor PO-bestanden (zoals de PO-modus in Emacs, Lokalize of Gtranslator) voldoet perfect.
• gettext biedt een eenvoudige manier om statistieken te bekomen over het gepresteerde werk, over wat nazicht en een update nodig heeft en over wat er nog moet gebeuren. Enkele voorbeelden zijn te vinden op deze adressen:

   - https://docs.kde.org/stable5/en/kdesdk/lokalize/project-view.html
   - http://www.debian.org/intl/l10n/
      

Maar niet alles is rozengeur en deze aanpak heeft ook enkele nadelen waarmee we moeten omgaan.

• Addenda zijn… vreemd op het eerste gezicht.
• Het is niet mogelijk om de vertaalde tekst naar uw smaak aan te passen, zoals hier een paragraaf opsplitsen en er daar twee andere samenvoegen. Maar in zekere zin moet het hoe dan ook als een bug gemeld worden, wanneer er een probleem is met het origineel.
• Zelfs met een gemakkelijke interface blijft het een nieuw gereedschap dat mensen moeten leren gebruiken.

  Een van mijn dromen is om po4a op een of andere manier te integreren in Gtranslator of Lokalize. Wanneer een documentatiebestand geopend wordt, zouden de tekstfragmenten automatisch geëxtraheerd worden en een vertaald bestand + po-bestand zouden naar schijf geschreven worden. Indien we erin zouden slagen een MS Word(TM)-module te ontwikkelen (of minstens een RTF-module), zouden zelfs professionele vertalers er gebruik van maken.