Tutorial de inițiere rapidă¶

Să presupunem că mențineți un program numit foo care are o pagină de manual man/foo.1 scrisă în limba engleză (limba punte în majoritatea proiectelor de cod sursă deschis, dar po4a poate fi utilizat din sau către orice limbă). Cu ceva timp în urmă, cineva a furnizat o traducere în limba germană numită man/foo.de.1 și a dispărut. Aceasta este o problemă pentru că tocmai ați primit un raport de eroare care spune că documentația dvs. conține o informație grav-înșelătoare care trebuie corectată în toate limbile, dar nu vorbiți germana, deci puteți modifica doar originalul, nu și traducerea. Acum, un alt contribuitor dorește să contribuie cu o traducere în japoneză, o limbă pe care nici tu nu o stăpânești.

Este timpul să vă convertiți documentația în po4a pentru a vă rezolva coșmarurile legate de întreținerea documentației. Doriți să actualizați documentația atunci când este necesar, doriți să ușurați munca colegilor dvs. traducători și doriți să vă asigurați că utilizatorii dvs. nu văd niciodată o documentație învechită și, prin urmare, înșelătoare.

Conversia include două etape: configurarea infrastructurii po4a și convertirea traducerii germane anterioare pentru a salva munca anterioară. Această ultimă parte este realizată utilizând po4a-gettextize, după cum urmează. După cum se detaliază în documentația po4a-gettextize(1), acest proces rareori este complet automat, dar odată realizat, fișierul de.po care conține traducerea germană poate fi integrat în fluxul de lucru po4a.

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

Să configurăm acum po4a. Cu aspectul corespunzător al fișierului, fișierul dvs. de configurare ar putea fi la fel de simplu ca acesta:

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

Aceasta specifică faptul că toate fișierele PO (care conțin munca traducătorilor) se află în directorul man/po4a/ și că aveți un singur fișier principal, man/foo.1. Dacă ați avea mai multe fișiere principale, ați avea mai multe linii similare celei de-a doua. Fiecare astfel de linie specifică, de asemenea, unde să se scrie fișierele de traducere corespunzătoare. Aici, traducerea în limba germană a fișierului man/foo.1 este în man/translated/foo.de.1.

Ultimul lucru de care avem nevoie pentru a finaliza configurarea po4a este un fișier POT care conține materialul șablon care ar trebui utilizat pentru a începe o nouă traducere. Creați pur și simplu un fișier gol cu extensia .pot în directorul po_directory specificat (de exemplu, man/po4a/foo.pot), iar po4a îl va umple cu conținutul așteptat.

Iată o recapitulare a fișierelor din această configurație:

  ├── man/
  │   ├── foo.1        <- Pagina de manual originală, în limba engleză
  │   ├── po4a/
  │   │   ├── de.po    <- Traducerea PO în limba germană, de la gettextizare
  │   │   └── foo.pot  <- Șablonul POT al viitoarelor traduceri (gol la început)
  │   └── translated/  <- Directorul în care vor fi create traducerile
  └── po4a.cfg         <- Fișierul de configurare

Odată configurat, execuția po4a va analiza documentația, va actualiza fișierul șablon POT, îl va utiliza pentru a actualiza fișierele de traducere PO și le va utiliza pentru a actualiza fișierele de traducere a documentației. Totul într-o singură comandă:

        po4a --verbose po4a.cfg

Asta este tot. po4a este acum complet configurat. După ce ați corectat eroarea din man/foo.1, paragraful incorect din traducerea în germană va fi înlocuit cu textul corectat în engleză. Amestecarea limbilor nu este optimă, dar este singura modalitate de a elimina erorile din traduceri pe care nici măcar nu le înțelegeți și de a vă asigura că conținutul prezentat utilizatorilor nu este niciodată înșelător. Actualizarea traducerii în limba germană este, de asemenea, mult mai ușoară în fișierul PO corespunzător, astfel încât amestecul de limbi poate să nu dureze mult. În cele din urmă, atunci când un traducător japonez dorește să contribuie cu o nouă traducere, ar trebui să redenumească fișierul foo.pot în ja.po și să completeze traducerea. Odată ce aveți acest fișier, introduceți-l în man/po4a/po/. O pagină tradusă va apărea ca man/translated/foo.ja.1 (cu condiția ca o cantitate suficientă de conținut să fie tradusă) atunci când executați din nou po4a.

Opțiuni ce modifică antetul POT¶

