Snabbstartsguide¶

Låt oss anta att du underhåller ett program som heter foo som har en man-sida man/foo.1 skriven på engelska (det gemensamma språket i de flesta öppen källkodsprojekt, men po4a kan användas från eller till vilket språk som helst). För en tid sedan tillhandahöll någon en tysk översättning med namnet man/foo.de.1 och försvann sedan. Detta är ett problem eftersom du just fått en felrapport om att din dokumentation innehåller allvarligt missvisande information som måste korrigeras på alla språk, men du talar inte tyska så du kan bara ändra originalet, inte översättningen. Nu vill en annan bidragsgivare bidra med en översättning till japanska, ett språk som du inte heller behärskar.

Det är dags att konvertera din dokumentation till po4a för att lösa dina dokumentationsunderhållsproblem. Du vill uppdatera dokumentationen när det behövs, du vill underlätta arbetet för dina kollegor och du vill se till att dina användare aldrig ser någon föråldrad och därmed missvisande dokumentation.

Konverteringen består av två steg: installera po4a-infrastrukturen och konvertera den tidigare tyska översättningen för att rädda det tidigare arbetet. Den senare delen görs med hjälp av po4a-gettextize enligt följande. Som beskrivs i dokumentationen för po4a-gettextize(1) är denna process sällan helt automatisk, men när den väl är klar kan filen de.po som innehåller den tyska översättningen integreras i ditt po4a-arbetsflöde.

  po4a-gettextize --format man --master foo.1 --localized foo.de.1 --po de.po

Låt oss nu konfigurera po4a. Med rätt filstruktur kan din konfigurationsfil se ut så här:

 [po_directory] man/po4a/
 [type: man] man/foo.1 $lang:man/translated/foo.$lang.1

Det anger att alla PO-filer (som innehåller översättarnas arbete) finns i katalogen man/po4a/ och att du bara har en huvudfil, man/foo.1. Om du hade flera huvudfiler skulle du ha flera rader som liknar den andra. Varje sådan rad anger också var motsvarande översättningsfiler ska skrivas. Här finns den tyska översättningen av man/foo.1 i man/translated/foo.de.1.

Det sista vi behöver för att slutföra konfigurationen av po4a är en POT-fil som innehåller mallmaterialet som ska användas för att starta en ny översättning. Skapa helt enkelt en tom fil med filändelsen .pot i den angivna po_directory (t.ex. man/po4a/foo.pot), så fyller po4a den med det förväntade innehållet.

Här är en sammanfattning av filerna i denna installation:

  ├── man/
  │   ├── foo.1        <- Den ursprungliga man-sidan, på engelska
  │   ├── po4a/
  │   │   ├── de.po    <- Den tyska PO-översättningen, från gettextization
  │   │   └── foo.pot  <- POT-mallen för framtida översättningar (tom i början)
  │   └── translated/  <- Katalog där översättningarna kommer att skapas
  └── po4a.cfg         <- Konfigurationsfilen

När det är konfigurerat kommer kommandot po4a att analysera din dokumentation, uppdatera POT-mallfilen, använda den för att uppdatera PO-översättningsfilerna och använda dem för att uppdatera dokumentationsöversättningsfilerna. Allt i ett kommando:

        po4a --verbose po4a.cfg

Det var allt. po4a är nu helt konfigurerat. När du har rättat felet i man/foo.1 kommer den felaktiga paragrafen i den tyska översättningen att ersättas med den korrigerade texten på engelska. Att blanda språk är inte optimalt, men det är det enda sättet att ta bort fel i översättningar som du inte ens förstår och säkerställa att innehållet som presenteras för användarna aldrig är missvisande. Det är också mycket enklare att uppdatera den tyska översättningen i motsvarande PO-fil, så språkblandningen kanske inte varar så länge. Slutligen, när en japansk översättare vill bidra med en ny översättning, bör hon byta namn på foo.pot till ja.po och slutföra översättningen. När du har den här filen lägger du bara in den i man/po4a/po/. En översatt sida visas som man/translated/foo.ja.1 (förutsatt att tillräckligt med innehåll är översatt) när du kör po4a igen.

Flaggor som modifierar POT-rubriken¶

--porefs type

