LOCALE::PO4A::XML.3PM(1) User Contributed Perl Documentation NUME Locale::Po4a::Xml - convertete documente XML i derivate din/in fiiere PO DESCRIERE Scopul proiectului po4a (PO pentru orice) este de a uura traducerile (i mai interesant, intreinerea traducerilor) folosind instrumente gettext in domenii in care nu erau ateptate, cum ar fi documentaia. Locale::Po4a::Xml este un modul care ajuta la traducerea documentelor XML in alte limbi [umane]. De asemenea, poate fi folosit ca baza pentru a construi module pentru documente bazate pe XML. TRADUCEREA CU PO4A::XML Acest modul poate fi utilizat direct pentru a gestiona documente XML generice. Acesta va extrage tot coninutul etichetei, fara atribute, deoarece acesta este locul in care este scris textul in majoritatea documentelor bazate pe XML. Exista cateva opiuni (descrise in seciunea urmatoare) care pot personaliza acest comportament. In cazul in care acest lucru nu se potrivete cu formatul documentului dvs., suntei incurajat sa scriei propriul dvs. modul derivat din acesta, pentru a descrie detaliile formatului dvs. Pentru descrierea procesului, consultai seciunea SCRIEREA MODULELOR DERIVATE de mai jos. OPIUNI ACCEPTATE DE ACEST MODUL Opiunea globala de depanare face ca acest modul sa afieze irurile excluse, pentru a vedea daca sare peste ceva important. Acestea sunt opiunile particulare ale acestui modul: nostrip Il impiedica sa elimine spaiile din jurul irurilor extrase. wrap Canonizeaza irul de caractere de tradus, considerand ca spaiile albe nu sunt importante, i incadreaza documentul tradus. Aceasta opiune poate fi anulata prin opiuni de eticheta personalizate. A se vedea opiunea translated de mai jos. unwrap_attributes Atributele sunt invaluite in mod implicit. Aceasta opiune dezactiveaza invaluirea. caseinsensitive Aceasta face ca etichetele i atributele de cautare sa funcioneze in mod insensibil la majuscule. Daca este definita, va trata laNG i Lang ca lang. escapequotes Eludeaza ghilimelele din irurile de ieire. Necesar, de exemplu, pentru crearea resurselor de iruri de caractere pentru a fi utilizate de instrumentele de compilare Android. A se vedea i: https://developer.android.com/guide/topics/resources/string-resource.html includeexternal Daca este definita, entitaile externe sunt incluse in documentul generat (tradus) i pentru extragerea irurilor de caractere. Daca nu este definita, va trebui sa traducei entitaile externe separat, ca documente independente. ontagerror Aceasta opiune definete comportamentul modulului atunci cand intalnete o sintaxa XML nevalida (o eticheta de inchidere care nu se potrivete cu ultima eticheta de deschidere). Aceasta poate lua urmatoarele valori: fail Aceasta este valoarea implicita. Modulul va iei cu o eroare. warn Modulul va continua i va emite un avertisment. silent Modulul va continua fara afiarea niciunui avertisment. Fii ateni atunci cand utilizai aceasta opiune. In general, este recomandat sa corectai fiierul de intrare. tagsonly Nota: Aceasta opiune este depreciata. Extrage numai etichetele specificate in opiunea tags. In caz contrar, va extrage toate etichetele, cu excepia celor specificate. doctype ir de caractere care va incerca sa se potriveasca cu prima linie a documentului doctype (daca este definit). In caz contrar, un avertisment va indica faptul ca documentul ar putea fi de un tip greit. addlang ir ce indica ruta (de exemplu, ) unei etichete la care se adauga un atribut lang=,,...". Limba va fi definita ca numele de baza al fiierului PO fara nicio extensie .po. optionalclosingtag Argument boolean care indica daca etichetele de inchidere sunt opionale (ca in HTML). In mod implicit, lipsa etichetelor de inchidere genereaza o eroare tratata in conformitate cu ontagerror. tags Nota: Aceasta opiune este depreciata. Ar trebui sa utilizai in schimb opiunile translated i untranslated. Lista separata prin spaii a etichetelor pe care dorii sa le traducei sau sa le omitei. In mod implicit, etichetele specificate vor fi excluse, dar daca utilizai opiunea ,,tagsonly", etichetele specificate vor fi singurele incluse. Etichetele trebuie sa fie de forma , dar putei alatura unele () pentru a spune ca coninutul etichetei va fi tradus numai atunci cand este intr-o eticheta . De asemenea, putei specifica unele opiuni de eticheta prin introducerea unor caractere in faa ierarhiei etichetei. De exemplu, putei pune w (wrap) sau W (don't wrap) pentru a trece peste comportamentul implicit specificat de opiunea globala wrap. Exemplu: W attributes Lista separata prin spaii a atributelor etichetei pe care dorii sa le traducei. Putei specifica atributele dupa numele lor (de exemplu, ,,lang"), dar le putei prefixa cu o ierarhie a etichetei, pentru a specifica faptul ca acest atribut va fi tradus numai atunci cand se afla in eticheta specificata. De exemplu: lang specifica faptul ca atributul lang va fi tradus numai daca se afla intr-o eticheta , i acesta se afla intr-o eticheta . foldattributes Nu traduce atributele din etichetele inline. In schimb, inlocuiete toate atributele unui etichete cu po4a-id=. Acest lucru este util atunci cand atributele nu trebuie traduse, deoarece simplifica irurile pentru traducatori i evita greelile de scriere. customtag Lista de etichete separate prin spaii care nu ar trebui tratate ca etichete. Aceste etichete sunt tratate ca inline i nu trebuie sa fie inchise. break Lista de etichete separate prin spaii care ar trebui sa intrerupa secvena. In mod implicit, toate etichetele intrerup secvena. Etichetele trebuie sa fie sub forma , dar putei alatura unele (), daca o eticheta () ar trebui sa fie luata in considerare numai atunci cand este in interiorul unei alte etichete (). Va rugam sa reinei ca o eticheta trebuie sa fie listata intr-un singur ir de definiii break, inline placeholder, sau customtag. inline Lista de etichete separate prin spaiu care ar trebui tratate ca fiind inline. In mod implicit, toate etichetele intrerup secvena. Etichetele trebuie sa fie sub forma , dar putei alatura unele (), daca o eticheta () ar trebui sa fie luata in considerare numai atunci cand este in interiorul unei alte etichete (). placeholder Lista de etichete, separate prin spaii, care ar trebui sa fie tratate ca marcatori de poziie. Marcatorii de poziie nu intrerup secvena, dar coninutul acestora este tradus separat. Locaia marcatorului de poziie in blocul sau va fi marcata cu un ir similar cu: Etichetele trebuie sa fie sub forma , dar putei alatura unele (), daca o eticheta () ar trebui sa fie luata in considerare numai atunci cand este in interiorul unei alte etichete (). break-pi In mod implicit, instruciunile de procesare (de exemplu, etichetele "") sunt tratate ca etichete inline. Trecei aceasta opiune daca dorii ca PI sa fie tratata ca o eticheta de intrerupere. Reinei ca etichetele PHP neprocesate sunt tratate ca Instruciuni de procesare de catre analizatorul analitic. nodefault Lista de etichete separate prin spaii pe care modulul nu ar trebui sa incerce sa le defineasca implicit in nicio categorie. Daca avei o eticheta a carei definiie implicita este stabilita de subclasa acestui modul, dar dorii sa stabilii o definiie alternativa, trebuie sa listai eticheta respectiva ca parte a irului de definiii nodefault. cpp Accepta directivele preprocesorului C. Atunci cand aceasta opiune este activata, po4a va considera directivele preprocesorului ca separatoare de paragraf. Acest lucru este important daca fiierul XML trebuie preprocesat, deoarece in caz contrar directivele pot fi inserate in mijlocul liniilor daca po4a considera ca aparin paragrafului curent, iar acestea nu vor fi recunoscute de preprocesor. Nota: directivele preprocesorului trebuie sa apara numai intre etichete (ele nu trebuie sa rupa o eticheta). translated Lista de etichete separate prin spaii pe care dorii sa le traducei. Etichetele trebuie sa fie sub forma , dar putei alatura unele (), daca o eticheta () ar trebui sa fie luata in considerare numai atunci cand este in interiorul unei alte etichete (). De asemenea, putei specifica unele opiuni de eticheta prin introducerea unor caractere in faa ierarhiei etichetei. Aceasta inlocuiete comportamentul implicit specificat de opiunea globala wrap i defaulttranslateoption. w Etichetele trebuie sa fie traduse, iar coninutul poate fi reincadrat (redimensionat). W Etichetele trebuie sa fie traduse, iar coninutul nu trebuie sa fie reincadrat (redimensionat). i Etichetele trebuie traduse inline. p Etichetele trebuie traduse ca marcatori de poziie. Intern, analizorului XML ii pasa doar de aceste patru opiuni: w W i p. * Etichetele enumerate in break sunt stabilite la w sau W in funcie de opiunea wrap. * Etichetele enumerate in inline sunt stabilite la i. Etichetele enumerate in placeholder sunt stabilite la p. * Etichetele enumerate in untranslated sunt fara niciuna dintre aceste opiuni definite. Putei verifica comportamentul parametrului intern real invocand po4a cu opiunea --debug. Exemplu: W Va rugam sa reinei ca o eticheta trebuie listata in irul de definiii translated sau untranslated. untranslated Lista de etichete separate prin spaii pe care nu dorii sa le traducei. Etichetele trebuie sa fie sub forma , dar putei alatura unele (), daca o eticheta () ar trebui sa fie luata in considerare numai atunci cand este in interiorul unei alte etichete (). Va rugam sa reinei ca o eticheta inline traductibila intr-o eticheta netradusa este tratata ca o eticheta de intrerupere traductibila, opiunea i este eliminata i w sau W este stabilita in funcie de opiunea wrap. defaulttranslateoption Categoriile implicite pentru etichetele care nu sunt in niciuna dintre categoriile ,,translated", ,,untranslated", ,,break", ,,inline" sau ,,placeholder". Acesta este un set de litere definit in translated i aceasta opiune este valabila numai pentru etichetele traductibile. SCRIEREA MODULELOR DERIVATE DEFINII ETICHETELE I ATRIBUTELE CARE URMEAZA SA FIE TRADUSE Cea mai simpla personalizare este sa definii etichetele i atributele pe care dorii ca analizatorul sa le traduca. Acest lucru ar trebui facut in funcia initialize(). Mai intai ar trebui sa apelai funcia principala initialize(), pentru a obine opiunile din linia de comanda, iar apoi sa adaugai definiiile dvs. personalizate la tabelul opiunilor. Daca dorii sa tratai unele opiuni noi din linia de comanda, trebuie sa le definii inainte de a apela funcia principala initialize(): $self->{options}{'new_option'}=''; $self->SUPER::initialize(%options); $self->{options}{'_default_translated'}.='

