Formater som stöds¶

För närvarande har denna metod framgångsrikt implementerats i flera olika textformateringsformat:

man (mogen parser)

Det gamla goda manualformatet, som används av så många program. Stöd för po4a är mycket välkommet här, eftersom detta format är något svårt att använda och inte särskilt användarvänligt för nybörjare.

Modulen Locale::Po4a::Man(3pm) stöder även mdoc-formatet, som används av BSD-man-sidorna (de är också ganska vanliga på Linux).

AsciiDoc (mogen parser)

Detta format är ett lättviktigt markup-format som är avsett att underlätta skapandet av dokumentation. Det används till exempel för att dokumentera git-systemet. Dessa man-sidor översätts med hjälp av po4a.

Se Locale::Po4a::AsciiDoc för mer information.

pod (mogen parser)

Detta är formatet för Perl Online Documentation. Språket och tilläggen själva dokumenteras med hjälp av detta format, liksom de flesta befintliga Perl-skript. Det gör det enkelt att hålla dokumentationen nära den faktiska koden genom att bädda in dem båda i samma fil. Det underlättar för programmeraren, men tyvärr inte för översättaren, tills du använder po4a.

Se Locale::Po4a::Pod för mer information.

sgml (mogen parser)

Även om detta format numera har ersatts av XML, används det fortfarande för dokument som är längre än några skärmbilder. Det kan till och med användas för hela böcker. Dokument av denna längd kan vara mycket svåra att uppdatera. B-<diff> en visar sig ofta vara värdelös när den ursprungliga texten har indragits på nytt efter uppdateringen. Lyckligtvis kan po4a hjälpa dig efter den processen.

För närvarande stöds endast DebianDoc och DocBook DTD, men det är väldigt enkelt att lägga till stöd för nya. Det är till och med möjligt att använda po4a på en okänd SGML DTD utan att ändra koden genom att ange nödvändig information på kommandoraden. Se Locale::Po4a::Sgml(3pm) för mer information.

TeX / LaTeX (mogen parser)

LaTeX-formatet är ett viktigt dokumentationsformat som används inom fri programvara och för publikationer.

Modulen Locale::Po4a::LaTeX(3pm) testades med Python-dokumentationen, en bok och några presentationer.

text (mogen parser)

Textformatet är grundformatet för många format som innehåller långa textblock, inklusive Markdown, fortunes, YAML front matter section, debian/changelog och debian/control.

Detta stöder det vanliga formatet som används i statiska webbplatsgeneratorer, README-filer och andra dokumentationssystem. Se Locale::Po4a::Text(3pm) för mer information.

xml och XHMTL (förmodligen mogen parser)

XML-formatet är ett basformat för många dokumentationsformat.

För närvarande stöds DocBook DTD (se Locale::Po4a::Docbook(3pm) för mer information) och XHTML av po4a.

BibTex (förmodligen mogen parser)

BibTex-formatet används tillsammans med LaTex för formatering av referenslistor (bibliografier).

Se Locale::Po4a::BibTex för mer information.

Docbook (förmodligen mogen parser)

Ett XML-baserat markup-språk som använder semantiska taggar för att beskriva dokument.

Se Locale::Po4a:Docbook för mer information.

Guide XML (förmodligen mogen parser)

Ett XML-dokumentationsformat. Denna modul utvecklades specifikt för att underlätta support och underhåll av översättningar av Gentoo Linux-dokumentation fram till åtminstone mars 2016 (baserat på Wayback Machine). Gentoo har sedan dess gått över till DevBook XML-formatet.

Se Locale::Po4a:Guide för mer information.

Wml (förmodligen mogen parser)

Web Markup Language, blanda inte ihop WML med WAP-tekniken som används i mobiltelefoner. Denna modul är beroende av Xhtml-modulen, som i sin tur är beroende av XmL-modulen.

Se Locale::Po4a::Wml för mer information.

Yaml (förmodligen mogen parser)

