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».

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

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.

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ă.