PO4A.7(1)

NUME
po4a - cadru pentru traducerea documentației și a altor materiale

Introducere
po4a (PO pentru orice) facilitează întreținerea traducerii documentației utilizând instrumentele clasice gettext. Principala caracteristică a po4a este că decuplează traducerea conținutului de structura documentului său.

Acest document servește drept introducere la proiectul po4a, cu accent pe utilizatorii potențiali care se gândesc dacă să utilizeze acest instrument și pe cei curioși care doresc să înțeleagă de ce lucrurile sunt așa cum sunt.

De ce po4a?
Filozofia software-ului liber este de a face tehnologia cu adevărat disponibilă pentru toată lumea. Dar licențierea nu este singurul aspect de luat în considerare: software-ul liber netradus este inutil pentru cei care nu vorbesc limba engleză. Prin urmare, mai avem încă ceva de lucru pentru a face software-ul disponibil pentru toată lumea.

Această situație este bine înțeleasă de majoritatea proiectelor și toată lumea este acum convinsă de necesitatea de a traduce totul. Cu toate acestea, traducerile efective reprezintă un efort uriaș al multor persoane, paralizat de mici dificultăți tehnice.

Din fericire, software-ul Open Source este de fapt foarte bine tradus cu ajutorul suitei de instrumente gettext. Aceste instrumente sunt utilizate pentru a extrage șirurile de caractere de tradus dintr-un program și pentru a le prezenta într-un format standardizat (denumit fișiere PO sau cataloage de traducere). Un întreg ecosistem de instrumente a apărut pentru a ajuta traducătorii să traducă efectiv aceste fișiere PO. Rezultatul este apoi utilizat de gettext în timpul execuției pentru a afișa mesaje traduse utilizatorilor finali.

Cu toate acestea, în ceea ce privește documentația, situația este încă oarecum dezamăgitoare. La început, traducerea documentației poate părea mai ușoară decât traducerea unui program, deoarece s-ar părea că trebuie doar să copiați fișierul sursă al documentației și să începeți să traduceți conținutul. Cu toate acestea, atunci când documentația originală este modificată, urmărirea modificărilor se transformă rapid într-un coșmar pentru traducători. Dacă este efectuată manual, această sarcină este neplăcută și predispusă la erori.

Traducerile învechite sunt adesea mai rele decât lipsa oricărei traduceri. Utilizatorii finali pot fi înșelați de documentația care descrie un comportament vechi al programului. În plus, aceștia nu pot interacționa direct cu cei care se ocupă de întreținere, deoarece nu vorbesc engleza. În plus, responsabilul cu întreținerea nu poate rezolva problema, deoarece nu cunoaște toate limbile în care este tradusă documentația sa. Aceste dificultăți, cauzate adesea de un instrumentar slab, pot submina motivația traducătorilor voluntari, agravând și mai mult problema.

Obiectivul proiectului po4a este de a ușura munca traducătorilor de documentație. În special, acesta face traducerile de documentație ușor de întreținut.

Ideea este de a reutiliza și adapta abordarea gettext la acest domeniu. Ca și în cazul gettext, textele sunt extrase din locațiile lor originale și prezentate traducătorilor sub formă de cataloage de traduceri PO. Traducătorii pot utiliza instrumentele clasice gettext pentru a monitoriza munca de făcut, a colabora și a se organiza ca echipe. po4a injectează apoi traducerile direct în structura documentației pentru a produce fișiere sursă traduse care pot fi prelucrate și distribuite la fel ca fișierele în limba engleză. Orice paragraf care nu este tradus este lăsat în limba engleză în documentul rezultat, asigurându-se că utilizatorii finali nu văd niciodată o traducere învechită în documentație.

Acest lucru automatizează cea mai mare parte a muncii de întreținere a traducerii. Descoperirea paragrafelor care necesită o actualizare devine foarte ușoară, iar procesul este complet automatizat atunci când elementele sunt reordonate fără alte modificări. Verificarea specifică poate fi, de asemenea, utilizată pentru a reduce șansele de erori de formatare care ar conduce la un document defectuos.

Pentru o listă mai completă a avantajelor și dezavantajelor acestei abordări, consultați și secțiunea Întrebări și răspunsuri frecvente de mai jos din acest document.

  Formatele acceptate
În prezent, această abordare a fost implementată cu succes pentru mai multe tipuri de formate de formatare a textului:

man (analizator matur)
    Vechiul format de pagini de manual, folosit de atât de multe programe. Sprijinul po4a este foarte binevenit aici, deoarece acest format este oarecum dificil de utilizat și nu este foarte prietenos pentru începători.

    Modulul Locale::Po4a::Man(3pm) acceptă, de asemenea, formatul mdoc, utilizat de paginile man BSD (acestea sunt destul de comune și în Linux).

AsciiDoc (analizator matur)
    Acest format este un format de marcare simplificat menit să faciliteze crearea documentației. De exemplu, este utilizat pentru documentarea sistemului git. Aceste pagini de manual sunt traduse folosind po4a.

    Consultați Locale::Po4a::AsciiDoc pentru detalii.

pod (analizator matur)
    Acesta este formatul documentației în linie Perl. Limbajul și extensiile în sine sunt documentate folosind acest format, în plus față de majoritatea scripturilor Perl existente. Acesta facilitează păstrarea documentației aproape de codul real prin încorporarea ambelor în același fișier. Face viața programatorului mai ușoară, dar, din păcate, nu și pe cea a traducătorului, până când nu utilizați po4a.

    Consultați Locale::Po4a::Pod pentru detalii.