--porefs tip

Specifică formatul referinței. Argumentul tip poate fi unul dintre never pentru a nu produce nicio referință, file pentru a specifica doar fișierul fără numărul de linie, counter pentru a înlocui numărul de linie cu un contor crescător și full pentru a include referințe complete (implicit: full).

--wrap-po no|newlines|număr (implicit: 76)

Specifică modul în care liniile din fișierul po ar trebui să fie încadrate. Acest lucru oferă posibilitatea de a alege între fișiere care sunt bine ajustate ca încadrare, dar ar putea duce la conflicte git, sau fișiere care sunt mai ușor de gestionat automat, dar mai greu de citit pentru oameni.

Din punct de vedere istoric, suita gettext a reformatat fișierele po la a 77-a coloană pentru cosmetică. Această opțiune specifică comportamentul lui po4a. Dacă este definită la o valoare numerică, po4a va împacheta fișierul po după această coloană și după noile linii din conținut. Dacă este definită la newlines, po4a va împărți doar msgid și msgstr după linii noi din conținut. Dacă este definită la no, po4a nu va încadra deloc fișierul po. Comentariile de referință sunt întotdeauna încadrate de instrumentele gettext pe care le folosim intern.

Rețineți că această opțiune nu are niciun impact asupra modului în care msgid și msgstr sunt încadrate, adică asupra modului în care sunt adăugate linii noi la conținutul acestor șiruri.

--master-language

Limba fișierelor sursă care conțin documentele de tradus. Rețineți că toate documentele principale trebuie să utilizeze aceeași limbă.

--msgid-bugs-address adresă@poștă.electronică

Definește adresa de raportare pentru erori din msgid. În mod implicit, fișierele POT create nu au câmpuri Report-Msgid-Bugs-To.

--copyright-holder șir

Definește deținătorul drepturilor de autor în antetul POT. Valoarea implicită este „Free Software Foundation, Inc.”

--package-name șir

Definește numele pachetului pentru antetul POT. Valoarea implicită este „PACKAGE”.

--package-version șir

Definește versiunea pachetului pentru antetul POT. Valoarea implicită este „VERSION”.

Opțiuni pentru modificarea fișierelor PO¶

--msgmerge-opt opțiuni

Opțiuni suplimentare pentru msgmerge(1).

Notă: $lang va fi extins la limba curentă.

--no-previous

Această opțiune elimină --previous din opțiunile transmise către msgmerge. Acest lucru este necesar pentru a oferi suport versiunilor de gettext anterioare versiunii 0.16.

--previous

Această opțiune adaugă --previous la opțiunile transmise către msgmerge. Aceasta necesită gettext 0.16 sau o versiune ulterioară și este activată implicit.

Găsirea fișierelor PO și POT¶

Cea mai simplă soluție este de a indica în mod explicit ruta către fișierele POT și PO, după cum urmează:

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

Aceasta specifică mai întâi ruta către fișierul POT și apoi rutele către fișierele PO în limbile germană și franceză.

Aceleași informații pot fi scrise după cum urmează pentru a reduce riscul de erori de copiere/lipire:

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

Componenta $lang este extinsă automat folosind lista de limbi furnizată, reducând riscul de erori de copiere/lipire atunci când este adăugată o limbă nouă.

Puteți compacta în continuare aceleași informații furnizând doar ruta către directorul care conține proiectul dvs. de traducere, după cum urmează.

 [po_directory] man/po/

Directorul furnizat trebuie să conțină un set de fișiere PO, fiecare denumit XX.po, "XX" fiind codul ISO 639-1 al limbii utilizate în acest fișier. Directorul trebuie să conțină, de asemenea, un singur fișier POT, cu extensia de fișier ".pot". Pentru prima rulare, acest fișier poate fi gol, dar trebuie să existe (po4a nu poate ghici numele de utilizat înainte de extensie).

Rețineți că trebuie să alegeți doar una dintre variantele "po_directory" și "po4a_paths". Prima ("po_directory") este mai compactă, reduce și mai mult riscul erorilor de copiere/lipire, dar vă obligă să utilizați structura de proiect și numele de fișiere așteptate. A doua ("po4a_paths"), este mai explicită, probabil mai ușor de citit și este recomandată atunci când configurați primul proiect cu po4a.

Fișiere PO centralizate sau divizate?