Ange referensformatet. Argumentet type kan vara never för att inte skapa någon referens, file för att endast ange filen utan radnummer, counter för att ersätta radnumret med en ökande räknare och full för att inkludera fullständiga referenser (standard: full).

--wrap-po no|newlines|number (standard: 76)

Ange hur po-filen ska formateras. Detta ger valet mellan antingen filer som är snyggt formaterade men som kan leda till git-konflikter, eller filer som är lättare att hantera automatiskt, men svårare att läsa för människor.

Historiskt sett har gettext-paketet omformaterat po-filerna vid den 77:e kolumnen av kosmetiska skäl. Denna flagga anger po4a:s beteende. Om det är inställt på ett numeriskt värde kommer po4a att bryta po-filen efter denna kolumn och efter radbrytningar i innehållet. Om det är inställt på newlines kommer po4a endast att dela upp msgid och msgstr efter radbrytningar i innehållet. Om det är inställt på no kommer po4a inte att bryta po-filen alls. Referenskommmentarerna bryts alltid av de gettext-verktyg som vi använder internt.

Baserat på värdet för denna flagga kommer lämpliga flaggor (--no-wrap eller --width=number) att skickas till underliggande gettext-verktyg. Tyvärr har gettext ingen motsvarighet till --wrap-po no, så i det fallet kommer --no-wrap att skickas (samma som för --wrap-po newlines).

Observera att denna flagga inte påverkar hur msgid och msgstr bryts, dvs. hur radbrytningar läggs till i innehållet i dessa strängar.

--master-language

Språket i källfilerna som innehåller dokumenten som ska översättas. Observera att alla originaldokument måste vara skrivna på samma språk.

--msgid-bugs-address email@address

Ställ in rapportadressen för msgid-buggar. Som standard har de skapade POT-filerna inga Report-Msgid-Bugs-To-fält.

--copyright-holder string

Ange upphovsrättsinnehavaren i POT-rubriken. Standardvärdet är "Free Software Foundation, Inc."

--package-name string

Ange paketnamnet för POT-rubriken. Standardvärdet är "PACKAGE".

--package-version string

Ställ in paketversionen för POT-rubriken. Standardvärdet är "VERSION".

Flaggor för att ändra PO-filerna¶

--msgmerge-opt options

Extra flaggor för msgmerge(1).

Obs: $lang kommer att utökas till det aktuella språket.

--no-previous

Den här flaggan tar bort --previous från flaggorna som skickas till msgmerge(1). Det här är nödvändigt för att stödja versioner av gettext(3) som är äldre än 0.16.

--previous

Den här flaggan lägger till --previous till flaggorna som skickas till msgmerge(1). Det kräver gettext(3) 0.16 eller senare och är aktiverat som standard.

Hitta PO- och POT-filerna¶

Den enklaste lösningen är att uttryckligen ange sökvägen till POT- och PO-filerna, enligt följande:

 [po4a_paths] man/po/project.pot de:man/po/de.po fr:man/po/fr.po

Här anges först sökvägen till POT-filen och sedan sökvägarna till de tyska och franska PO-filerna.

Samma information kan skrivas på följande sätt för att minska risken för kopierings-/klistringsfel:

 [po4a_langs] fr de
 [po4a_paths] man/po/project.pot $lang:man/po/$lang.po

Komponenten $lang expanderas automatiskt med hjälp av den medföljande språklistan, vilket minskar risken för kopierings-/klistringsfel när ett nytt språk läggs till.

Du kan komprimera samma information ytterligare genom att endast ange sökvägen till katalogen som innehåller ditt översättningsprojekt, enligt följande.

 [po_directory] man/po/

Den angivna katalogen måste innehålla en uppsättning PO-filer, var och en med namnet XX.po där "XX" är ISO 639-1-koden för det språk som används i filen. Katalogen måste också innehålla en enda POT-fil med filändelsen ".pot". Vid första körningen kan denna fil vara tom, men den måste finnas (po4a kan inte gissa namnet som ska användas före filändelsen).

Observera att du måste välja endast en av flaggorna "po_directory" och "po4a_paths". Den första flaggan ("po_directory") är mer kompakt och minskar risken för kopierings-/klistringsfel, men tvingar dig att använda den förväntade projektstrukturen och filnamnen. Den andra ("po4a_paths") är mer explicit, förmodligen mer läsbar och rekommenderas när du konfigurerar ditt första projekt med po4a.