sgml (analizator matur)
    Chiar dacă a fost înlocuit de XML în prezent, acest format este încă utilizat pentru documentele care au mai mult de câteva ecrane. Acesta poate fi utilizat chiar și pentru cărți complete. Actualizarea documentelor de această lungime poate fi foarte dificilă. diff se dovedește adesea inutil atunci când textul original a fost reindentat după actualizare. Din fericire, po4a vă poate ajuta după acest proces.

    În prezent, numai DTD DebianDoc și DTD DocBook sunt acceptate, dar adăugarea suportului pentru unul nou este foarte ușoară. Este chiar posibil să utilizați po4a pe un DTD SGML necunoscut fără a modifica codul, furnizând informațiile necesare pe linia de comandă. Consultați Locale::Po4a::Sgml(3pm) pentru detalii.

TeX / LaTeX (analizator matur)
    Formatul LaTeX este un format important de documentație utilizat în lumea software-ului liber și pentru publicații.

    Modulul Locale::Po4a::LaTeX(3pm) a fost testat cu documentația Python, o carte și câteva prezentări.

text (analizator matur)
    Formatul Text este formatul de bază pentru multe formate care includ blocuri lungi de text, inclusiv Markdown, fortunes, secțiunea de introducere YAML, debian/changelog și debian/control.

    Acesta acceptă formatul comun utilizat în generatoarele de situri statice, README-uri și alte sisteme de documentare. Consultați Locale::Po4a::Text(3pm) pentru detalii.

xml și XHMTL (probabil un analizator matur)
    Formatul XML este un format de bază pentru multe formate de documentație.

    În prezent, po4a acceptă DTD DocBook (consultați Locale::Po4a::Docbook(3pm) pentru detalii) și XHTML.

BibTex (probabil un analizator matur)
    Formatul BibTex este utilizat împreună cu LaTex pentru formatarea listelor de referințe (bibliografii).

    Consultați Locale::Po4a::BibTex pentru detalii.

Docbook (probabil un analizator matur)
    Un limbaj de marcare bazat pe XML care utilizează etichete semantice pentru a descrie documentele.

    Consultați Locale::Po4a:Docbook pentru informații mai detaliate.

Guide XML (probabil un analizator matur)
    Un format de documentație XML. Acest modul a fost dezvoltat special pentru a ajuta la susținerea și menținerea traducerilor documentației Gentoo Linux cel puțin până în martie 2016 (Conform datelor din situl Wayback Machine). De atunci, Gentoo a trecut la formatul DevBook XML.

    Consultați Locale::Po4a:Guide pentru informații mai detaliate.

Wml (probabil un analizator matur)
    Limbajul de marcare web, nu confundați WML cu WAP-ul utilizat pe telefoanele mobile. Acest modul se bazează pe modulul Xhtml, care la rândul său se bazează pe modulul XmL.

    Consultați Locale::Po4a::Wml pentru informații mai detaliate.

Yaml (probabil un analizator matur)
    Un superset strict al JSON. YAML este adesea utilizat ca sisteme sau proiecte de configurare. YAML se află la baza Ansible de la Red Hat.

    Consultați Locale::Po4a::Yaml pentru informații mai detaliate.

RubyDoc (probabil un analizator matur)
    Formatul Ruby Document (RD), inițial formatul implicit de documentare pentru Ruby și proiectele Ruby înainte de a fi convertit în RDoc în 2002. Deși se pare că versiunea japoneză a manualului de referință Ruby încă utilizează RD.

    Consultați Locale::Po4a::RubyDoc pentru informații mai detaliate.

Halibut (probabil un analizator într-un stadiu experimental)
    Un sistem de producție a documentației, cu elemente similare TeX, debiandoc-sgml, TeXinfo și altele, dezvoltat de Simon Tatham, dezvoltatorul PuTTY.

    Consultați Locale::Po4a:Halibut pentru informații mai detaliate.

Ini (probabil un analizator într-un stadiu experimental)
    Format de fișier de configurare popularizat de MS-DOS.

    Consultați Locale::Po4a::Ini pentru informații mai detaliate.

texinfo (analizator într-un stadiu foarte experimental)
    Toată documentația GNU este scrisă în acest format (este chiar una dintre cerințele pentru a deveni un proiect GNU oficial). Suportul pentru Locale::Po4a::Texinfo(3pm) în po4a este încă la început. Vă rugăm să raportați erori și solicitări de caracteristici.

gemtext (analizator într-un stadiu foarte experimental)
    Formatul nativ de text simplu al protocolului Gemini. Extensia ".gmi" este frecvent utilizată. Suportul pentru acest modul în po4a este încă în fază incipientă. Dacă găsiți ceva în neregulă, vă rugăm să depuneți un raport de eroare sau o cerere de caracteristică.

org (analizator într-un stadiu foarte experimental)
    Formatul de document utilizat de modul Org. Suportul pentru acest modul în po4a este încă în fază incipientă. Dacă găsiți ceva în neregulă, vă rugăm să depuneți un raport de eroare sau o cerere de caracteristică.

vimhelp (analizator într-un stadiu foarte experimental)
    Formatul utilizat pentru fișierele de ajutor Vim (și documentația unor module terțe). Suportul pentru acest format în po4a este încă în fază incipientă. Dacă găsiți ceva în neregulă, vă rugăm să depuneți un raport de eroare sau o cerere de caracteristică.

