PO4A.7(1) User Contributed Perl Documentation PO4A.7(1) NUME po4a - cadru pentru traducerea documentaiei i a altor materiale Introducere po4a (PO pentru orice) faciliteaza intreinerea traducerii documentaiei utilizand instrumentele clasice gettext. Principala caracteristica a po4a este ca decupleaza traducerea coninutului de structura documentului sau. Acest document servete drept introducere la proiectul po4a, cu accent pe utilizatorii poteniali care se gandesc daca sa utilizeze acest instrument i pe cei curioi care doresc sa ineleaga de ce lucrurile sunt aa cum sunt. De ce po4a? Filozofia software-ului liber este de a face tehnologia cu adevarat disponibila pentru toata lumea. Dar licenierea nu este singurul aspect de luat in considerare: software-ul liber netradus este inutil pentru cei care nu vorbesc limba engleza. Prin urmare, mai avem inca ceva de lucru pentru a face software-ul disponibil pentru toata lumea. Aceasta situaie este bine ineleasa de majoritatea proiectelor i toata lumea este acum convinsa de necesitatea de a traduce totul. Cu toate acestea, traducerile efective reprezinta un efort uria al multor persoane, paralizat de mici dificultai 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 intr-un format standardizat (denumit fiiere PO sau cataloage de traducere). Un intreg ecosistem de instrumente a aparut pentru a ajuta traducatorii sa traduca efectiv aceste fiiere PO. Rezultatul este apoi utilizat de gettext in timpul execuiei pentru a afia mesaje traduse utilizatorilor finali. Cu toate acestea, in ceea ce privete documentaia, situaia este inca oarecum dezamagitoare. La inceput, traducerea documentaiei poate parea mai uoara decat traducerea unui program, deoarece s-ar parea ca trebuie doar sa copiai fiierul sursa al documentaiei i sa incepei sa traducei coninutul. Cu toate acestea, atunci cand documentaia originala este modificata, urmarirea modificarilor se transforma rapid intr-un comar pentru traducatori. Daca este efectuata manual, aceasta sarcina este neplacuta i predispusa la erori. Traducerile invechite sunt adesea mai rele decat lipsa oricarei traduceri. Utilizatorii finali pot fi inelai de documentaia care descrie un comportament vechi al programului. In plus, acetia nu pot interaciona direct cu cei care se ocupa de intreinere, deoarece nu vorbesc engleza. In plus, responsabilul cu intreinerea nu poate rezolva problema, deoarece nu cunoate toate limbile in care este tradusa documentaia sa. Aceste dificultai, cauzate adesea de un instrumentar slab, pot submina motivaia traducatorilor voluntari, agravand i mai mult problema. Obiectivul proiectului po4a este de a uura munca traducatorilor de documentaie. In special, acesta face traducerile de documentaie uor de intreinut. Ideea este de a reutiliza i adapta abordarea gettext la acest domeniu. Ca i in cazul gettext, textele sunt extrase din locaiile lor originale i prezentate traducatorilor sub forma de cataloage de traduceri PO. Traducatorii pot utiliza instrumentele clasice gettext pentru a monitoriza munca de facut, a colabora i a se organiza ca echipe. po4a injecteaza apoi traducerile direct in structura documentaiei pentru a produce fiiere sursa traduse care pot fi prelucrate i distribuite la fel ca fiierele in limba engleza. Orice paragraf care nu este tradus este lasat in limba engleza in documentul rezultat, asigurandu-se ca utilizatorii finali nu vad niciodata o traducere invechita in documentaie. Acest lucru automatizeaza cea mai mare parte a muncii de intreinere a traducerii. Descoperirea paragrafelor care necesita o actualizare devine foarte uoara, iar procesul este complet automatizat atunci cand elementele sunt reordonate fara alte modificari. Verificarea specifica poate fi, de asemenea, utilizata pentru a reduce ansele de erori de formatare care ar conduce la un document defectuos. Pentru o lista mai completa a avantajelor i dezavantajelor acestei abordari, consultai i seciunea Intrebari i raspunsuri frecvente de mai jos din acest document. Formatele acceptate In prezent, aceasta abordare a fost implementata cu succes pentru mai multe tipuri de formate de formatare a textului: man (analizator matur) Vechiul format de pagini de manual, folosit de atat de multe programe. Sprijinul po4a este foarte binevenit aici, deoarece acest format este oarecum dificil de utilizat i nu este foarte prietenos pentru incepatori. Modulul Locale::Po4a::Man(3pm) accepta, de asemenea, formatul mdoc, utilizat de paginile man BSD (acestea sunt destul de comune i in Linux). AsciiDoc (analizator matur) Acest format este un format de marcare simplificat menit sa faciliteze crearea documentaiei. De exemplu, este utilizat pentru documentarea sistemului git. Aceste pagini de manual sunt traduse folosind po4a. Consultai Locale::Po4a::AsciiDoc pentru detalii. pod (analizator matur) Acesta este formatul documentaiei in linie Perl. Limbajul i extensiile in sine sunt documentate folosind acest format, in plus faa de majoritatea scripturilor Perl existente. Acesta faciliteaza pastrarea documentaiei aproape de codul real prin incorporarea ambelor in acelai fiier. Face viaa programatorului mai uoara, dar, din pacate, nu i pe cea a traducatorului, pana cand nu utilizai po4a. Consultai Locale::Po4a::Pod pentru detalii. sgml (analizator matur) Chiar daca a fost inlocuit de XML in prezent, acest format este inca utilizat pentru documentele care au mai mult de cateva ecrane. Acesta poate fi utilizat chiar i pentru cari complete. Actualizarea documentelor de aceasta lungime poate fi foarte dificila. diff se dovedete adesea inutil atunci cand textul original a fost reindentat dupa actualizare. Din fericire, po4a va poate ajuta dupa acest proces. In prezent, numai DTD DebianDoc i DTD DocBook sunt acceptate, dar adaugarea suportului pentru unul nou este foarte uoara. Este chiar posibil sa utilizai po4a pe un DTD SGML necunoscut fara a modifica codul, furnizand informaiile necesare pe linia de comanda. Consultai Locale::Po4a::Sgml(3pm) pentru detalii. TeX / LaTeX (analizator matur) Formatul LaTeX este un format important de documentaie utilizat in lumea software-ului liber i pentru publicaii. Modulul Locale::Po4a::LaTeX(3pm) a fost testat cu documentaia Python, o carte i cateva prezentari. text (analizator matur) Formatul Text este formatul de baza pentru multe formate care includ blocuri lungi de text, inclusiv Markdown, fortunes, seciunea de introducere YAML, debian/changelog i debian/control. Acesta accepta formatul comun utilizat in generatoarele de situri statice, README-uri i alte sisteme de documentare. Consultai Locale::Po4a::Text(3pm) pentru detalii. xml i XHMTL (probabil un analizator matur) Formatul XML este un format de baza pentru multe formate de documentaie. In prezent, po4a accepta DTD DocBook (consultai Locale::Po4a::Docbook(3pm) pentru detalii) i XHTML. BibTex (probabil un analizator matur) Formatul BibTex este utilizat impreuna cu LaTex pentru formatarea listelor de referine (bibliografii). Consultai Locale::Po4a::BibTex pentru detalii. Docbook (probabil un analizator matur) Un limbaj de marcare bazat pe XML care utilizeaza etichete semantice pentru a descrie documentele. Consultai Locale::Po4a:Docbook pentru informaii mai detaliate. Guide XML (probabil un analizator matur) Un format de documentaie XML. Acest modul a fost dezvoltat special pentru a ajuta la susinerea i meninerea traducerilor documentaiei Gentoo Linux cel puin pana in martie 2016 (Conform datelor din situl Wayback Machine). De atunci, Gentoo a trecut la formatul DevBook XML. Consultai Locale::Po4a:Guide pentru informaii mai detaliate. Wml (probabil un analizator matur) Limbajul de marcare web, nu confundai WML cu WAP-ul utilizat pe telefoanele mobile. Acest modul se bazeaza pe modulul Xhtml, care la randul sau se bazeaza pe modulul XmL. Consultai Locale::Po4a::Wml pentru informaii mai detaliate. Yaml (probabil un analizator matur) Un superset strict al JSON. YAML este adesea utilizat ca sisteme sau proiecte de configurare. YAML se afla la baza Ansible de la Red Hat. Consultai Locale::Po4a::Yaml pentru informaii mai detaliate. RubyDoc (probabil un analizator matur) Formatul Ruby Document (RD), iniial formatul implicit de documentare pentru Ruby i proiectele Ruby inainte de a fi convertit in RDoc in 2002. Dei se pare ca versiunea japoneza a manualului de referina Ruby inca utilizeaza RD. Consultai Locale::Po4a::RubyDoc pentru informaii mai detaliate. Halibut (probabil un analizator intr-un stadiu experimental) Un sistem de producie a documentaiei, cu elemente similare TeX, debiandoc-sgml, TeXinfo i altele, dezvoltat de Simon Tatham, dezvoltatorul PuTTY. Consultai Locale::Po4a:Halibut pentru informaii mai detaliate. Ini (probabil un analizator intr-un stadiu experimental) Format de fiier de configurare popularizat de MS-DOS. Consultai Locale::Po4a::Ini pentru informaii mai detaliate. texinfo (analizator intr-un stadiu foarte experimental) Toata documentaia GNU este scrisa in acest format (este chiar una dintre cerinele pentru a deveni un proiect GNU oficial). Suportul pentru Locale::Po4a::Texinfo(3pm) in po4a este inca la inceput. Va rugam sa raportai erori i solicitari de caracteristici. gemtext (analizator intr-un stadiu foarte experimental) Formatul nativ de text simplu al protocolului Gemini. Extensia ".gmi" este frecvent utilizata. Suportul pentru acest modul in po4a este inca in faza incipienta. Daca gasii ceva in neregula, va rugam sa depunei un raport de eroare sau o cerere de caracteristica. org (analizator intr-un stadiu foarte experimental) Formatul de document utilizat de modul Org. Suportul pentru acest modul in po4a este inca in faza incipienta. Daca gasii ceva in neregula, va rugam sa depunei un raport de eroare sau o cerere de caracteristica. vimhelp (analizator intr-un stadiu foarte experimental) Formatul utilizat pentru fiierele de ajutor Vim (i documentaia unor module tere). Suportul pentru acest format in po4a este inca in faza incipienta. Daca gasii ceva in neregula, va rugam sa depunei un raport de eroare sau o cerere de caracteristica. simplepod (analizator intr-un stadiu foarte experimental) Similar cu pod menionat anterior, acesta adopta noul Pod::Simple ca analizator. Deoarece este nou creat, sunt de ateptat unele erori. Daca observai vreun comportament ciudat, va rugam sa ne anunai. In cele din urma, acest modul va inlocui pod. Alte formate acceptate Po4a poate gestiona i unele formate mai rare sau specializate, cum ar fi documentaia opiunilor de compilare pentru nucleele Linux 2.4+ (Locale::Po4a::KernelHelp) sau diagramele produse de instrumentul dia (Locale::Po4a::Dia). Adaugarea unui nou format este adesea foarte uoara, iar sarcina principala este de a veni cu un analizator pentru formatul inta. Consultai Locale::Po4a::TransTractor(3pm) pentru mai multe informaii despre acest lucru. Formate neacceptate Din pacate, po4a nu ofera inca suport pentru mai multe formate de documentaie. Multe dintre acestea ar fi uor de acceptat in po4a. Aceasta include formate care nu sunt utilizate doar pentru documentaie, cum ar fi, descrieri de pachete (deb i rpm), intrebari privind scripturile de instalare a pachetelor, jurnale de modificari ale pachetelor i toate formatele de fiiere specializate utilizate de programe, cum ar fi scenariile de jocuri sau fiierele de resurse pentru <>. Folosind po4a Cel mai simplu mod de a utiliza acest instrument in proiectul dumneavoastra este sa scriei un fiier de configurare pentru programul po4a i sa interacionai numai cu acest program. Va rugam sa consultai documentaia acestuia, in po4a(1). Restul acestei seciuni ofera mai multe detalii pentru utilizatorii avansai ai po4a care doresc sa ii aprofundeze cunotinele. Schema detaliata a fluxului de lucru po4a Asigurai-va ca citii po4a(1) inainte de aceasta seciune excesiv de detaliata pentru a obine o imagine de ansamblu simplificata a fluxului de lucru po4a. Revenii aici cand dorii sa obinei imaginea infricoatoare in ansamblu, cu aproape toate detaliile. In urmatoarea schema, principal.doc este un nume de exemplu pentru documentaia care urmeaza sa fie tradusa; XX.doc este acelai document tradus in limba XX, in timp ce doc.XX.po este catalogul de traducere pentru documentul respectiv in limba XX. Autorii documentaiei vor fi preocupai in principal de principal.doc (care poate fi o pagina de manual, un document XML, un fiier AsciiDoc etc.); traducatorii vor fi preocupai in principal de fiierul PO, in timp ce utilizatorii finali vor vedea doar fiierul XX.doc. Tranziiile cu paranteze drepte precum "[po4a actualizari po]" reprezinta executarea unui instrument po4a, in timp ce tranziiile cu acolade precum "{actualizare de principal.doc}" reprezinta o modificare manuala a fiierelor proiectului. principal.doc | V +<-----<----+<-----<-----<--------+------->-------->-------+ : | | : {traducere} | {actualizare de principal.doc} : : | | : XX.doc | V V (opional) | principal.doc ->-------->------>+ : | (nou) | V V | | [po4a-gettextize] doc.XX.po -->+ | | | (vechi) | | | | ^ V V | | | [po4a actualizeaza po] | V | | V traducere.pot ^ V | | | doc.XX.po | | | (trad. aprox. ,,fuzzy") | {traducere} | | | | ^ V V | | {editare manuala} | | | | | V | V V doc.XX.po --->---->+<---<-- doc.XX.po addendum master.doc (iniial) (actualizat) (opional) (actualizat) : | | | : V | | +----->----->----->------> + | | | | | V V V +------>-----+------<------+ | V [po4a actualizeaza traducerile] | V XX.doc (actualizat) Din nou, aceasta schema este excesiv de complicata. Consultai po4a(1) pentru o prezentare simplificata. Partea din stanga descrie modul in 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 sau tradus i incearca sa construiasca fiierul PO corespunzator. O astfel de conversie manuala este destul de greoaie (consultai documentaia po4a-gettextize(1) pentru mai multe detalii), dar este necesara o singura data pentru a va converti traducerile existente. Daca nu avei nicio traducere de convertit, putei sa uitai de acest lucru i sa va concentrai pe partea dreapta a schemei. In partea dreapta sus, este descrisa aciunea autorului original, care actualizeaza documentaia. Partea din dreapta mijloc prezinta actualizarile automate ale fiierelor de traducere: materialul nou este extras i comparat cu traducerea existenta. Traducerea anterioara este utilizata pentru parile care nu s-au schimbat, in timp ce parile parial modificate sunt conectate la traducerea anterioara cu un marcaj ,,fuzzy" (traducere aproximativa) care indica faptul ca traducerea trebuie actualizata. Materialele noi sau puternic modificate sunt lasate netraduse. Apoi, blocul editare manuala descrie aciunea traducatorilor, care modifica fiierele PO pentru a furniza traduceri pentru fiecare ir i paragraf original. Acest lucru se poate face fie utilizand un editor specific, cum ar fi GTranslator, Lokalize de la KDE sau poedit, fie utilizand o platforma de localizare din Internet, cum ar fi weblate sau pootle. Rezultatul traducerii este un set de fiiere PO, unul pentru fiecare limba. Va rugam sa consultai documentaia gettext pentru mai multe detalii. Partea de jos a figurii arata cum po4a creeaza un document sursa tradus din documentul original principal.doc i catalogul de traduceri doc.XX.po care a fost actualizat de traducatori. Structura documentului este reutilizata, in timp ce coninutul original este inlocuit cu omologul sau tradus. Opional, un addendum poate fi utilizat pentru a adauga text suplimentar la traducere. Acesta este adesea utilizat pentru a adauga numele traducatorului la documentul final. A se vedea mai jos pentru detalii. La invocare, po4a actualizeaza automat atat fiierele de traducere, cat i fiierele de documentaie traduse. Inceperea unui nou proiect de traducere Daca incepei de la zero, trebuie doar sa scriei un fiier de configurare pentru po4a i ai terminat. abloanele relevante sunt create pentru fiierele lipsa, permiand colaboratorilor dvs. sa traduca proiectul dvs. in limba lor. Va rugam sa consultai po4a(1) pentru un tutorial de pornire rapida i pentru toate detaliile. Daca avei o traducere existenta, adica un fiier de documentaie care a fost tradus manual, putei integra coninutul sau in fluxul de lucru po4a utilizand po4a-gettextize. Aceasta sarcina este un pic greoaie (aa cum este descris in pagina de manual a instrumentului), dar odata ce proiectul dvs. este convertit in fluxul de lucru po4a, totul va fi actualizat automat. Actualizarea traducerilor i a documentelor Odata configurat, invocarea po4a este suficienta pentru a actualiza atat fiierele PO de traducere, cat i documentele traduse. Putei trece "--no-translations" la po4a pentru a nu actualiza traducerile (actualizand astfel doar fiierele PO) sau "--no-update" pentru a nu actualiza fiierele PO (actualizand 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?" in seciunea de mai jos). CUM se utilizeaza addenda pentru a adauga text suplimentar la traduceri Adaugarea de text nou la traducere este probabil singurul lucru care este mai uor pe termen lung atunci cand traducei manual fiiere :). Acest lucru se intampla atunci cand dorii sa adaugai o seciune suplimentara la documentul tradus, care nu corespunde niciunui coninut din documentul original. Cazul clasic de utilizare este de a acorda credite (mulumiri, recunoaterea muncii depuse, .a.) echipei de traducere i de a indica modul de raportare a problemelor specifice traducerii. Cu po4a, trebuie sa specificai fiiere addendum, care pot fi privite conceptual ca plasturi (patches) aplicai documentului localizat(tradus) dupa procesare. Fiecare addendum trebuie sa fie furnizat ca fiier separat, al carui format este totui foarte diferit de cel al plasturilor clasice. Prima linie este o linie de antet, care definete punctul de inserie al addendumului (cu o sintaxa din pacate criptica - a se vedea mai jos), in timp ce restul fiierului este adaugat textual la poziia stabilita. Linia de antet trebuie sa inceapa cu irul PO4A-HEADER:, urmat de o lista de campuri cheie=valoare separate prin punct i virgula. De exemplu, urmatorul antet declara un addendum care trebuie plasat chiar la sfaritul traducerii. PO4A-HEADER: mode=eof Lucrurile sunt mai complexe atunci cand dorii sa adaugai coninut suplimentar in mijlocul documentului. Urmatorul antet declara un addendum care trebuie plasat dupa seciunea XML care conine irul "Despre acest document" in traducere. PO4A-HEADER: position=Despre acest document; mode=after; endboundary= In practica, atunci cand incearca sa aplice un addendum, po4a cauta prima linie care corespunde argumentului "poziie" (acesta poate fi o expresie regulata ,,expreg"). Nu uitai ca po4a ia in considerare aici documentul tradus. Aceasta documentaie este in limba engleza, dar linia dvs. ar trebui probabil sa sune dupa cum urmeaza daca intenionai ca addendumul dvs. sa se aplice traducerii in franceza a documentului. PO4A-HEADER: position=A propos de ce document; mode=after; endboundary= Odata ce "poziia" este gasita in documentul inta, po4a cauta urmatoarea linie dupa "poziia" care corespunde "endboundary" furnizata. Addendumul este adaugat chiar dupa acea linie (deoarece am furnizat un endboundary, adica o limita care incheie seciunea curenta). Exact acelai efect ar putea fi obinut cu urmatorul antet, care este echivalent: PO4A-HEADER: position=Despre acest document; mode=after; beginboundary=
Aici, po4a cauta prima linie care corespunde "
" dupa linia care corespunde "About this document" din traducere i adauga addendumul inainte de aceasta linie, deoarece am furnizat un beginboundary, adica o limita care marcheaza inceputul seciunii urmatoare. Aadar, aceasta linie de antet necesita plasarea addendumului dupa seciunea care conine "About this document", i sa instruim po4a ca o seciune incepe cu o linie care conine eticheta "
". Acest lucru este echivalent cu exemplul anterior, deoarece ceea ce dorii cu adevarat este sa adaugai acest addendum fie dupa "
", fie inainte de "
". De asemenea, putei stabili inseria mod la valoarea "before", cu o semantica similara: combinarea "mode=before" cu un "endboundary" va plasa addendum-ul chiar after (dupa) limita care corespunde, adica ultima linie de limita poteniala inainte de "position". Combinarea "mode=before" cu un "beginboundary" va plasa addendumul chiar before (inainte) faa de limita corespunzatoare, adica ultima linie de limita poteniala inainte de "position". Mod | Tipul de limita | Limita utilizata | Punctul de inserie in raport cu limita ========|=================|==============================|========================================= 'before'| 'endboundary' | ultima inainte de 'position' | Imediat dupa limita selectata 'before'| 'beginboundary' | ultima inainte de 'position' | Chiar inainte de limita selectata 'after' | 'endboundary' | prima dupa 'position' | Imediat dupa limita selectata 'after' | 'beginboundary' | prima dupa 'position' | Chiar inainte de limita selectata 'eof' | (niciunul) | nedeclarata | Sfaritul fiierului Sfaturi i trucuri despre addenda o Amintii-va ca acestea sunt expresii regulate. De exemplu, daca dorii sa potrivii sfaritul unei seciuni nroff care se termina cu linia ".fi", nu utilizai ".fi" ca endboundary, deoarece se va potrivi cu "the[ fi]le", ceea ce evident nu este ceea ce va ateptai. endboundary corect in acest caz este: "^\.fi$". o Spaiile albe SUNT importante in coninutul poziiei "position" i al limitelor. Astfel, cele doua linii urmatoare sunt diferite. Cea de-a doua va fi gasita numai daca exista suficiente spaii la final in documentul tradus. PO4A-HEADER: position=Despre acest document; mode=after; beginboundary=
PO4A-HEADER: position=Despre acest document ; mode=after; beginboundary=
o Dei se poate considera ca aceasta cautare contextuala opereaza aproximativ pe fiecare linie a documentului tradus, ea opereaza de fapt pe irul intern de date al documentului tradus. Acest ir de date interne poate fi un text care se intinde pe un paragraf coninand mai multe linii sau poate fi doar o eticheta XML. punctul de inserie exact al addendumului trebuie sa fie inainte sau dupa irul intern de date i nu poate fi in interiorul irului intern de date. o Trecei argumentul "-vv" la po4a pentru a inelege cum sunt adaugate addendele la traducere. De asemenea, poate fi util sa rulai po4a in modul de depanare pentru a vedea irul de date interne reale atunci cand addendumul dvs. nu se aplica. Exemple de addenda o Daca dorii sa adaugai ceva dupa urmatoarea seciune nroff: .SH "AUTHORS" Ar trebui sa selectai o abordare in doi pai prin definirea mode=after. Apoi ar trebui sa restrangei cautarea la linia de dupa AUTHORS cu expresia regulata a argumentului position. Apoi, ar trebui sa potrivii inceputul urmatoarei seciuni (i anume, ^\.SH) cu expresia regulata a argumentului beginboundary. Adica: PO4A-HEADER:mode=after;position=AUTHORS;beginboundary=\.SH o Daca dorii sa adaugai ceva imediat dupa o anumita linie (de exemplu, dupa linia ,,Drepturi de autor Baiat Detept"), utilizai un argument position care corespunde acestei linii, definii mode=after i dai un beginboundary care corespunde oricarei linii. PO4A-HEADER:mode=after;position=Drepturi de autor Baiat Detept, 2004;beginboundary=^ o Daca dorii sa adaugai ceva la sfaritul documentului, dai un argument position care sa corespunda oricarei linii din document (dar numai unei linii. Po4a nu va continua daca nu este unic) i dai un argument endboundary care sa nu se potriveasca cu nimic. Nu folosii aici iruri simple precum "EOF", ci preferai-le pe cele care au mai puine anse sa se afle in documentul dumneavoastra. 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_insami Apoi, urmatorul addendum va asigura adaugarea unei seciuni (in franceza) despre traducator la sfaritul dosarului (in franceza, ,,TRADUCTEUR" inseamna ,,TRADUCATOR", iar ,,moi" inseamna ,,eu"). |PO4A-HEADER:mode=after;position=AUTOR;beginboundary=^=head | |=head1 TRADUCATOR | |eu_insami | Pentru a plasa addendumul inainte de AUTOR, utilizai urmatorul antet: PO4A-HEADER:mode=after;position=NOM;beginboundary=^=head1 Acest lucru funcioneaza deoarece urmatoarea linie care se potrivete cu beginboundary "/^=head1/" dupa seciunea ,,NAME" (tradusa prin ,,NOM" in franceza), este cea care declara autorii. Deci, addendumul va fi pus intre cele doua seciuni. Reinei ca, daca ulterior se adauga o alta seciune intre seciunile ,,NAME" i ,,AUTHOR", po4a va plasa in mod eronat addenda inaintea noii seciuni. Pentru a evita acest lucru, putei realiza acelai lucru folosind mode=before: PO4A-HEADER:mode=before;position=^=head1 AUTOR Cum funcioneaza acesta? Acest capitol va ofera o scurta prezentare generala a componentelor interne ale po4a, astfel incat sa va simii mai increzatori i sa ne ajutai sa il meninem i sa il imbunataim. De asemenea, va poate ajuta sa inelegei de ce nu face ceea ce va ateptai i cum sa soluionai problemele ce pot aparea. TransTractors i arhitectura proiectului La baza proiectului po4a, clasa Locale::Po4a::TransTractor(3pm) este stramoul comun al tuturor analizatorilor po4a. Acest nume ciudat provine din faptul ca se ocupa in acelai timp de traducerea documentelor i de extragerea irurilor de caractere. Mai formal, acesta ia un document de tradus plus un fiier PO care conine traducerile de utilizat ca intrare, producand in acelai timp doua rezultate separate: un alt fiier PO (rezultat din extragerea irurilor traductibile din documentul de intrare) i un document tradus (cu aceeai structura ca cel de intrare, dar cu toate irurile traductibile inlocuite cu coninutul PO de intrare). Iata o reprezentare grafica a acestui lucru: Document intrare --\ /---> Document ieire \ TransTractor:: / (tradus) +-->-- parse() --------+ / \ PO intrare --------/ \---> PO ieire (extras) Acest mic os este nucleul intregii arhitecturi ,,scheletului" po4a. Daca furnizai ambele documente de intrare i nu inei cont de PO de ieire, obinei po4a-translate. Daca in schimb desconsiderai documentul de ieire, obinei po4a-updatepo. po4a utilizeaza un prim TransTractor pentru a obine un fiier POT de ieire actualizat (fara a ine cont de documentele de ieire), apeleaza la msgmerge -U pentru a actualiza fiierele PO de traducere de pe disc i construiete un al doilea TransTractor cu aceste fiiere PO actualizate pentru a actualiza documentele de ieire. Pe scurt, po4a ofera o soluie unica pentru a actualiza ceea ce este necesar, utilizand un singur fiier de configurare. po4a-gettextize utilizeaza, de asemenea, doua TransTractors, dar intr-un alt mod: Construiete un TransTractor pentru fiecare limba, iar apoi construiete un nou fiier PO folosind msgids din documentul original ca msgids i msgids din documentul tradus ca msgstrs. Este nevoie de multa atenie pentru a se asigura ca irurile potrivite in acest mod corespund intr-adevar, dupa cum se descrie in po4a-gettextize(1). Analizatori specifici formatului Toi analizatorii de format po4a sunt implementai pe partea de sus a TransTractor. Unii dintre ei sunt foarte simpli, cum ar fi cei Text, Markdown i AsciiDoc. Acetia incarca liniile una cate una folosind TransTractor::shiftline(), acumuleaza coninutul paragrafelor sau orice altceva. Odata ce un ir de caractere este complet analizat, analizatorul utilizeaza TransTractor::translate() pentru (1) a adauga acest ir la fiierul PO de ieire i (2) pentru a obine traducerea din fiierul PO de intrare. Analizatorul apoi introduce rezultatul in fiierul de ieire utilizand TransTractor::pushline(). Ali analizatori sunt mai compleci deoarece se bazeaza pe un analizator extern pentru a analiza documentul de intrare. Analizatorii Xml, HTML, SGML i Pod sunt construii pe baza analizatorilor SAX. Acetia declara reapeluri la evenimente precum ,,Am gasit un titlu nou al carui coninut este urmatorul" pentru a actualiza documentul de ieire i fiierele POT de ieire in funcie de coninutul de intrare utilizand TransTractor::translate() i TransTractor::pushline(). Analizatorul Yaml este similar, dar diferit: acesta serializeaza o structura de date produsa de analizatorul YAML::Tiny. Acesta este motivul pentru care modulul Yaml din po4a nu reuete sa declare liniile de referina: locaia fiecarui ir de caractere din fiierul de intrare nu este pastrata de analizator, astfel incat nu putem furniza decat ,,$filename:1" ca locaie a irului. Analizatorii orientai pe SAX utilizeaza caractere joker i alte trucuri pentru a salva numele fiierului i numerele de linie ale referinelor. O problema specifica provine din codificarea fiierelor i marcatorii BOM. Analizatorii simpli pot uita de aceasta problema, care este tratata de TransTractor::read() (utilizat intern pentru a obine liniile unui document de intrare), dar modulele care se bazeaza pe un analizator extern trebuie sa se asigure ca toate fiierele sunt citite cu un strat de decodificare PerlIO adecvat. Cel mai simplu este sa deschidei chiar dvs. fiierul i sa furnizai un identificator de fiier sau direct irul complet analizatorului dvs. extern. Consultai Pod::read() i Pod::parse() pentru un exemplu. Coninutul citit de TransTractor este ignorat, dar un identificator de fiier nou este transmis analizatorului extern. Partea importanta este modul "<:encoding($charset)" care este transmis funciei perl open(). Obiecte PO Clasa Locale::Po4a::Po(3pm) este responsabila de incarcarea i utilizarea fiierelor PO i POT. Practic, putei citi un fiier, adauga intrari, obine traduceri cu metoda gettext(), scrie PO intr-un fiier. Funciile mai avansate, cum ar fi fuzionarea unui fiier PO cu un fiier POT sau validarea unui fiier, sunt delegate catre msgmerge i, respectiv, msgfmt. Contribuind la po4a Chiar daca nu ai contribuit niciodata in trecut la vreun proiect Open Source, suntei binevenit: suntem dispui sa va ajutam i sa va indrumam aici. po4a este cel mai bine intreinut de utilizatorii sai in zilele noastre. Deoarece nu dispunem de personal, incercam sa facem proiectul primitor prin imbunatairea documentaiei i a testelor automate pentru a va face increzatori in contribuia la proiect. Va rugam sa consultai fiierul CONTRIBUTING.md pentru mai multe detalii. Proiecte cu cod-sursa deschis ,,open-source" care utilizeaza po4a Iata o lista foarte pariala a proiectelor care utilizeaza po4a in producie pentru documentaia lor. Daca dorii sa va adaugai proiectul la lista, trimitei-ne un e-mail (sau o cerere de imbinare ,,merge request"). o adduser (man): instrument de gestionare a utilizatorilor i a grupurilor. o apt (man, docbook): Gestionarul de pachete Debian. o aptitude (docbook, svg): gestionar de pachete bazat pe terminal pentru Debian o F-Droid website (markdown): catalog instalabil de aplicaii de software liber i cod-sursa deschis (,,Free and Open Source Software": FOSS) pentru platforma Android. o git (asciidoc): sistem distribuit de control al versiunilor pentru urmarirea modificarilor in codul sursa. o Linux manpages (pagini de manual) Acest proiect ofera o infrastructura pentru traducerea multor pagini de manual in diferite limbi, gata de integrare in cateva distribuii majore (Arch Linux, Debian, Fedora, Mageia, openSUSE i derivatele acestora). o Stellarium (HTML): un planetariu cu cod-sursa deschis, gratuit pentru calculatorul dumneavoastra. po4a este utilizat pentru a traduce descrierile obiectelor cereti. o Jamulus (markdown, yaml, HTML): o aplicaie FOSS pentru bruiaj in linie in timp real. Documentaia sitului web este meninuta in mai multe limbi utilizand po4a. o Alt element de rezolvat: Intrebari i raspunsuri frecvente Cum se pronuna po4a? Eu personal o vocalizez ca pouah , care este o onomatopee franceza pe care o folosim in loc de expresie de dezgust :) Poate ca am un sim al umorului ciudat :) De ce sunt depreciate scripturile individuale? Intr-adevar, po4a-updatepo i po4a-translate sunt depreciate in favoarea lui po4a. Motivul este ca, dei po4a poate fi utilizat ca inlocuitor al acestor scripturi, exista destul de multe duplicaii de cod aici. Scripturile individuale au in jur de 150 de linii de cod, in timp ce programul po4a are 1200 de linii, astfel incat acestea fac multe lucruri in plus faa de elementele interne comune. Duplicarea codului duce la apariia unor erori in ambele versiuni i la necesitatea a doua remedieri. Un exemplu de astfel de duplicare sunt bug-urile #1022216 din Debian i problema #442 din GitHub care au avut exact acelai remediu, dar unul in po4a i celalalt po4a-updatepo. Pe termen lung, a dori sa renun la scripturile individuale i sa menin o singura versiune a acestui cod. Lucrul sigur este ca scripturile individuale nu vor mai fi imbunataite, astfel incat doar po4a va beneficia de noile caracteristici. Acestea fiind spuse, nu exista nicio urgena de depreciere. Intenionez sa pastrez scripturile individuale cat de mult posibil i cel puin pana in 2030. Daca proiectul dvs. utilizeaza inca po4a-updatepo i po4a-translate in 2030, s-ar putea sa avei o problema. De asemenea, am putea elimina deprecierea acestor scripturi la un moment dat, daca o refactorizare reduce duplicarea codului la zero. Daca avei o idee (sau mai bine: un plasture ,,patch" :)), ajutorul dvs. este binevenit. Ce se intampla cu celelalte instrumente de traducere pentru documentaie care utilizeaza gettext? Exista cateva dintre ele. Iata o lista posibil incompleta, 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 documentaie in fiiere PO i le-a injectat inapoi dupa traducere. Poate gestiona doar XML i doar un anumit DTD. Sunt destul de nemulumit de gestionarea listelor, care se termina cu un msgid mare. Cand lista devine mare, fragmentul devine mai greu de inghiit. po-debiandoc Acest program realizat de Denis Barbier este un fel de precursor al modulului SGML po4a, care il depreciaza mai mult sau mai puin. Dupa cum spune i numele, acesta gestioneaza doar DTD-ul DebianDoc, care este mai mult sau mai puin un DTD depreciat. xml2po.py Folosit de echipa de documentare GIMP din 2004, funcioneaza destul de bine, chiar daca, dupa cum sugereaza i numele, funcioneaza doar cu fiiere XML i are nevoie de fiiere makefile configurate special. Sphinx Proiectul de documentare Sphinx utilizeaza, de asemenea, gettext in mod extensiv pentru a-i gestiona traducerile. Din pacate, acesta funcioneaza doar pentru cateva formate de text, rest i markdown, dei este probabil singurul instrument care gestioneaza intregul proces de traducere. Principalele avantaje ale po4a faa de acestea sunt uurina de a adauga coninut suplimentar (care este chiar mai rau acolo) i capacitatea de a realiza gettextizarea. REZUMAT al avantajelor abordarii bazate pe gettext o Traducerile nu sunt stocate impreuna cu originalul, ceea ce face posibila detectarea daca traducerile devin neactualizate. o Traducerile sunt stocate in fiiere separate unele de altele, ceea ce previne interferena intre traducatorii din limbi diferite, atat atunci cand ii trimit modificarile, cat i la nivelul codificarii fiierelor. o Acesta se bazeaza intern pe gettext (dar po4a ofera o interfaa foarte simpla, astfel incat nu trebuie sa inelegei elementele interne pentru a-l utiliza). In acest fel, nu trebuie sa reinventam roata i, datorita utilizarii lor pe scara larga, putem crede ca aceste instrumente sunt mai mult sau mai puin lipsite de erori. o Nu s-a schimbat nimic pentru utilizatorul final (in afara de faptul ca traducerile vor fi, speram, mai bine intreinute). Fiierul de documentaie rezultat distribuit este exact acelai. o Nu este nevoie ca traducatorii sa invee o noua sintaxa de fiier, iar editorul lor preferat de fiiere PO (cum ar fi modul PO din Emacs, Lokalize sau Gtranslator) va funciona foarte bine. o gettext ofera o modalitate simpla de a obine statistici despre ceea ce este facut, ceea ce ar trebui revizuit i actualizat i ceea ce mai este de facut. Unele exemple pot fi gasite la aceste adrese: - https://docs.kde.org/stable5/en/kdesdk/lokalize/project-view.html - http://www.debian.org/intl/l10n/ Dar nu totul este ,,in roz", iar aceasta abordare are i unele dezavantaje cu care trebuie sa ne confruntam. o Addenda este oarecum ciudata la prima vedere. o Nu putei adapta textul tradus la preferinele dvs., cum ar fi divizarea unui paragraf aici i unirea altor doua acolo. Dar, intr-un anumit sens, daca exista o problema cu originalul, aceasta ar trebui oricum raportata ca eroare. o Chiar i cu o interfaa uoara, acesta ramane un instrument nou pe care oamenii trebuie sa il invee. Unul dintre visele mele ar fi sa integrez cumva po4a la Gtranslator sau Lokalize. Cand se deschide un fiier de documentaie, irurile de caractere sunt extrase automat, iar un fiier tradus + fiier po poate fi scris pe disc. Daca reuim sa facem un modul MS Word (TM) (sau cel puin RTF), traducatorii profesioniti ar putea chiar sa-l foloseasca. CONSULTAI I o Documentaia instrumentului ,,totul in unul" pe care ar trebui sa o utilizai: po4a(1) ;). o Documentaia scripturilor individuale po4a: po4a-gettextize(1), po4a-updatepo(1), po4a-translate(1), po4a-normalize(1). o Scripturile de ajutor suplimentare: msguntypot(1), po4a-display-man(1), po4a-display-pod(1). o Analizatorii fiecarui format, in special pentru a vedea opiunile 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). o Implementarea infrastructurii de baza: Locale::Po4a::TransTractor(3pm) (deosebit de important pentru a inelege organizarea codului), Locale::Po4a::Chooser(3pm), Locale::Po4a::Po(3pm), Locale::Po4a::Common(3pm). Va rugam sa verificai i fiierul CONTRIBUTING.md din arborele codului sursa. AUTORI Denis Barbier Martin Quinson (mquinson#debian.org) perl v5.42.0 2025-11-22 PO4A.7(1)