En strikt superset av JSON. YAML används ofta i system- eller konfigurationsprojekt. YAML är kärnan i Red Hats Ansible.

Se Locale::Po4a::Yaml för mer information.

RubyDoc (förmodligen mogen parser)

Ruby Document (RD)-formatet var ursprungligen standardformatet för dokumentation för Ruby och Ruby-projekt innan det konverterades till RDoc 2002. Den japanska versionen av Ruby Reference Manual använder dock fortfarande RD.

Se Locale::Po4a::RubyDoc för mer information.

Halibut (förmodligen experimentell parser)

Ett system för dokumentproduktion, med element som liknar TeX, debiandoc-sgml, TeXinfo och andra, utvecklat av Simon Tatham, utvecklaren av PuTTY.

Se Locale::Po4a:Halibut för mer information.

Ini (förmodligen experimentell parser)

Konfigurationsfilformat som populariserades av MS-DOS.

Se Locale::Po4a::Ini för mer information.

texinfo (mycket experimentell parser)

All GNU-dokumentation är skriven i detta format (det är till och med ett av kraven för att bli ett officiellt GNU-projekt). Stödet för Locale::Po4a::Texinfo(3pm) i po4a är fortfarande i sin linda. Vänligen rapportera buggar och önskemål om funktioner.

gemtext (mycket experimentell parser)

Det inbyggda ren textformatet i Gemini-protokollet. Filändelsen ".gmi" används vanligtvis. Stödet för denna modul i po4a är fortfarande i sin linda. Om du upptäcker något, vänligen rapportera ett fel eller skicka en funktionsförfrågan.

org (mycket experimentell parser)

Det dokumentformat som används av Org-läget. Stödet för denna modul i po4a är fortfarande i sin linda. Om du upptäcker något, vänligen rapportera ett fel eller en funktionsförfrågan.

vimhelp (mycket experimentell parser)

Formatet som används för Vim-hjälpfiler (och viss dokumentation för plugin-program från tredje part). Stödet för detta format i po4a är fortfarande i sin linda. Om du upptäcker något, vänligen skicka in en felrapport eller en funktionsförfrågan.

simplepod (mycket experimentell parser)

I likhet med den tidigare nämnda pod använder denna den nya Pod::Simple som parser. Eftersom den är nyutvecklad kan vissa buggar förekomma. Om du upptäcker något konstigt beteende, vänligen meddela oss. Så småningom kommer denna modul att ersätta pod.

Andra format som stöds

Po4a kan också hantera vissa mer sällsynta eller specialiserade format, såsom dokumentation av kompileringsflaggor för Linux-kärnorna 2.4+ (Locale::Po4a::KernelHelp) eller diagram som skapats med verktyget dia (Locale::Po4a::Dia). Det är ofta mycket enkelt att lägga till ett nytt format och det viktigaste är att ta fram en parser för det format du vill använda. Se Locale::Po4a::TransTractor(3pm) för mer information om detta.

Format som inte stöds

Tyvärr saknar po4a fortfarande stöd för flera dokumentationsformat. Många av dem skulle vara lätta att stödja i po4a. Detta inkluderar format som inte bara används för dokumentation, såsom paketbeskrivningar (deb och rpm), frågor om paketinstallationsskript, paketändringsloggar och alla specialiserade filformat som används av program såsom spelscenarier eller wine-resursfiler.

Detaljerad översikt över po4a-arbetsflödet¶

Läs po4a(1) innan du går vidare till detta mycket detaljerade avsnitt för att få en förenklad översikt över po4a-arbetsflödet. Kom tillbaka hit när du vill få en fullständig bild, med nästan alla detaljer.

I följande schema är master.doc ett exempel på namnet på dokumentationen som ska översättas; XX.doc är samma dokument översatt till språket XX, medan doc.XX.po är översättningskatalogen för det dokumentet på språket XX. Dokumentationsförfattare kommer främst att arbeta med master.doc (som kan vara en man-sida, ett XML-dokument, en AsciiDoc-fil etc.), översättarna kommer främst att arbeta med PO-filen, medan slutanvändarna endast kommer att se filen XX.doc.