Centraliserade eller delade PO-filer?

Som standard skapar po4a en enda PO-fil per målspråk, som innehåller hela innehållet i ditt översättningsprojekt. När projektet växer kan storleken på dessa filer bli ett problem. När du använder weblate är det möjligt att ange prioriteringar för varje översättningssegment (dvs. msgid) så att de viktiga översätts först. Vissa översättningsteam föredrar ändå att dela upp innehållet i flera filer.

För att ha en PO-fil per huvudfil behöver du bara använda strängen $master i namnet på dina PO-filer på raden "[po4a_paths]", enligt följande.

 [po4a_paths] doc/$master/$master.pot $lang:doc/$master/$lang.po

Med denna rad kommer po4a att skapa separata POT- och PO-filer för varje dokument som ska översättas. Om du till exempel har 3 dokument och 5 språk kommer detta att resultera i 3 POT-filer och 15 PO-filer. Dessa filer namnges enligt specifikationen i mallen "po4a_paths", där $master ersätts med basnamnet på varje dokument som ska översättas. Vid namnskonflikter kan du ange vilken POT-fil som ska användas på följande sätt, med parametern "pot=".

Denna funktion kan också användas för att gruppera flera översatta filer i samma POT-fil. Följande exempel ger endast två POT-filer: l10n/po/foo.pot (innehåller materialet från foo/gui.xml) och l10n/po/bar.pot (innehåller materialet från både bar/gui.xml och bar/cli.xml).

 [po4a_langs] de fr ja
 [po4a_paths] l10n/po/$master.pot $lang:l10n/po/$master.$lang.po
 [type: xml] foo/gui.xml $lang:foo/gui.$lang.xml pot=foo
 [type: xml] bar/gui.xml $lang:bar/gui.$lang.xml pot=bar
 [type: xml] bar/cli.xml $lang:bar/cli.$lang.xml pot=bar

I delat läge skapar po4a ett tillfälligt kompendium under PO-uppdateringen för att dela översättningarna mellan alla PO-filer. Om två PO-filer har olika översättningar för samma sträng markerar po4a denna sträng som oklar och skickar båda översättningarna i alla PO-filer som innehåller denna sträng. När översättaren har klargjort översättningen används den automatiskt i alla PO-filer.

Ange vilka dokument som ska översättas¶

Du måste också ange vilka dokument som ska översättas. För varje huvudfil måste du ange vilken formatparser som ska användas, var det översatta dokumentet ska sparas och eventuellt vissa konfigurationsinställningar. Filnamn ska anges inom citationstecken eller med escape-tecken om de innehåller mellanslag. Här är ett exempel:

 [type: sgml] "doc/my stuff.sgml"  "fr:doc/fr/mon truc.sgml"  de:doc/de/mein\ kram.sgml
 [type: man] script fr:doc/fr/script.1 de:doc/de/script.1
 [type: docbook] doc/script.xml fr:doc/fr/script.xml \
             de:doc/de/script.xml

Men återigen är dessa komplexa rader svåra att läsa och ändra, t.ex. när man lägger till ett nytt språk. Det är mycket enklare att omorganisera saker med hjälp av mallen $lang enligt följande:

 [type: sgml]    doc/my_stuff.sgml $lang:doc/$lang/my_stuff.sgml
 [type: man]     script.1          $lang:po/$lang/script.1
 [type: docbook] doc/script.xml    $lang:doc/$lang/script.xml

Ange flaggor¶

Det finns två typer av flaggor: po4a options är standardvärden för po4a-kommandoradsflaggorna, medan format options används för att ändra formatparsarnas beteende. Som ett po4a options kan du till exempel ange i din konfigurationsfil att standardvärdet för kommandoradsparametern --keep är 50% i istället för 80 %. Format options finns dokumentation på den specifika sidan för varje parsningsmodul, t.ex. Locale::Po4a::Xml(3pm). Du kan till exempel skicka nostrip till XML-parsern för att inte ta bort mellanslagen runt de extraherade strängarna.

Du kan skicka dessa flaggor för en specifik huvudfil, eller till och med för en specifik översättning av den filen, med hjälp av "opt:" och "opt_XX:" för språket "XX". I följande exempel skickas flaggan nostrip till XML-tolkaren (för alla språk), medan tröskelvärdet reduceras till 0% f för den franska översättningen (som därmed alltid behålls).

 [type:xml] toto.xml $lang:toto.$lang.xml opt:"-o nostrip" opt_fr:"--keep 0"