simplepod (analizator într-un stadiu foarte experimental)
    Similar cu pod menționat anterior, acesta adoptă noul Pod::Simple ca analizator. Deoarece este nou creat, sunt de așteptat unele erori. Dacă observați vreun comportament ciudat, vă rugăm să ne anunțați. În cele din urmă, acest modul va înlocui pod.

Alte formate acceptate
    Po4a poate gestiona și unele formate mai rare sau specializate, cum ar fi documentația opțiunilor de compilare pentru nucleele Linux 2.4+ (Locale::Po4a::KernelHelp) sau diagramele produse de instrumentul dia (Locale::Po4a::Dia). Adăugarea unui nou format este adesea foarte ușoară, iar sarcina principală este de a veni cu un analizator pentru formatul țintă. Consultați Locale::Po4a::TransTractor(3pm) pentru mai multe informații despre acest lucru.

Formate neacceptate
    Din păcate, po4a nu oferă încă suport pentru mai multe formate de documentație. Multe dintre acestea ar fi ușor de acceptat în po4a. Aceasta include formate care nu sunt utilizate doar pentru documentație, cum ar fi, descrieri de pachete (deb și rpm), întrebări privind scripturile de instalare a pachetelor, jurnale de modificări ale pachetelor și toate formatele de fișiere specializate utilizate de programe, cum ar fi scenariile de jocuri sau fișierele de resurse pentru «wine».

Folosind po4a
Cel mai simplu mod de a utiliza acest instrument în proiectul dumneavoastră este să scrieți un fișier de configurare pentru programul po4a și să interacționați numai cu acest program. Vă rugăm să consultați documentația acestuia, în po4a(1). Restul acestei secțiuni oferă mai multe detalii pentru utilizatorii avansați ai po4a care doresc să își aprofundeze cunoștințele.

  Schema detaliată a fluxului de lucru po4a
Asigurați-vă că citiți po4a(1) înainte de această secțiune excesiv de detaliată pentru a obține o imagine de ansamblu simplificată a fluxului de lucru po4a. Reveniți aici când doriți să obțineți imaginea înfricoșătoare în ansamblu, cu aproape toate detaliile.

În următoarea schemă, principal.doc este un nume de exemplu pentru documentația care urmează să fie tradusă; XX.doc este același document tradus în limba XX, în timp ce doc.XX.po este catalogul de traducere pentru documentul respectiv în limba XX. Autorii documentației vor fi preocupați în principal de principal.doc (care poate fi o pagină de manual, un document XML, un fișier AsciiDoc etc.); traducătorii vor fi preocupați în principal de fișierul PO, în timp ce utilizatorii finali vor vedea doar fișierul XX.doc.

Tranzițiile cu paranteze drepte precum "[po4a actualizări po]" reprezintă executarea unui instrument po4a, în timp ce tranzițiile cu acolade precum "{actualizare de principal.doc}" reprezintă o modificare manuală a fișierelor proiectului.

                                   principal.doc
                                       |
                                       V
     +<-----<----+<-----<-----<--------+------->-------->-------+
     :           |                     |                        :
{traducere}      |       {actualizare de principal.doc}         :
     :           |                     |                        :
   XX.doc        |                     V                        V
 (opțional)      |              principal.doc ->-------->------>+
     :           |                   (nou)                      |
     V           V                     |                        |
  [po4a-gettextize]   doc.XX.po -->+   |                        |
          |           (vechi)      |   |                        |
          |              ^         V   V                        |
          |              |  [po4a actualizează po]              |
          V              |           |                          V
    traducere.pot        ^           V                          |
          |              |        doc.XX.po                     |
          |              |  (trad. aprox. „fuzzy”)              |
     {traducere}         |           |                          |
          |              ^           V                          V
          |              |     {editare manuală}                |
          |              |           |                          |
          V              |           V                          V
      doc.XX.po --->---->+<---<-- doc.XX.po    addendum     master.doc
      (inițial)                 (actualizat)  (opțional)   (actualizat)
          :                          |            |             |
          :                          V            |             |
          +----->----->----->------> +            |             |
                                     |            |             |
                                     V            V             V
                                     +------>-----+------<------+
                                                  |
                                                  V
                                   [po4a actualizează traducerile]
                                                  |
                                                  V
                                                XX.doc
                                             (actualizat)

Din nou, această schemă este excesiv de complicată. Consultați po4a(1) pentru o prezentare simplificată.

Partea din stânga descrie modul în care po4a-gettextize(1) poate fi utilizat pentru a converti un proiect de traducere existent la infrastructura po4a. Acest script ia un document original și omologul său tradus și încearcă să construiască fișierul PO corespunzător. O astfel de conversie manuală este destul de greoaie (consultați documentația po4a-gettextize(1) pentru mai multe detalii), dar este necesară o singură dată pentru a vă converti traducerile existente. Dacă nu aveți nicio traducere de convertit, puteți să uitați de acest lucru și să vă concentrați pe partea dreaptă a schemei.

În partea dreaptă sus, este descrisă acțiunea autorului original, care actualizează documentația. Partea din dreapta mijloc prezintă actualizările automate ale fișierelor de traducere: materialul nou este extras și comparat cu traducerea existentă. Traducerea anterioară este utilizată pentru părțile care nu s-au schimbat, în timp ce părțile parțial modificate sunt conectate la traducerea anterioară cu un marcaj „fuzzy” (traducere aproximativă) care indică faptul că traducerea trebuie actualizată. Materialele noi sau puternic modificate sunt lăsate netraduse.