În mod implicit, po4a produce un singur fișier PO pentru fiecare limbă țintă, conținând întregul conținut al proiectului dvs. de traducere. Pe măsură ce proiectul dumneavoastră crește, dimensiunea acestor fișiere poate deveni problematică. Atunci când utilizați weblate, este posibil să specificați priorități pentru fiecare segment de traducere (de exemplu, msgid), astfel încât cele importante să fie traduse primele. Totuși, unele echipe de traducători preferă să împartă conținutul în mai multe fișiere.

Pentru a avea un fișier PO pentru fiecare fișier principal, trebuie doar să utilizați șirul $master în numele fișierelor PO de pe linia "[po4a_paths]", după cum urmează.

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

Cu această linie, po4a va produce fișiere POT și PO separate pentru fiecare document de tradus. De exemplu, dacă aveți 3 documente și 5 limbi, aceasta va avea ca rezultat 3 fișiere POT și 15 fișiere PO. Aceste fișiere sunt denumite după cum se specifică în șablonul "po4a_paths", cu $master înlocuit cu numele de bază al fiecărui document de tradus. În caz de conflict de nume, puteți specifica fișierul POT de utilizat după cum urmează, cu parametrul "pot=".

Această caracteristică poate fi utilizată și pentru a grupa mai multe fișiere traduse în același fișier POT. Următorul exemplu produce doar 2 fișiere POT: l10n/po/foo.pot (conținând materialul din foo/gui.xml) și l10n/po/bar.pot (conținând materialul din bar/gui.xml și 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

În modul divizare, po4a construiește un compendiu temporar în timpul actualizării PO, pentru a partaja traducerile între toate fișierele PO. În cazul în care două fișiere PO au traduceri diferite pentru același șir de caractere, po4a va marca acest șir ca fiind fuzzy și va prezenta ambele traduceri în toate fișierele PO care conțin acest șir de caractere. În cazul în care traductorul a eliminat fuzzy-ul, traducerea este utilizată automat în toate fișierele PO.

Specificarea documentelor de tradus¶

De asemenea, trebuie să listați documentele care trebuie traduse. Pentru fiecare fișier principal, trebuie să specificați analizatorul de format care urmează să fie utilizat, locația documentului tradus care urmează să fie produs și, opțional, o anumită configurare. Numele fișierelor trebuie să fie puse între ghilimele sau eludate dacă conțin spații. Iată un exemplu:

 [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

Dar, din nou, aceste linii complexe sunt dificil de citit și de modificat, de exemplu atunci când se adaugă un nou limbaj. Este mult mai simplu să reorganizați lucrurile folosind șablonul $lang după cum urmează:

 [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

Specificarea opțiunilor¶

Există două tipuri de opțiuni: opțiuni po4a sunt valorile implicite ale opțiunilor din linia de comandă po4a, în timp ce opțiuni format sunt utilizate pentru a modifica comportamentul analizatorilor de format. Ca opțiuni po4a, ați putea, de exemplu, să specificați în fișierul dvs. de configurare că valoarea implicită a parametrului de linie de comandă --keep este 50% în loc de 80%. Opțiunile de format sunt documentate pe pagina specifică a fiecărui modul de analizare, de exemplu Locale::Po4a::Xml(3pm). Ați putea, de exemplu, să treceți nostrip analizorului XML pentru a nu elimina spațiile din jurul șirurilor extrase.

Puteți trece aceste opțiuni pentru un anumit fișier principal sau chiar pentru o anumită traducere a fișierului respectiv, utilizând "opt:" și "opt_XX:" pentru limba "XX". În exemplul următor, opțiunea nostrip este transmisă analizatorului XML (pentru toate limbile), în timp ce pragul va fi redus la 0% pentru traducerea în franceză (care este astfel păstrată întotdeauna).

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

În orice caz, aceste bucăți de configurare trebuie să fie situate la sfârșitul liniei. Declarația fișierelor trebuie să fie prima, apoi addendumul, dacă există (a se vedea mai jos), și apoi doar opțiunile. Gruparea bucăților de configurare nu este foarte importantă, deoarece elementele sunt concatenate intern ca șiruri de caractere. Exemplele următoare sunt toate echivalente:

  [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

Rețineți că opțiunile specifice fiecărei limbi nu sunt utilizate la crearea fișierului POT. De exemplu, este imposibil să transmiteți nostrip analizatorului doar atunci când creați traducerea în franceză, deoarece același fișier POT este utilizat pentru actualizarea fiecărei limbi. Prin urmare, singurele opțiuni care pot fi specifice unei limbi sunt cele care sunt utilizate la realizarea traducerii, cum ar fi opțiunea "--keep".

Alias de configurare

Pentru a transmite aceleași opțiuni mai multor fișiere, cel mai bine este să definiți un alias de tip după cum urmează. În exemplul următor, "--keep 0" este transmis la fiecare traducere italiană folosind acest tip "test", adică o extensie a tipului "man".

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

De asemenea, puteți extinde un tip existent reutilizând același nume pentru alias, după cum urmează. Aceasta nu este interpretată ca o definiție recursivă eronată.

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

Opțiuni implicite globale

De asemenea, puteți utiliza liniile "[options]" pentru a defini opțiuni care trebuie utilizate pentru toate fișierele, indiferent de tipul acestora.

  [options] --keep 20 --option nostrip

Ca și în cazul opțiunilor din linia de comandă, puteți abrevia parametrii trecuți în fișierul de configurare:

  [options] -k 20 -o nostrip

Prioritatea opțiunilor

Opțiunile fiecărei surse sunt concatenate, asigurându-se că valorile implicite pot fi ușor anulate prin opțiuni mai specifice. Ordinea este următoarea:

• Liniile "[options]" furnizează valori implicite care pot fi anulate de orice altă sursă.
• Se utilizează apoi alias de tip. Opțiuniile specifice limbii prevalează asupra celor aplicabile tuturor limbilor.
• Opțiunile specifice unui anumit fișier principal prevalează atât asupra celor implicite, cât și asupra celor care provin din pseudonimul de tip. De asemenea, în acest caz, opțiunile specifice limbii prevalează asupra celor globale.
• În cele din urmă, parametrii furnizați în linia de comandă po4a prevalează asupra oricăror opțiuni din fișierul de configurare.

Exemplu

Iată un exemplu care arată cum să citați spațiile și ghilimelele:

 [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

Addendum: Adăugarea de conținut suplimentar în traducere¶

Dacă doriți să adăugați o secțiune suplimentară la traducere, de exemplu pentru a acorda mulțumiri traducătorului, atunci trebuie să definiți un addendum la linia care definește fișierul principal. Vă rugăm să consultați pagina po4a(7) pentru mai multe detalii privind sintaxa fișierelor addendum.

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

De asemenea, puteți utiliza șabloane de limbă după cum urmează:

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

Dacă un addendum eșuează la aplicare, traducerea este respinsă.

Modificatori pentru declarația de addendum

Modificatorii de addendum pot simplifica fișierul de configurare în cazul în care nu toate limbile furnizează un addendum sau atunci când lista de addendumuri se modifică de la o limbă la alta. Modificatorul este un singur caracter situat înaintea numelui fișierului.

?

Include ruta_la_addendum dacă acest fișier există, altfel nu face nimic.

@

ruta_la_addendum nu este un addendum obișnuit, ci un fișier care conține o listă de addenda, rând pe rând. Fiecare addendum poate fi precedat de modificatori.

!

ruta_la_addendum (fișierul către care arată) este înlăturat, nu este încărcat și nu va fi încărcat de nicio altă specificație de addendum.

Următoarele includ un addendum în orice limbă, dar numai dacă acesta există. Nu este raportată nicio eroare dacă addendumul nu există.

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

Următoarele includ o listă de addendumuri pentru fiecare limbă:

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

Filtrarea șirurilor traduse¶

Uneori, doriți să ascundeți anumite șiruri de caractere de procesul de traducere. În acest scop, puteți oferi un parametru "pot_in" fișierului principal pentru a specifica numele fișierului care urmează să fie utilizat în locul fișierului principal real la construirea fișierului POT. Iată un exemplu:

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

Cu această configurare, șirurile de caractere de tradus vor fi extrase din book-filtered.xml (care trebuie produs înainte de a apela po4a), în timp ce fișierele traduse vor fi construite din book.xml. Ca urmare, orice șir care face parte din book.xml, dar nu din book-filtered.xml nu va fi inclus în fișierele PO, împiedicând traducătorii să furnizeze o traducere pentru acestea. Astfel, aceste șiruri de caractere vor rămâne nemodificate la producerea documentelor traduse. Acest lucru scade în mod natural nivelul de traducere, astfel încât este posibil să aveți nevoie de opțiunea "--keep" pentru a vă asigura că documentul este produs oricum.