Övergångar med hakparenteser, såsom "[po4a uppdaterar po]", representerar körningen av ett po4a-verktyg, medan övergångar med klamrar, såsom "{uppdatering av master.doc}" representerar en manuell modifiering av projektets filer.

                                   master.doc
                                       |
                                       V
     +<-----<----+<-----<-----<--------+------->-------->-------+
     :           |                     |                        :
{translation}    |          {update of master.doc}              :
     :           |                     |                        :
   XX.doc        |                     V                        V
 (optional)      |                 master.doc ->-------->------>+
     :           |                   (new)                      |
     V           V                     |                        |
  [po4a-gettextize]   doc.XX.po -->+   |                        |
          |            (old)       |   |                        |
          |              ^         V   V                        |
          |              |   [po4a updates po]                  |
          V              |           |                          V
   translation.pot       ^           V                          |
          |              |        doc.XX.po                     |
          |              |         (fuzzy)                      |
    {translation}        |           |                          |
          |              ^           V                          V
          |              |     {manual editing}                 |
          |              |           |                          |
          V              |           V                          V
      doc.XX.po --->---->+<---<-- doc.XX.po    addendum     master.doc
      (initial)                 (up-to-date)  (optional)   (up-to-date)
          :                          |            |             |
          :                          V            |             |
          +----->----->----->------> +            |             |
                                     |            |             |
                                     V            V             V
                                     +------>-----+------<------+
                                                  |
                                                  V
                                     [po4a updates translations]
                                                  |
                                                  V
                                                XX.doc
                                             (up-to-date)

Återigen är detta schema alltför komplicerat. Se po4a(1) för en förenklad översikt.

Den vänstra delen visar hur po4a-gettextize(1) kan användas för att konvertera ett befintligt översättningsprojekt till po4a-infrastrukturen. Detta skript tar ett originaldokument och dess översatta motsvarighet och försöker skapa motsvarande PO-fil. En sådan manuell konvertering är ganska omständlig (se dokumentationen för po4a-gettextize(1) för mer information), men den behövs bara en gång för att konvertera dina befintliga översättningar. Om du inte har några översättningar att konvertera kan du strunta i detta och fokusera på den högra delen av schemat.

I den övre högra delen visas den ursprungliga författarens åtgärd, uppdatering av dokumentationen. Den mellersta högra delen visar de automatiska uppdateringarna av översättningsfilerna: det nya materialet extraheras och jämförs med den befintliga översättningen. Den tidigare översättningen används för de delar som inte har ändrats, medan delvis modifierade delar kopplas till den tidigare översättningen med en "fuzzy"-markör som indikerar att översättningen måste uppdateras. Nytt eller kraftigt modifierat material lämnas oöversatt.

Sedan visar I-<manual editing> -blocket översättarnas arbete, som modifierar PO-filerna för att tillhandahålla översättningar till varje originalsträng och originalstycke. Detta kan göras med hjälp av antingen en specifik editor såsom B-<GNOME Translation Editor>, KDE:s B-<Lokalize> eller B-<poedit>, eller med hjälp av en online-lokaliseringsplattform såsom B-<weblate> eller B-<pootle>. Översättningsresultatet är en uppsättning PO-filer, en per språk. Se gettext-dokumentationen för mer information.

Den nedre delen av figuren visar hur po4a skapar ett översatt källdokument från master.doc originaldokumentet och doc.XX.po översättningskatalogen som uppdaterats av översättarna. Dokumentets struktur återanvänds, medan det ursprungliga innehållet ersätts med dess översatta motsvarighet. Valfritt kan ett tillägg användas för att lägga till extra text till översättningen. Detta används ofta för att lägga till översättarens namn till det slutliga dokumentet. Se nedan för mer information.

När po4a anropas uppdateras både översättningsfilerna och de översatta dokumentationsfilerna automatiskt.