Apoi, blocul editare manuală descrie acțiunea traducătorilor, care modifică fișierele PO pentru a furniza traduceri pentru fiecare șir și paragraf original. Acest lucru se poate face fie utilizând un editor specific, cum ar fi GTranslator, Lokalize de la KDE sau poedit, fie utilizând o platformă de localizare din Internet, cum ar fi weblate sau pootle. Rezultatul traducerii este un set de fișiere PO, unul pentru fiecare limbă. Vă rugăm să consultați documentația gettext pentru mai multe detalii.

Partea de jos a figurii arată cum po4a creează un document sursă tradus din documentul original principal.doc și catalogul de traduceri doc.XX.po care a fost actualizat de traducători. Structura documentului este reutilizată, în timp ce conținutul original este înlocuit cu omologul său tradus. Opțional, un addendum poate fi utilizat pentru a adăuga text suplimentar la traducere. Acesta este adesea utilizat pentru a adăuga numele traducătorului la documentul final. A se vedea mai jos pentru detalii.

La invocare, po4a actualizează automat atât fișierele de traducere, cât și fișierele de documentație traduse.

  Începerea unui nou proiect de traducere
Dacă începeți de la zero, trebuie doar să scrieți un fișier de configurare pentru po4a și ați terminat. Șabloanele relevante sunt create pentru fișierele lipsă, permițând colaboratorilor dvs. să traducă proiectul dvs. în limba lor. Vă rugăm să consultați po4a(1) pentru un tutorial de pornire rapidă și pentru toate detaliile.

Dacă aveți o traducere existentă, adică un fișier de documentație care a fost tradus manual, puteți integra conținutul său în fluxul de lucru po4a utilizând po4a-gettextize. Această sarcină este un pic greoaie (așa cum este descris în pagina de manual a instrumentului), dar odată ce proiectul dvs. este convertit în fluxul de lucru po4a, totul va fi actualizat automat.

  Actualizarea traducerilor și a documentelor
Odată configurat, invocarea po4a este suficientă pentru a actualiza atât fișierele PO de traducere, cât și documentele traduse. Puteți trece "--no-translations" la po4a pentru a nu actualiza traducerile (actualizând astfel doar fișierele PO) sau "--no-update" pentru a nu actualiza fișierele PO (actualizând astfel doar traducerile). Aceasta corespunde aproximativ scripturilor individuale po4a-updatepo și po4a-translate care sunt acum depreciate (a se vedea „De ce sunt depreciate scripturile individuale?” în secțiunea de mai jos).

  CUM se utilizează addenda pentru a adăuga text suplimentar la traduceri
Adăugarea de text nou la traducere este probabil singurul lucru care este mai ușor pe termen lung atunci când traduceți manual fișiere :). Acest lucru se întâmplă atunci când doriți să adăugați o secțiune suplimentară la documentul tradus, care nu corespunde niciunui conținut din documentul original. Cazul clasic de utilizare este de a acorda credite (mulțumiri, recunoașterea muncii depuse, ș.a.) echipei de traducere și de a indica modul de raportare a problemelor specifice traducerii.

Cu po4a, trebuie să specificați fișiere addendum, care pot fi privite conceptual ca plasturi (patches) aplicați documentului localizat(tradus) după procesare. Fiecare addendum trebuie să fie furnizat ca fișier separat, al cărui format este totuși foarte diferit de cel al plasturilor clasice. Prima linie este o linie de antet, care definește punctul de inserție al addendumului (cu o sintaxă din păcate criptică - a se vedea mai jos), în timp ce restul fișierului este adăugat textual la poziția stabilită.

Linia de antet trebuie să înceapă cu șirul PO4A-HEADER:, urmat de o listă de câmpuri cheie=valoare separate prin punct și virgulă.

De exemplu, următorul antet declară un addendum care trebuie plasat chiar la sfârșitul traducerii.

 PO4A-HEADER: mode=eof

Lucrurile sunt mai complexe atunci când doriți să adăugați conținut suplimentar în mijlocul documentului. Următorul antet declară un addendum care trebuie plasat după secțiunea XML care conține șirul "Despre acest document" în traducere.

 PO4A-HEADER: position=Despre acest document; mode=after; endboundary=</section>

În practică, atunci când încearcă să aplice un addendum, po4a caută prima linie care corespunde argumentului "poziție" (acesta poate fi o expresie regulată „expreg”). Nu uitați că po4a ia în considerare aici documentul tradus. Această documentație este în limba engleză, dar linia dvs. ar trebui probabil să sune după cum urmează dacă intenționați ca addendumul dvs. să se aplice traducerii în franceză a documentului.

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

Odată ce "poziția" este găsită în documentul țintă, po4a caută următoarea linie după "poziția" care corespunde "endboundary" furnizată. Addendumul este adăugat chiar după acea linie (deoarece am furnizat un endboundary, adică o limită care încheie secțiunea curentă).

Exact același efect ar putea fi obținut cu următorul antet, care este echivalent:

 PO4A-HEADER: position=Despre acest document; mode=after; beginboundary=<section>