I alla fall måste dessa konfigurationsdelar placeras i slutet av raden. Deklarationen av filer måste komma först, sedan eventuella tillägg (se nedan) och därefter endast flaggorna. Grupperingen av konfigurationsdelar är inte särskilt viktig, eftersom elementen internt sammanfogas som strängar. Följande exempel är alla likvärdiga:

  [type:xml] toto.xml $lang:toto.$lang.xml opt:"--keep 20" opt:"-o nostrip" opt_fr:"--keep 0"
  [type:xml] toto.xml $lang:toto.$lang.xml opt:"--keep 20 -o nostrip" opt_fr:"--keep 0"
  [type:xml] toto.xml $lang:toto.$lang.xml opt:--keep opt:20 opt:-o opt:nostrip opt_fr:--keep opt_fr:0

Observera att språkspecifika flaggor inte används när POT-filen skapas. Det är till exempel omöjligt att endast skicka nostrip till parsern när den franska översättningen skapas, eftersom samma POT-fil används för att uppdatera alla språk. De enda flaggor som kan vara språkspecifika är därför de som används när översättningen skapas, såsom flaggan "--keep".

Konfigurationsalias

För att överföra samma flaggor till flera filer är det bäst att definiera ett typalias enligt följande. I nästa exempel överförs "--keep 0" till alla italienska översättningar med hjälp av denna "test" -typ, som är en utvidgning av "man" -typen.

  [po4a_alias:test] man opt_it:"--keep 0"
  [type: test] man/page.1 $lang:man/$lang/page.1

Du kan också utöka en befintlig typ genom att återanvända samma namn för aliaset på följande sätt. Detta tolkas inte som en felaktig rekursiv definition.

  [po4a_alias:man] man opt_it:"--keep 0"
  [type: man] man/page.1 $lang:man/$lang/page.1

Globala standardflaggor

Du kan också använda "[options]"-rader för att definiera flaggor som måste användas för alla filer, oavsett typ.

  [flaggor] --keep 20 --option nostrip

Precis som med kommandoradsflaggor kan du förkorta parametrarna som skickas i konfigurationsfilen:

  [flaggor] -k 20 -o nostrip

Flaggprioriteringar

Flaggorna för varje källa är sammankopplade, vilket säkerställer att standardvärdena enkelt kan åsidosättas av mer specifika flaggor. Ordningen är följande:

• "[options]"-rader anger standardvärden som kan åsidosättas av andra källor.
• Därefter används typalias. Språkspecifika inställningar åsidosätter de inställningar som gäller för alla språk.
• Inställningar som är specifika för en viss huvudfil åsidosätter både standardinställningarna och de som kommer från typalias. Även i detta fall åsidosätter språkspecifika inställningar de globala inställningarna.
• Slutligen åsidosätter parametrar som anges på kommandoraden för B-<po4a> en alla inställningar från konfigurationsfilen.

Exempel

Här är ett exempel som visar hur man citerar mellanslag och citattecken:

 [po_directory] man/po/
 
 [options] --master-charset UTF-8
 
 [po4a_alias:man] man opt:"-o \"mdoc=NAME,SEE ALSO\""
 [type:man] t-05-config/test02_man.1 $lang:tmp/test02_man.$lang.1 \
            opt:"-k 75" opt_it:"-L UTF-8" opt_fr:--verbose

Context¶

po4a supports context features such as "msgctxt" in the GNU gettext PO file format. See GNU gettext utilities - Contexts <https://www.gnu.org/software/gettext/manual/html_node/Contexts.html> for the motivation behind this feature. In short, it allows multiple messages with the same "msgid" (master language message) to coexist in a single PO file. Here's a simple example. Consider this Markdown document, context.md:

  # Foo
  Foo

In this case, both the title and paragraph share the same "msgid" "Foo". If we want to translate the title "Foo" as "BAR" and the paragraph "Foo" as "Bar", we encounter a problem: the PO file only supports one message for this msgid, forcing us to choose a single translation. This is where the context feature becomes useful. By tagging each message with a distinct context—for example, "title" or "paragraph"—we can treat them as separate messages, allowing each to have its own translation in the generated output.