Starta ett nytt översättningsprojekt¶

Om du börjar från grunden behöver du bara skriva en konfigurationsfil för po4a, så är du klar. Relevanta mallar skapas för de filer som saknas, så att dina bidragsgivare kan översätta ditt projekt till sitt språk. Se po4a(1) för en snabbstartsguide och alla detaljer.

Om du har en befintlig översättning, dvs. en dokumentationsfil som har översatts manuellt, kan du integrera dess innehåll i ditt po4a-arbetsflöde med hjälp av po4a-gettextize. Denna uppgift är lite besvärlig (som beskrivs i verktygets manual), men när ditt projekt väl har konverterats till po4a-arbetsflöde kommer allt att uppdateras automatiskt.

Uppdatering av översättningar och dokument¶

När det är konfigurerat räcker det att anropa po4a för att uppdatera både översättningsfilerna (PO-filer) och de översatta dokumenten. Du kan skicka "--no-translations" till po4a för att inte uppdatera översättningarna (och därmed bara uppdatera PO-filerna) eller "--no-update" för att inte uppdatera PO-filerna (och därmed bara uppdatera översättningarna). Detta motsvarar ungefär de enskilda skripten po4a-updatepo och po4a-translate som nu är föråldrade (se "Varför är de enskilda skripten föråldrade" i FAQ nedan).

Använda tillägg för att lägga till extra text i översättningar¶

Att lägga till ny text i översättningen är förmodligen det enda som är enklare på lång sikt när du översätter filer manuellt :). Detta inträffar när du vill lägga till ett extra avsnitt i det översatta dokumentet, som inte motsvarar något innehåll i originaldokumentet. Det klassiska användningsfallet är att ge krediter till översättningsteamet och att ange hur man rapporterar översättningsspecifika problem.

Med po4a måste du ange B-<addendum> -filer, som konceptuellt kan ses som patchar som appliceras på det lokaliserade dokumentet efter bearbetning. Varje tillägg måste tillhandahållas som en separat fil, vars format dock skiljer sig mycket från de klassiska patcharna. Den första raden är en I-<header line>, som definierar infogningspunkten för tillägget (med en tyvärr kryptisk syntax – se nedan), medan resten av filen läggs till ordagrant på den bestämda positionen.

Rubrikraden måste börja med strängen PO4A-HEADER:, följt av en semikolonseparerad lista med fälten key=value.

Till exempel deklarerar följande rubrik ett tillägg som måste placeras i slutet av översättningen.

 PO4A-HEADER: mode=eof

Det blir mer komplicerat när du vill lägga till extra innehåll mitt i dokumentet. Följande rubrik deklarerar ett tillägg som måste placeras efter XML-sektionen som innehåller strängen "About this document" i översättningen.

 PO4A-HEADER: position=Om detta dokument; mode=after; endboundary=</section>

I praktiken söker po4a, när det försöker tillämpa ett tillägg, efter den första raden som matchar argumentet "position" (detta kan vara ett reguljärt uttryck). Glöm inte att po4a här beaktar dokumentet translated. Denna dokumentation är på engelska, men din rad bör antagligen se ut som följer om du vill att ditt tillägg ska tillämpas på den franska översättningen av dokumentet.

 PO4A-HEADER: position=Om detta dokument; mode=after; endboundary=</section>

När C-<position> en har hittats i måldokumentet söker po4a efter nästa rad efter C-<position> en som matchar den angivna C-<endboundary> en. Tillägget läggs till direkt B-<after> om den raden (eftersom vi angav en I-<endboundary>, dvs. en gräns som avslutar det aktuella avsnittet).

Exakt samma effekt kan uppnås med följande rubrik, som är likvärdig:

 PO4A-HEADER: position=Om detta dokument; mode=after; beginboundary=<section>