Aici, po4a caută prima linie care corespunde "<section>" după linia care corespunde "About this document" din traducere și adaugă addendumul înainte de această linie, deoarece am furnizat un beginboundary, adică o limită care marchează începutul secțiunii următoare. Așadar, această linie de antet necesită plasarea addendumului după secțiunea care conține "About this document", și să instruim po4a că o secțiune începe cu o linie care conține eticheta "<section>". Acest lucru este echivalent cu exemplul anterior, deoarece ceea ce doriți cu adevărat este să adăugați acest addendum fie după "</section>", fie înainte de "<section>".

De asemenea, puteți stabili inserția mod la valoarea "before", cu o semantică similară: combinarea "mode=before" cu un "endboundary" va plasa addendum-ul chiar after (după) limita care corespunde, adică ultima linie de limită potențială înainte de "position". Combinarea "mode=before" cu un "beginboundary" va plasa addendumul chiar before (înainte) față de limita corespunzătoare, adică ultima linie de limită potențială înainte de "position".

  Mod    | Tipul de limită |       Limita utilizată       | Punctul de inserție în raport cu limita
 ========|=================|==============================|=========================================
 'before'|  'endboundary'  | ultima înainte de 'position' | Imediat după limita selectată
 'before'| 'beginboundary' | ultima înainte de 'position' | Chiar înainte de limita selectată
 'after' |  'endboundary'  |    prima după 'position'     | Imediat după limita selectată
 'after' | 'beginboundary' |    prima după 'position'     | Chiar înainte de limita selectată
 'eof'   |   (niciunul)    |    nedeclarată               | Sfârșitul fișierului

Sfaturi și trucuri despre addenda

•   Amintiți-vă că acestea sunt expresii regulate. De exemplu, dacă doriți să potriviți sfârșitul unei secțiuni nroff care se termină cu linia ".fi", nu utilizați ".fi" ca endboundary, deoarece se va potrivi cu "the[ fi]le", ceea ce evident nu este ceea ce vă așteptați. endboundary corect în acest caz este: "^\.fi$".

•   Spațiile albe SUNT importante în conținutul poziției "position" și al limitelor. Astfel, cele două linii următoare sunt diferite. Cea de-a doua va fi găsită numai dacă există suficiente spații la final în documentul tradus.

     PO4A-HEADER: position=Despre acest document; mode=after; beginboundary=<section>
     PO4A-HEADER: position=Despre acest document ; mode=after; beginboundary=<section>

•   Deși se poate considera că această căutare contextuală operează aproximativ pe fiecare linie a documentului tradus, ea operează de fapt pe șirul intern de date al documentului tradus. Acest șir de date interne poate fi un text care se întinde pe un paragraf conținând mai multe linii sau poate fi doar o etichetă XML. punctul de inserție exact al addendumului trebuie să fie înainte sau după șirul intern de date și nu poate fi în interiorul șirului intern de date.

•   Treceți argumentul "-vv" la po4a pentru a înțelege cum sunt adăugate addendele la traducere. De asemenea, poate fi util să rulați po4a în modul de depanare pentru a vedea șirul de date interne reale atunci când addendumul dvs. nu se aplică.

Exemple de addenda

•   Dacă doriți să adăugați ceva după următoarea secțiune nroff:

      .SH "AUTHORS"

    Ar trebui să selectați o abordare în doi pași prin definirea mode=after. Apoi ar trebui să restrângeți căutarea la linia de după AUTHORS cu expresia regulată a argumentului position. Apoi, ar trebui să potriviți începutul următoarei secțiuni (și anume, ^\.SH) cu expresia regulată a argumentului beginboundary. Adică:

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

•   Dacă doriți să adăugați ceva imediat după o anumită linie (de exemplu, după linia „Drepturi de autor Băiat Deștept”), utilizați un argument position care corespunde acestei linii, definiți mode=after și dați un beginboundary care corespunde oricărei linii.

     PO4A-HEADER:mode=after;position=Drepturi de autor Băiat Deștept, 2004;beginboundary=^

•   Dacă doriți să adăugați ceva la sfârșitul documentului, dați un argument position care să corespundă oricărei linii din document (dar numai unei linii. Po4a nu va continua dacă nu este unic) și dați un argument endboundary care să nu se potrivească cu nimic. Nu folosiți aici șiruri simple precum "EOF", ci preferați-le pe cele care au mai puține șanse să se afle în documentul dumneavoastră.

     PO4A-HEADER:mode=after;position=Despre acest document;beginboundary=FakePo4aBoundary

Un exemplu mai detaliat

Documentul original (formatat POD):

 |=head1 NUME
 |
 |fantoma - un program fictiv
 |
 |=head1 AUTHOR
 |
 |eu_însămi

Apoi, următorul addendum va asigura adăugarea unei secțiuni (în franceză) despre traducător la sfârșitul dosarului (în franceză, „TRADUCTEUR” înseamnă „TRADUCĂTOR”, iar „moi” înseamnă „eu”).

 |PO4A-HEADER:mode=after;position=AUTOR;beginboundary=^=head
 |
 |=head1 TRADUCĂTOR
 |
 |eu_însămi
 |

Pentru a plasa addendumul înainte de AUTOR, utilizați următorul antet:

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

Acest lucru funcționează deoarece următoarea linie care se potrivește cu beginboundary "/^=head1/" după secțiunea „NAME” (tradusă prin „NOM” în franceză), este cea care declară autorii. Deci, addendumul va fi pus între cele două secțiuni. Rețineți că, dacă ulterior se adaugă o altă secțiune între secțiunile „NAME” și „AUTHOR”, po4a va plasa în mod eronat addenda înaintea noii secțiuni.