This may sound appealing, but it can be complicated to use due to its maximum flexibility. The "context-module" option takes a Perl module name, which must contain a "get_msgctxt" subroutine. A minimal example looks like this:

  package ContextExample;
  use strict;
  use warnings;
  sub get_msgctxt {
      my $args = shift;
      $args->{msgid} eq 'Foo' or return;
      if ( $args->{type} eq 'Title #' ) {
          return 'title';
      } else {
          return 'paragraph';
      }
  }
  1;

Save this Perl module to "/path/to/lib/ContextExample.pm". The configuration file "/path/to/po4a.conf" should contain the following:

  [po4a_paths] master.pot trans:translation.po
  [type:Text] context.md trans:translation.md \
              opt:"--option markdown \
                   --context-module=ContextExample"

Then run "PERL5LIB=/path/to/lib:$PERL5LIB po4a /path/to/po4a.conf". Note that you must set the Perl library path environment variable so that po4a can locate the provided module.

There are some important caveats when using this feature:

Choose context string values wisely

Embedding the "reference" value as-is is strongly discouraged because file paths tend to change, which would cause all messages with that context to change as well. Use concise, clear, and consistent context values that reflect your intention.

Unicode strings are normalized before being passed to your module

You may need to investigate the exact Perl string literal using debug print statements in your context module. For example, if the "msgid" contains "’" (a right single quotation mark), the value passed to the "get_msgctxt" subroutine will contain "\x{2019}" instead. In this case, you would write a conditional such as "$args-"{msgid} eq "\x{2019}scuse me?".>

Tillägg: Lägga till extra innehåll i översättningen¶

Om du vill lägga till ett extra avsnitt i översättningen, till exempel för att ge översättaren kredit, måste du definiera ett tillägg till raden som definierar din huvudfil. Se sidan po4a(7) för mer information om syntaxen för tilläggsfiler.

 [type: pod] script fr:doc/fr/script.1 \
             add_fr:doc/l10n/script.fr.add

Du kan också använda språkmallar enligt följande:

 [type: pod] script $lang:doc/$lang/script.1 \
             add_$lang:doc/l10n/script.$lang.add

Om ett tillägg inte är tillämpligt, kasseras översättningen.

Modifierare för tilläggsdeklarationen

Tilläggsmodifierare kan förenkla konfigurationsfilen i fall där inte alla språk har ett tillägg, eller när listan över tillägg varierar mellan olika språk. Modifieraren är ett enda tecken som placeras före filnamnet.

?

Inkludera addendum_path om denna fil finns, annars gör ingenting.

@

addendum_path är inte ett vanligt tillägg utan en fil som innehåller en lista med tillägg, ett per rad. Varje tillägg kan föregås av modifierare.

!

addendum_path kasseras, det laddas inte och kommer inte att laddas av någon ytterligare tilläggsspecifikation.

Följande inkluderar ett tillägg på valfritt språk, men endast om det finns. Inget fel rapporteras om tillägget inte finns.

 [type: pod] script $lang:doc/$lang/script.1  add_$lang:?doc/l10n/script.$lang.add

Nedan följer en lista med tillägg för varje språk:

 [type: pod] script $lang:doc/$lang/script.1  add_$lang:@doc/l10n/script.$lang.add

Filtrera de översatta strängarna¶

Ibland vill man dölja vissa strängar från översättningsprocessen. I så fall kan man ange en "pot_in"-parameter i huvudfilen för att ange namnet på den fil som ska användas istället för den riktiga huvudfilen när POT-filen skapas. Här är ett exempel:

  [type:docbook] book.xml          \
          pot_in:book-filtered.xml \
          $lang:book.$lang.xml

Med denna inställning kommer strängarna som ska översättas att extraheras från book-filtered.xml (som måste skapas innan po4a anropas), medan de översatta filerna kommer att skapas från book.xml. Som ett resultat kommer alla strängar som ingår i book.xml men inte i book-filtered.xml inte att inkluderas i PO-filerna, vilket förhindrar översättarna från att översätta dem. Dessa strängar kommer alltså att lämnas oförändrade när de översatta dokumenten skapas. Detta minskar naturligtvis översättningsnivån, så du kan behöva flaggan "--keep" för att säkerställa att dokumentet skapas ändå.