Här söker po4a efter den första raden som matchar "<section>" efter raden som matchar "About this document" i översättningen, och lägger till tillägget before den raden eftersom vi har angett en beginboundary, dvs. en gräns som markerar början på nästa avsnitt. Denna rubrikrad kräver alltså att tillägget placeras efter avsnittet som innehåller "About this document" och att po4a instrueras att ett avsnitt börjar med en rad som innehåller <section> taggen </section> "<section>". Detta motsvarar föregående exempel eftersom det du egentligen vill är att lägga till detta tillägg antingen efter "</section>":</section> > eller före "<section>".

Du kan också ställa in infognings<mode> en till värdet "before", med en liknande semantik: genom att kombinera "mode=before" med en "endboundary" kommer tillägget att placeras precis after den matchade gränsen, det vill säga den sista potentiella gränsen före "position". Genom att kombinera "mode=before" med en "beginboundary" kommer tillägget att placeras precis before den matchade gränsen, det vill säga den sista potentiella gränsen före "position".

  Läge   | Gränstyp      |     Använd gräns        | Infogningspunkt jämfört med gränsen
 ========|===============|========================|=========================================
 'before'| 'endboundary' | last before 'position' | Direkt efter den valda gränsen
 'before'|'beginboundary'| last before 'position' | Direkt före den valda gränsen
 'after' | 'endboundary' | first after 'position' | Direkt efter den valda gränsen
 'after' |'beginboundary'| first after 'position' | Direkt före den valda gränsen
 'eof'   |   (none)      |  n/a                   | Slut på fil

Tips och tricks om tillägg

• Kom ihåg att detta är reguljära uttryck. Om du till exempel vill matcha slutet på en nroff-sektion som slutar med raden ".fi", ska du inte använda ".fi" som endboundary, eftersom det kommer att matcha "the[ fi]le", vilket uppenbarligen inte är vad du förväntar dig. Det korrekta endboundary i det fallet är: "^\.fi$".
• Vita utrymmen ÄR viktiga i innehållet i "position" och gränserna. Så de två följande raderna are different. Den andra kommer endast att hittas om det finns tillräckligt med efterföljande utrymmen i det översatta dokumentet.

   PO4A-HEADER: position=Om detta dokument; mode=after; beginboundary=<section>
   PO4A-HEADER: position=Om detta dokument ; mode=after; beginboundary=<section>
      

• Även om denna kontextsökning kan anses fungera ungefär på varje rad i B-<translated> sdokumentet, fungerar den i själva verket på den interna datasträngen i det översatta dokumentet. Denna interna datasträng kan vara en text som sträcker sig över ett stycke som innehåller flera rader eller kan vara en XML-tagg i sig själv. Den exakta I-<insertion point> en av tillägget måste vara före eller efter den interna datasträngen och kan inte finnas inom den interna datasträngen.
• Skicka argumentet "-vv" till po4a för att förstå hur tilläggen läggs till i översättningen. Det kan också vara bra att köra po4a i felsökningsläge för att se den faktiska interna datasträngen när ditt tillägg inte gäller.

Exempel på tillägg

• Om du vill lägga till något efter följande nroff-avsnitt:

    .SH "UPPHOVSPERSONER"
      

  Du bör välja en tvåstegsmetod genom att ställa in mode=after. Sedan bör du begränsa sökningen till raden efter AUTHORS med argumentet position regex. Därefter bör du matcha början av nästa avsnitt (dvs. ^\.SH) med argumentet beginboundary regex. Det vill säga:

   PO4A-HEADER:läge=efter;position=FÖRFATTARE;början av gräns=\.SH
      

• Om du vill lägga till något direkt efter en viss rad (t.ex. efter raden "Copyright Big Dude"), använd en B-<position> som matchar denna rad, B-<mode=after>, och ange en B-<beginboundary>, som matchar vilken rad som helst.

   PO4A-HEADER:läge=efter;position=Copyright Big Dude, 2004;början=^
      