Pentru a evita acest lucru, puteți realiza același lucru folosind mode=before:

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

Cum funcționează acesta?
Acest capitol vă oferă o scurtă prezentare generală a componentelor interne ale po4a, astfel încât să vă simțiți mai încrezători și să ne ajutați să îl menținem și să îl îmbunătățim. De asemenea, vă poate ajuta să înțelegeți de ce nu face ceea ce vă așteptați și cum să soluționați problemele ce pot apărea.

  TransTractors și arhitectura proiectului
La baza proiectului po4a, clasa Locale::Po4a::TransTractor(3pm) este strămoșul comun al tuturor analizatorilor po4a. Acest nume ciudat provine din faptul că se ocupă în același timp de traducerea documentelor și de extragerea șirurilor de caractere.

Mai formal, acesta ia un document de tradus plus un fișier PO care conține traducerile de utilizat ca intrare, producând în același timp două rezultate separate: un alt fișier PO (rezultat din extragerea șirurilor traductibile din documentul de intrare) și un document tradus (cu aceeași structură ca cel de intrare, dar cu toate șirurile traductibile înlocuite cu conținutul PO de intrare). Iată o reprezentare grafică a acestui lucru:

   Document intrare --\                             /---> Document ieșire
                       \      TransTractor::       /         (tradus)
                        +-->--   parse()  --------+
                       /                           \
   PO intrare --------/                             \---> PO ieșire
                                                          (extras)

Acest mic os este nucleul întregii arhitecturi „scheletului” po4a. Dacă furnizați ambele documente de intrare și nu țineți cont de PO de ieșire, obțineți po4a-translate. Dacă în schimb desconsiderați documentul de ieșire, obțineți po4a-updatepo. po4a utilizează un prim TransTractor pentru a obține un fișier POT de ieșire actualizat (fără a ține cont de documentele de ieșire), apelează la msgmerge -U pentru a actualiza fișierele PO de traducere de pe disc și construiește un al doilea TransTractor cu aceste fișiere PO actualizate pentru a actualiza documentele de ieșire. Pe scurt, po4a oferă o soluție unică pentru a actualiza ceea ce este necesar, utilizând un singur fișier de configurare.

po4a-gettextize utilizează, de asemenea, două TransTractors, dar într-un alt mod: Construiește un TransTractor pentru fiecare limbă, iar apoi construiește un nou fișier PO folosind msgids din documentul original ca msgids și msgids din documentul tradus ca msgstrs. Este nevoie de multă atenție pentru a se asigura că șirurile potrivite în acest mod corespund într-adevăr, după cum se descrie în po4a-gettextize(1).

  Analizatori specifici formatului
Toți analizatorii de format po4a sunt implementați pe partea de sus a TransTractor. Unii dintre ei sunt foarte simpli, cum ar fi cei Text, Markdown și AsciiDoc. Aceștia încarcă liniile una câte una folosind TransTractor::shiftline(), acumulează conținutul paragrafelor sau orice altceva. Odată ce un șir de caractere este complet analizat, analizatorul utilizează TransTractor::translate() pentru (1) a adăuga acest șir la fișierul PO de ieșire și (2) pentru a obține traducerea din fișierul PO de intrare. Analizatorul apoi introduce rezultatul în fișierul de ieșire utilizând TransTractor::pushline().

Alți analizatori sunt mai complecși deoarece se bazează pe un analizator extern pentru a analiza documentul de intrare. Analizatorii Xml, HTML, SGML și Pod sunt construiți pe baza analizatorilor SAX. Aceștia declară reapeluri la evenimente precum „Am găsit un titlu nou al cărui conținut este următorul” pentru a actualiza documentul de ieșire și fișierele POT de ieșire în funcție de conținutul de intrare utilizând TransTractor::translate() și TransTractor::pushline(). Analizatorul Yaml este similar, dar diferit: acesta serializează o structură de date produsă de analizatorul YAML::Tiny. Acesta este motivul pentru care modulul Yaml din po4a nu reușește să declare liniile de referință: locația fiecărui șir de caractere din fișierul de intrare nu este păstrată de analizator, astfel încât nu putem furniza decât „$filename:1” ca locație a șirului. Analizatorii orientați pe SAX utilizează caractere joker și alte trucuri pentru a salva numele fișierului și numerele de linie ale referințelor.

O problemă specifică provine din codificarea fișierelor și marcatorii BOM. Analizatorii simpli pot uita de această problemă, care este tratată de TransTractor::read() (utilizat intern pentru a obține liniile unui document de intrare), dar modulele care se bazează pe un analizator extern trebuie să se asigure că toate fișierele sunt citite cu un strat de decodificare PerlIO adecvat. Cel mai simplu este să deschideți chiar dvs. fișierul și să furnizați un identificator de fișier sau direct șirul complet analizatorului dvs. extern. Consultați Pod::read() și Pod::parse() pentru un exemplu. Conținutul citit de TransTractor este ignorat, dar un identificator de fișier nou este transmis analizatorului extern. Partea importantă este modul "<:encoding($charset)" care este transmis funcției perl open().

  Obiecte PO