'; $self->{options}{'attributes'}.=' <p>lang id'; $self->{options}{'_default_inline'}.=' <br>'; $self->treat_options; Trebuie sa utiliza<?>i op<?>iunile _default_inline, _default_break, _default_placeholder, _default_translated, _default_untranslated <?>i _default_attributes in modulele derivate. Acest lucru permite utilizatorilor sa inlocuiasca comportamentul implicit definit in modulul dvs. cu op<?>iuni de linie de comanda. SUPRASCRIE COMPORTAMENTUL IMPLICIT CU OP<?>IUNI DE LINIE DE COMANDA Daca nu va place comportamentul implicit al modulului xml <?>i al modulelor sale derivate, pute<?>i furniza op<?>iuni de linie de comanda pentru a le modifica comportamentul. Vede<?>i Locale::Po4a::Docbook(3pm), SUPRASCRIEREA FUNC<?>IEI found_string() Un alt pas simplu este sa suprascrie<?>i func<?>ia ,,found_string", care prime<?>te <?>irurile extrase de analizator, pentru a le traduce. Aici pute<?>i controla <?>irurile de caractere pe care dori<?>i sa le traduce<?>i <?>i pute<?>i efectua transformari ale acestora inainte sau dupa traducerea propriu-zisa. Acesta prime<?>te textul extras, referin<?>a la locul de unde a fost extras <?>i un tabel de elemente asociate care con<?>ine informa<?>ii suplimentare pentru a controla ce <?>iruri de caractere sa traduca, cum sa le traduca <?>i sa genereze comentariul. Con<?>inutul acestor op<?>iuni depinde de tipul de <?>ir de caractere (specificat intr-o intrare a acestui tabel): type="tag" <?>irul gasit este con<?>inutul unei etichete traductibile. Intrarea ,,tag_options" con<?>ine caracterele de op<?>iune din fa<?>a ierarhiei etichetelor in op<?>iunea ,,tags" a modulului. type="attribute" Inseamna ca <?>irul gasit este valoarea unui atribut traductibil. Intrarea ,,attribute" are numele atributului. Aceasta trebuie sa returneze textul care va inlocui originalul in documentul tradus. Iata un exemplu de baza al acestei func<?>ii: sub found_string { my ($self,$text,$ref,$options)=@_; $text = $self->translate($text,$ref,"type ".$options->{'type'}, 'wrap'=>$self->{options}{'wrap'}); return $text; } Exista un alt exemplu simplu in noul modul Dia, care filtreaza doar cateva <?>iruri de caractere. MODIFICAREA TIPURILOR DE ETICHETE (DE FACUT) Acesta este unul mai complex, dar permite o personalizare (aproape) totala. Se bazeaza pe o lista de tabele de elemente asociate, fiecare definind comportamentul unui tip de eticheta. Lista ar trebui sa fie ordonata astfel incat cele mai generale etichete sa fie dupa cele mai concrete (ordonate mai intai dupa cheile de inceput <?>i apoi dupa cele de sfar<?>it). Pentru a defini un tip de eticheta, va trebui sa crea<?>i un tabel cu urmatoarele chei: beginning Specifica inceputul etichetei, dupa ,,<". end Specifica sfar<?>itul etichetei, inainte de ,,>". breaking Spune daca aceasta este o clasa de eticheta de intrerupere. O eticheta de neintrerupere (inline) este una care poate fi luata ca parte a con<?>inutului unei alte etichete. Aceasta poate lua valorile fals (0), adevarat (1) sau nedefinita. Daca o lasa<?>i nedefinita, va trebui sa defini<?>i func<?>ia f_breaking care va spune daca o eticheta concreta din aceasta clasa este o eticheta de intrerupere sau nu. f_breaking Este o func<?>ie care va spune daca urmatoarea eticheta este una de intrerupere sau nu. Ar trebui sa fie definita daca op<?>iunea breaking nu este. f_extract Daca lasa<?>i aceasta cheie nedefinita, func<?>ia de extragere generica va trebui sa extraga eticheta in sine. Este util pentru etichetele care pot con<?>ine alte etichete sau structuri speciale, astfel incat analizatorul principal sa nu innebuneasca. Aceasta func<?>ie prime<?>te un argument boolean care spune daca eticheta trebuie sau nu sa fie eliminata din fluxul de intrare. f_translate Aceasta func<?>ie prime<?>te eticheta (in formatul get_string_until()) <?>i returneaza eticheta tradusa (atributele traduse sau toate transformarile necesare) ca un singur <?>ir. FUNC<?>II INTERNE utilizate pentru scrierea analizatorilor derivativi LUCRAND CU ETICHETE get_path() Aceasta func<?>ie returneaza ruta catre eticheta curenta din radacina documentului, sub forma <html><body><p>. O matrice suplimentara de etichete (fara paranteze) poate fi trecuta ca argument. Aceste elemente de ruta sunt adaugate la sfar<?>itul rutei curente. tag_type() Aceasta func<?>ie returneaza indexul din lista tag_types care se potrive<?>te cu urmatoarea eticheta din fluxul de intrare sau -1 daca este la sfar<?>itul fi<?>ierului de intrare. Aici, eticheta are o structura care incepe cu < <?>i se termina cu > <?>i poate con<?>ine mai multe linii. Aceasta func<?>ioneaza pe matricea "@{$self->{TT}{doc_in}}" care con<?>ine datele documentului de intrare <?>i referin<?>a indirecta prin "$self->shiftline()" <?>i "$self->unshiftline($$)". extract_tag($$) Aceasta func<?>ie returneaza urmatoarea eticheta din fluxul de intrare fara inceput <?>i sfar<?>it, sub forma unei matrice, pentru a men<?>ine referin<?>ele din fi<?>ierul de intrare. Func<?>ia are doi parametri: tipul etichetei (returnat de tag_type) <?>i un parametru boolean, care indica daca aceasta ar trebui eliminata din fluxul de intrare. Aceasta func<?>ioneaza pe matricea "@{$self->{TT}{doc_in}}" care con<?>ine datele documentului de intrare <?>i referin<?>a indirecta prin "$self->shiftline()" <?>i "$self->unshiftline($$)". get_tag_name(@) Aceasta func<?>ie returneaza numele etichetei transmise ca argument, in forma de matrice returnata de extract_tag. breaking_tag() Aceasta func<?>ie returneaza un argument boolean care spune daca urmatoarea eticheta din fluxul de intrare este o eticheta de intrerupere sau nu (eticheta inline). Aceasta lasa fluxul de intrare intact. treat_tag() Aceasta func<?>ie traduce urmatoarea eticheta din fluxul de intrare. Folosind func<?>iile de traducere personalizate ale fiecarui tip de eticheta. Aceasta func<?>ioneaza pe matricea "@{$self->{TT}{doc_in}}" care con<?>ine datele documentului de intrare <?>i referin<?>a indirecta prin "$self->shiftline()" <?>i "$self->unshiftline($$)". tag_in_list($@) Aceasta func<?>ie returneaza o valoare <?>ir de caractere care spune daca primul argument (o ierarhie de etichete) se potrive<?>te cu oricare dintre etichetele din al doilea argument (o lista de etichete sau ierarhii de etichete). Daca nu se potrive<?>te, returneaza 0. In caz contrar, returneaza op<?>iunile etichetei potrivite (caracterele din fa<?>a etichetei) sau 1 (daca eticheta respectiva nu are op<?>iuni). LUCRAND CU ATRIBUTE treat_attributes(@) Aceasta func<?>ie se ocupa de traducerea atributelor etichetelor. Prime<?>te eticheta fara semnele de inceput / sfar<?>it, apoi gase<?>te atributele <?>i le traduce pe cele traductibile (specificate de op<?>iunea modulului attributes). Aceasta returneaza un <?>ir simplu cu eticheta tradusa. LUCRAND CU CON<?>INUT ETICHETAT treat_content() Aceasta func<?>ie ob<?>ine textul pana la urmatoarea eticheta de intrerupere (nu in linie) din fluxul de intrare. Il traduce utilizand func<?>iile de traducere personalizate ale fiecarui tip de eticheta. Aceasta func<?>ioneaza pe matricea "@{$self->{TT}{doc_in}}" care con<?>ine datele documentului de intrare <?>i referin<?>a indirecta prin "$self->shiftline()" <?>i "$self->unshiftline($$)". LUCRAND CU OP<?>IUNILE MODULULUI treat_options() Aceasta func<?>ie completeaza structurile interne care con<?>in etichetele, atributele <?>i datele inline cu op<?>iunile modulului (specificate in linia de comanda sau in func<?>ia de ini<?>ializare). OB<?>INEREA TEXTULUI DIN DOCUMENTUL DE INTRARE get_string_until($%) Aceasta func<?>ie returneaza o matrice cu liniile (<?>i referin<?>ele) din documentul de intrare pana cand gase<?>te primul argument. Al doilea argument este un <?>ir de valori numerice pentru op<?>iuni. Valoarea 0 inseamna dezactivat (implicit) <?>i 1, activat. Op<?>iunile valide sunt: include Aceasta face ca matricea returnata sa con<?>ina textul cautat remove Aceasta elimina fluxul returnat de la intrare unquoted Aceasta asigura ca textul cautat se afla in afara oricaror ghilimele regex Aceasta indica faptul ca primul argument este o expresie regulata in loc de un <?>ir simplu skip_spaces(\@) Aceasta func<?>ie prime<?>te ca argument referin<?>a la un paragraf (in formatul returnat de get_string_until), ignora spa<?>iile de titlu ale acestuia <?>i le returneaza sub forma unui <?>ir simplu. join_lines(@) Aceasta func<?>ie returneaza un <?>ir de caractere simplu cu textul din matricea de argumente (eliminand referin<?>ele). STAREA ACESTUI MODUL Acest modul poate traduce etichete <?>i atribute. LISTA CU LUCRURI DE FACUT DOCTYPE (ENTITA<?>I) Exista un suport minim pentru traducerea entita<?>ilor. Acestea sunt traduse ca un intreg, iar etichetele nu sunt luate in considerare. Entita<?>ile multilinie nu sunt acceptate, iar entita<?>ile sunt intotdeauna reincadrate (redimensionate) in timpul traducerii. MODIFICAREA TIPURILOR DE ETICHETE DIN MODULELE EREDATE (mutarea structurii tag_types in interiorul tabelului de elemente asociate $self?) CONSULTA<?>I <?>I Locale::Po4a::TransTractor(3pm), po4a(7) AUTORI Jordi Vilalta <jvprat@gmail.com> Nicolas Francois <nicolas.francois@centraliens.net> DREPTURI DE AUTOR <?>i LICEN<?>A Drepturi de autor (C) 2004 Jordi Vilalta <jvprat@gmail.com> Drepturi de autor (C) 2008-2009 Nicolas Francois <nicolas.francois@centraliens.net> Acest program este software liber; il pute<?>i redistribui <?>i/sau modifica in conformitate cu termenii GPL v2.0 sau o versiune ulterioara (consulta<?>i fi<?>ierul COPYING). perl v5.42.0 2025-11-22 LOCALE::PO4A::XML.3PM(1)