• Om du vill lägga till något i slutet av dokumentet, ange en position som matchar valfri rad i dokumentet (men endast en rad. Po4a fortsätter inte om den inte är unik) och ange en endboundary som inte matchar något. Använd inte enkla strängar här, såsom "EOF", utan välj hellre sådana som har mindre chans att förekomma i dokumentet.

   PO4A-HEADER:läge=efter;position=Om detta dokument;början av gräns=FakePo4aBoundary
      

Mer detaljerat exempel

Originaldokument (POD-format):

 |=head1 NAMN
 |
 |dummy - ett dummyprogram
 |
 |=head1 UPPHOVSPERSON
 |
 |jag

Därefter kommer följande tillägg att säkerställa att ett avsnitt (på franska) om översättaren läggs till i slutet av filen (på franska betyder "TRADUCTEUR" "ÖVERSÄTTARE" och "moi" betyder "jag").

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

För att lägga till ditt tillägg före FÖRFATTAREN, använd följande rubrik:

 PO4A-HEADER:läge=efter;position=NOM;början av gräns=^=head1

Detta fungerar eftersom nästa rad som matchar beginboundary "/^=head1/" efter avsnittet "NAME" (översatt till "NOM" på franska) är den som anger författarna. Tillägget kommer alltså att placeras mellan de båda avsnitten. Observera att om ett annat avsnitt läggs till mellan avsnitten NAME och AUTHOR senare, kommer po4a felaktigt att placera tilläggen före det nya avsnittet.

För att undvika detta kan du uppnå samma resultat med hjälp av mode=before:

 PO4A-HEADER:läge=före;position=^=head1 AUTEUR

TransTractors och projektarkitektur¶

I kärnan av po4a-projektet är klassen Locale::Po4a::TransTractor(3pm) den gemensamma förfadern till alla po4a-parsers. Detta märkliga namn kommer från det faktum att den samtidigt ansvarar för att översätta dokument och extrahera strängar.

Mer formellt krävs ett dokument att översätta samt en PO-fil som innehåller översättningarna som ska användas som indata för att producera två separata utdata: En annan PO-fil (resultatet av extraheringen av översättningsbara strängar från indatadokumentet) och ett översatt dokument (med samma struktur som indatadokumentet, men där alla översättningsbara strängar har ersatts med innehållet i indataprofilen). Här är en grafisk representation av detta:

   Input document --\                             /---> Output document
                     \      TransTractor::       /       (translated)
                      +-->--   parse()  --------+
                     /                           \
   Input PO --------/                             \---> Output PO
                                                       (extracted)

Denna lilla kod är kärnan i hela po4a-arkitekturen. Om du anger både indata och bortser från utdata PO får du po4a-translate. Om du istället bortser från utdatadokumentet får du po4a-updatepo. po4a använder en första TransTractor för att få en uppdaterad utdatapot-fil (utan att ta hänsyn till utdatadokumenten), anropar msgmerge -U för att uppdatera översättningspo-filerna på disken och bygger en andra TransTractor med dessa uppdaterade po-filer för att uppdatera utdatadokumenten. Kort sagt, po4a erbjuder en helhetslösning för att uppdatera det som behövs, med hjälp av en enda konfigurationsfil.

po4a-gettextize använder också två TransTractors, men på ett annat sätt: Det skapar en TransTractor per språk och skapar sedan en ny PO-fil med msgids från originaldokumentet som msgids och msgids från det översatta dokumentet som msgstrs. Det krävs stor noggrannhet för att säkerställa att strängarna som matchas på detta sätt verkligen matchar, vilket beskrivs i po4a-gettextize(1).

Formatspecifika parsers¶

Alla po4a-formatparsers är implementerade ovanpå TransTractor. Vissa av dem är mycket enkla, såsom Text, Markdown och AsciiDoc. De laddar raderna en efter en med hjälp av TransTractor::shiftline(), samlar in innehållet i styckena eller vad det nu är. När en sträng är helt parsad använder parsern TransTractor::translate() för att (1) lägga till denna sträng till utdata-PO-filen och (2) hämta översättningen från inmatnings-PO-filen. Parsern skickar sedan resultatet till utdatafilen med hjälp av TransTractor::pushline().