Clasa Locale::Po4a::Po(3pm) este responsabilă de încărcarea și utilizarea fișierelor PO și POT. Practic, puteți citi un fișier, adăuga intrări, obține traduceri cu metoda gettext(), scrie PO într-un fișier. Funcțiile mai avansate, cum ar fi fuzionarea unui fișier PO cu un fișier POT sau validarea unui fișier, sunt delegate către msgmerge și, respectiv, msgfmt.

  Contribuind la po4a
Chiar dacă nu ați contribuit niciodată în trecut la vreun proiect Open Source, sunteți binevenit: suntem dispuși să vă ajutăm și să vă îndrumăm aici. po4a este cel mai bine întreținut de utilizatorii săi în zilele noastre. Deoarece nu dispunem de personal, încercăm să facem proiectul primitor prin îmbunătățirea documentației și a testelor automate pentru a vă face încrezători în contribuția la proiect. Vă rugăm să consultați fișierul CONTRIBUTING.md pentru mai multe detalii.

Proiecte cu cod-sursă deschis „open-source” care utilizează po4a
Iată o listă foarte parțială a proiectelor care utilizează po4a în producție pentru documentația lor. Dacă doriți să vă adăugați proiectul la listă, trimiteți-ne un e-mail (sau o cerere de îmbinare „merge request”).

•   adduser (man): instrument de gestionare a utilizatorilor și a grupurilor.

•   apt (man, docbook): Gestionarul de pachete Debian.

•   aptitude (docbook, svg): gestionar de pachete bazat pe terminal pentru Debian

•   F-Droid website <https://gitlab.com/fdroid/fdroid-website> (markdown): catalog instalabil de aplicații de software liber și cod-sursă deschis („Free and Open Source Software”: FOSS) pentru platforma Android.

•   git <https://github.com/jnavila/git-manpages-l10n> (asciidoc): sistem distribuit de control al versiunilor pentru urmărirea modificărilor în codul sursă.

•   Linux manpages <https://salsa.debian.org/manpages-l10n-team/manpages-l10n> (pagini de manual)

    Acest proiect oferă o infrastructură pentru traducerea multor pagini de manual în diferite limbi, gata de integrare în câteva distribuții majore (Arch Linux, Debian, Fedora, Mageia, openSUSE și derivatele acestora).

•   Stellarium <https://github.com/Stellarium/stellarium> (HTML): un planetariu cu cod-sursă deschis, gratuit pentru calculatorul dumneavoastră. po4a este utilizat pentru a traduce descrierile obiectelor cerești.

•   Jamulus <https://jamulus.io/> (markdown, yaml, HTML): o aplicație FOSS pentru bruiaj în linie în timp real. Documentația sitului web este menținută în mai multe limbi utilizând po4a.

•   Alt element de rezolvat: <https://gitlab.com/fdroid/fdroid-website/> <https://github.com/fsfe/reuse-docs/pull/61>

Întrebări și răspunsuri frecvente

  Cum se pronunță po4a?
Eu personal o vocalizez ca pouah <https://en.wiktionary.org/wiki/pouah>, care este o onomatopee franceză pe care o folosim în loc de expresie de dezgust :) Poate că am un simț al umorului ciudat :)

  De ce sunt depreciate scripturile individuale?
Într-adevăr, po4a-updatepo și po4a-translate sunt depreciate în favoarea lui po4a. Motivul este că, deși po4a poate fi utilizat ca înlocuitor al acestor scripturi, există destul de multe duplicații de cod aici. Scripturile individuale au în jur de 150 de linii de cod, în timp ce programul po4a are 1200 de linii, astfel încât acestea fac multe lucruri în plus față de elementele interne comune. Duplicarea codului duce la apariția unor erori în ambele versiuni și la necesitatea a două remedieri. Un exemplu de astfel de duplicare sunt bug-urile #1022216 din Debian și problema #442 din GitHub care au avut exact același remediu, dar unul în po4a și celălalt po4a-updatepo.

Pe termen lung, aș dori să renunț la scripturile individuale și să mențin o singură versiune a acestui cod. Lucrul sigur este că scripturile individuale nu vor mai fi îmbunătățite, astfel încât doar po4a va beneficia de noile caracteristici. Acestea fiind spuse, nu există nicio urgență de depreciere. Intenționez să păstrez scripturile individuale cât de mult posibil și cel puțin până în 2030. Dacă proiectul dvs. utilizează încă po4a-updatepo și po4a-translate în 2030, s-ar putea să aveți o problemă.

De asemenea, am putea elimina deprecierea acestor scripturi la un moment dat, dacă o refactorizare reduce duplicarea codului la zero. Dacă aveți o idee (sau mai bine: un plasture „patch” :)), ajutorul dvs. este binevenit.

  Ce se întâmplă cu celelalte instrumente de traducere pentru documentație care utilizează gettext?
Există câteva dintre ele. Iată o listă posibil incompletă, și multe alte instrumente apar la orizont.

poxml
    Acesta este instrumentul dezvoltat de cei de la KDE pentru a gestiona DocBook XML. AFAIK, a fost primul program care a extras șiruri de caractere pentru a le traduce din documentație în fișiere PO și le-a injectat înapoi după traducere.

    Poate gestiona doar XML și doar un anumit DTD. Sunt destul de nemulțumit de gestionarea listelor, care se termină cu un msgid mare. Când lista devine mare, fragmentul devine mai greu de înghițit.