Vissa andra parsers är mer komplexa eftersom de förlitar sig på en extern parser för att analysera indatadokumentet. Parsers för Xml, HTML, SGML och Pod är byggda på SAX-parsers. De deklarerar återkopplingar till händelser som "Jag har hittat en ny titel med följande innehåll" för att uppdatera utdatadokumentet och mata ut POT-filer enligt indatainnehållet med hjälp av TransTractor::translate() och TransTractor::pushline(). Yaml-parsern är liknande men ändå annorlunda: den serialiserar en datastruktur som producerats av YAML::Tiny-parsern. Det är därför som Yaml-modulen i po4a inte kan deklarera referensraderna: parsern sparar inte platsen för varje sträng i inmatningsfilen, så vi kan bara ange "$filename:1" som strängplats. De SAX-orienterade parsrarna använder globala variabler och andra knep för att spara filnamn och radnummer för referenser.

Ett specifikt problem uppstår i samband med filkodningar och BOM-markörer. Enkla parsers kan bortse från detta problem, som hanteras av TransTractor::read() (används internt för att hämta raderna i ett indatadokument), men moduler som är beroende av en extern parser måste se till att alla filer läses med ett lämpligt PerlIO-avkodningslager. Det enklaste är att öppna filen själv och tillhandahålla en filhanterare eller direkt hela strängen till din externa parser. Se Pod::read() och Pod::parse() för ett exempel. Innehållet som läses av TransTractor ignoreras, men ett nytt filhandtag skickas till den externa parsern. Den viktiga delen är läget "<:encoding($charset)" som skickas till open()-funktionen i Perl.

Po-objekt¶

Klassen Locale::Po4a::Po(3pm) ansvarar för att ladda och använda PO- och POT-filer. I grund och botten kan du läsa en fil, lägga till poster, hämta översättningar med metoden gettext() och skriva PO till en fil. Mer avancerade funktioner, såsom att slå samman en PO-fil med en POT-fil eller validera en fil, delegeras till msgmerge(1) respektive msgfmt(1).

Bidra till po4a¶

Även om du aldrig tidigare har bidragit till något öppen källkodsprojekt är du välkommen: vi är villiga att hjälpa och handleda dig här. po4a underhålls numera bäst av sina användare. Eftersom vi saknar arbetskraft försöker vi göra projektet välkomnande genom att förbättra dokumentationen och de automatiska testerna så att du känner dig trygg med att bidra till projektet. Se filen CONTRIBUTING.md för mer information.

Hur uttalar man po4a?¶

Personligen uttalar jag det som pouah <https://en.wiktionary.org/wiki/pouah>, vilket är ett franskt onomatopoetiskt uttryck som vi använder istället för yuck :) Jag kanske har ett konstigt sinne för humor :)

Varför är de enskilda skripten föråldrade?¶

Faktum är att po4a-updatepo och po4a-translate är föråldrade till förmån för po4a. Anledningen är att även om po4a kan användas som ersättning för dessa skript när du har tillhandahållit en konfigurationsfil, finns det ganska mycket kodduplicering här. Enskilda skript är cirka 150 rader långa, medan programmet po4a är 1200 rader långt, så de gör mycket utöver de gemensamma interna funktionerna. Koddupliceringen resulterar i buggar i båda versionerna och kräver två korrigeringar. Ett exempel på sådan duplicering är buggarna #1022216 i Debian och problemet #442 i GitHub som hade exakt samma korrigering, men den ena i po4a och den andra i po4a-updatepo.

På sikt skulle jag vilja slopa de enskilda skripten och bara behålla en version av den här koden. Det som är säkert är att de enskilda skripten inte kommer att förbättras längre, så endast po4a kommer att få de nya funktionerna. Med det sagt finns det ingen brådska att fasa ut dem. Jag planerar att behålla de enskilda skripten så länge som möjligt, och åtminstone fram till 2030. Om ditt projekt fortfarande använder po4a-updatepo och po4a-translate år 2030 kan du få problem.