po-debiandoc
    Acest program realizat de Denis Barbier este un fel de precursor al modulului SGML po4a, care îl depreciază mai mult sau mai puțin. După cum spune și numele, acesta gestionează doar DTD-ul DebianDoc, care este mai mult sau mai puțin un DTD depreciat.

xml2po.py
    Folosit de echipa de documentare GIMP din 2004, funcționează destul de bine, chiar dacă, după cum sugerează și numele, funcționează doar cu fișiere XML și are nevoie de fișiere makefile configurate special.

Sphinx
    Proiectul de documentare Sphinx utilizează, de asemenea, gettext în mod extensiv pentru a-și gestiona traducerile. Din păcate, acesta funcționează doar pentru câteva formate de text, rest și markdown, deși este probabil singurul instrument care gestionează întregul proces de traducere.

Principalele avantaje ale po4a față de acestea sunt ușurința de a adăuga conținut suplimentar (care este chiar mai rău acolo) și capacitatea de a realiza gettextizarea.

  REZUMAT al avantajelor abordării bazate pe gettext

•   Traducerile nu sunt stocate împreună cu originalul, ceea ce face posibilă detectarea dacă traducerile devin neactualizate.

•   Traducerile sunt stocate în fișiere separate unele de altele, ceea ce previne interferența între traducătorii din limbi diferite, atât atunci când își trimit modificările, cât și la nivelul codificării fișierelor.

•   Acesta se bazează intern pe gettext (dar po4a oferă o interfață foarte simplă, astfel încât nu trebuie să înțelegeți elementele interne pentru a-l utiliza). În acest fel, nu trebuie să reinventăm roata și, datorită utilizării lor pe scară largă, putem crede că aceste instrumente sunt mai mult sau mai puțin lipsite de erori.

•   Nu s-a schimbat nimic pentru utilizatorul final (în afară de faptul că traducerile vor fi, sperăm, mai bine întreținute). Fișierul de documentație rezultat distribuit este exact același.

•   Nu este nevoie ca traducătorii să învețe o nouă sintaxă de fișier, iar editorul lor preferat de fișiere PO (cum ar fi modul PO din Emacs, Lokalize sau Gtranslator) va funcționa foarte bine.

•   gettext oferă o modalitate simplă de a obține statistici despre ceea ce este făcut, ceea ce ar trebui revizuit și actualizat și ceea ce mai este de făcut. Unele exemple pot fi găsite la aceste adrese:

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

Dar nu totul este „în roz”, iar această abordare are și unele dezavantaje cu care trebuie să ne confruntăm.

•   Addenda este oarecum ciudată la prima vedere.

•   Nu puteți adapta textul tradus la preferințele dvs., cum ar fi divizarea unui paragraf aici și unirea altor două acolo. Dar, într-un anumit sens, dacă există o problemă cu originalul, aceasta ar trebui oricum raportată ca eroare.

•   Chiar și cu o interfață ușoară, acesta rămâne un instrument nou pe care oamenii trebuie să îl învețe.

    Unul dintre visele mele ar fi să integrez cumva po4a la Gtranslator sau Lokalize. Când se deschide un fișier de documentație, șirurile de caractere sunt extrase automat, iar un fișier tradus + fișier po poate fi scris pe disc. Dacă reușim să facem un modul MS Word (TM) (sau cel puțin RTF), traducătorii profesioniști ar putea chiar să-l folosească.

CONSULTAȚI ȘI

•   Documentația instrumentului „totul în unul” pe care ar trebui să o utilizați: po4a(1) ;).

•   Documentația scripturilor individuale po4a: po4a-gettextize(1), po4a-updatepo(1), po4a-translate(1), po4a-normalize(1).

•   Scripturile de ajutor suplimentare: msguntypot(1), po4a-display-man(1), po4a-display-pod(1).

•   Analizatorii fiecărui format, în special pentru a vedea opțiunile acceptate de fiecare dintre ei: Locale::Po4a::AsciiDoc(3pm) Locale::Po4a::Dia(3pm), Locale::Po4a::Gemtext(3pm), Locale::Po4a::Guide(3pm), Locale::Po4a::Ini(3pm), Locale::Po4a::KernelHelp(3pm), Locale::Po4a::Man(3pm), Locale::Po4a::RubyDoc(3pm), Locale::Po4a::Texinfo(3pm), Locale::Po4a::Text(3pm), Locale::Po4a::Xhtml(3pm), Locale::Po4a::Yaml(3pm), Locale::Po4a::BibTeX(3pm), Locale::Po4a::Docbook(3pm), Locale::Po4a::Halibut(3pm), Locale::Po4a::LaTeX(3pm), Locale::Po4a::Org(3pm), Locale::Po4a::Pod(3pm), Locale::Po4a::SimplePod(3pm), Locale::Po4a::Sgml(3pm), Locale::Po4a::TeX(3pm), Locale::Po4a::VimHelp, Locale::Po4a::Wml(3pm), Locale::Po4a::Xml(3pm).

•   Implementarea infrastructurii de bază: Locale::Po4a::TransTractor(3pm) (deosebit de important pentru a înțelege organizarea codului), Locale::Po4a::Chooser(3pm), Locale::Po4a::Po(3pm), Locale::Po4a::Common(3pm). Vă rugăm să verificați și fișierul CONTRIBUTING.md din arborele codului sursă.

AUTORI
 Denis Barbier <barbier,linuxfr.org>
 Martin Quinson (mquinson#debian.org)