Vi kan också ta bort avvecklingen av dessa skript vid någon tidpunkt, om en omstrukturering minskar koddupliceringen till noll. Om du har en idé (eller ännu bättre: en patch), är din hjälp välkommen.

Hur är det med andra översättningsverktyg för dokumentation som använder gettext?¶

Det finns några stycken. Här är en lista som kanske inte är komplett, och fler verktyg är på väg.

poxml

Detta är ett verktyg som utvecklats av KDE-teamet för att hantera DocBook XML. Såvitt jag vet var det det första programmet som extraherade strängar för översättning från dokumentation till PO-filer och infogade dem igen efter översättningen.

Den kan bara hantera XML och endast en viss DTD. Jag är ganska missnöjd med hanteringen av listor, som slutar i ett stort msgid. När listan blir stor blir biten svårare att smälta.

po-debiandoc

Detta program, utvecklat av Denis Barbier, är en sorts föregångare till po4a SGML-modulen, som mer eller mindre har gjort det föråldrat. Som namnet antyder hanterar det endast DebianDoc DTD, som mer eller mindre är en föråldrad DTD.

xml2po.py

Används av GIMP Documentation Team sedan 2004, fungerar ganska bra även om det, som namnet antyder, endast fungerar med XML-filer och kräver specialkonfigurerade makefiler.

Sphinx

Sphinx Documentation Project använder också gettext i stor utsträckning för att hantera sina översättningar. Tyvärr fungerar det bara för några få textformat, rest och markdown, även om det kanske är det enda verktyget som hanterar hela översättningsprocessen.

De främsta fördelarna med po4a jämfört med dem är att det är enkelt att lägga till extra innehåll (vilket är ännu svårare där) och möjligheten att uppnå gettextisering.

SAMMANFATTNING av fördelarna med den gettextbaserade metoden¶

• Översättningarna lagras inte tillsammans med originalet, vilket gör det möjligt att upptäcka om översättningarna blir inaktuella.
• Översättningarna lagras i separata filer, vilket förhindrar att översättare av olika språk stör varandra, både när de skickar in sina patchar och på filkodningsnivå.
• Det baseras internt på gettext (men po4a erbjuder ett mycket enkelt gränssnitt så att du inte behöver förstå det interna för att kunna använda det). På så sätt behöver vi inte implementera hjulet på nytt, och tack vare deras breda användning kan vi anta att dessa verktyg är mer eller mindre buggfria.
• Ingenting förändrades för slutanvändaren (förutom att översättningarna förhoppningsvis kommer att underhållas bättre). Den resulterande dokumentationsfilen som distribueras är exakt densamma.
• Översättare behöver inte lära sig någon ny filsyntax och deras favoritredigerare för PO-filer (som Emacs PO-läge, Lokalize eller Gtranslator) fungerar utan problem.
• gettext erbjuder ett enkelt sätt att få statistik om vad som är gjort, vad som bör granskas och uppdateras och vad som återstår att göra. Några exempel finns på följande adresser:

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

Men allt är inte grönt, och denna strategi har också några nackdelar som vi måste ta itu med.

• Tillägg är något konstiga vid första anblicken.
• Du kan inte anpassa den översatta texten efter dina önskemål, till exempel dela upp ett stycke här och slå ihop två andra där. Men i viss mening bör ett problem med originalet ändå rapporteras som ett fel.
• Även om gränssnittet är enkelt är det fortfarande ett nytt verktyg som människor måste lära sig.

  En av mina drömmar skulle vara att på något sätt integrera po4a i Gtranslator eller Lokalize. När en dokumentationsfil öppnas extraheras strängarna automatiskt, och en översatt fil + po-fil kan skrivas till disken. Om vi lyckas skapa en MS Word (TM)-modul (eller åtminstone RTF) kan professionella översättare till och med använda den.