LOCALE::PO4A::XML.3PM(1)

NUME
Locale::Po4a::Xml - convertește documente XML și derivate din/în fișiere PO

DESCRIERE
Scopul proiectului po4a (PO pentru orice) este de a ușura traducerile (și mai interesant, întreținerea traducerilor) folosind instrumente gettext în domenii în care nu erau așteptate, cum ar fi documentația.

Locale::Po4a::Xml este un modul care ajută la traducerea documentelor XML în alte limbi [umane]. De asemenea, poate fi folosit ca bază 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 conținutul etichetei, fără atribute, deoarece acesta este locul în care este scris textul în majoritatea documentelor bazate pe XML.

Există câteva opțiuni (descrise în secțiunea următoare) care pot personaliza acest comportament. În cazul în care acest lucru nu se potrivește cu formatul documentului dvs., sunteți încurajat să scrieți propriul dvs. modul derivat din acesta, pentru a descrie detaliile formatului dvs. Pentru descrierea procesului, consultați secțiunea SCRIEREA MODULELOR DERIVATE de mai jos.

OPȚIUNI ACCEPTATE DE ACEST MODUL
Opțiunea globală de depanare face ca acest modul să afișeze șirurile excluse, pentru a vedea dacă sare peste ceva important.

Acestea sunt opțiunile particulare ale acestui modul:

nostrip
    Îl împiedică să elimine spațiile din jurul șirurilor extrase.

wrap
    Canonizează șirul de caractere de tradus, considerând că spațiile albe nu sunt importante, și încadrează documentul tradus. Această opțiune poate fi anulată prin opțiuni de etichetă personalizate. A se vedea opțiunea translated de mai jos.

unwrap_attributes
    Atributele sunt învăluite în mod implicit. Această opțiune dezactivează învăluirea.

caseinsensitive
    Aceasta face ca etichetele și atributele de căutare să funcționeze în mod insensibil la majuscule. Dacă este definită, va trata <BooK>laNG și <BOOK>Lang ca <book>lang.

escapequotes
    Eludează ghilimelele din șirurile de ieșire. 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
    Dacă este definită, entitățile externe sunt incluse în documentul generat (tradus) și pentru extragerea șirurilor de caractere. Dacă nu este definită, va trebui să traduceți entitățile externe separat, ca documente independente.

ontagerror
    Această opțiune definește comportamentul modulului atunci când întâlnește o sintaxă XML nevalidă (o etichetă de închidere care nu se potrivește cu ultima etichetă de deschidere). Aceasta poate lua următoarele valori:

    fail
        Aceasta este valoarea implicită. Modulul va ieși cu o eroare.

    warn
        Modulul va continua și va emite un avertisment.

    silent
        Modulul va continua fără afișarea niciunui avertisment.

    Fiți atenți atunci când utilizați această opțiune. În general, este recomandat să corectați fișierul de intrare.

tagsonly
    Notă: Această opțiune este depreciată.

    Extrage numai etichetele specificate în opțiunea tags. În caz contrar, va extrage toate etichetele, cu excepția celor specificate.

doctype
    Șir de caractere care va încerca să se potrivească cu prima linie a documentului doctype (dacă este definit). În caz contrar, un avertisment va indica faptul că documentul ar putea fi de un tip greșit.

addlang
    Șir ce indică ruta (de exemplu, <bbb><aaa>) unei etichete la care se adaugă un atribut lang=„...”. Limba va fi definită ca numele de bază al fișierului PO fără nicio extensie .po.

optionalclosingtag
    Argument boolean care indică dacă etichetele de închidere sunt opționale (ca în HTML). În mod implicit, lipsa etichetelor de închidere generează o eroare tratată în conformitate cu ontagerror.

tags
    Notă: Această opțiune este depreciată. Ar trebui să utilizați în schimb opțiunile translated și untranslated.

    Listă separată prin spații a etichetelor pe care doriți să le traduceți sau să le omiteți. În mod implicit, etichetele specificate vor fi excluse, dar dacă utilizați opțiunea „tagsonly”, etichetele specificate vor fi singurele incluse. Etichetele trebuie să fie de forma <aaa>, dar puteți alătura unele (<bbb><aaa>) pentru a spune că conținutul etichetei <aaa> va fi tradus numai atunci când este într-o etichetă <bbb>.

    De asemenea, puteți specifica unele opțiuni de etichetă prin introducerea unor caractere în fața ierarhiei etichetei. De exemplu, puteți pune w (wrap) sau W (don't wrap) pentru a trece peste comportamentul implicit specificat de opțiunea globală wrap.

    Exemplu: W<capitolr><titlu>

attributes
    Listă separată prin spații a atributelor etichetei pe care doriți să le traduceți. Puteți specifica atributele după numele lor (de exemplu, „lang”), dar le puteți prefixa cu o ierarhie a etichetei, pentru a specifica faptul că acest atribut va fi tradus numai atunci când se află în eticheta specificată. De exemplu: <bbb><aaa>lang specifică faptul că atributul lang va fi tradus numai dacă se află într-o etichetă <aaa>, și acesta se află într-o etichetă <bbb>.

foldattributes
    Nu traduce atributele din etichetele inline. În schimb, înlocuiește toate atributele unui etichete cu po4a-id=<id>.

    Acest lucru este util atunci când atributele nu trebuie traduse, deoarece simplifică șirurile pentru traducători și evită greșelile de scriere.

customtag
    Listă de etichete separate prin spații care nu ar trebui tratate ca etichete. Aceste etichete sunt tratate ca inline și nu trebuie să fie închise.

break
    Lista de etichete separate prin spații care ar trebui să întrerupă secvența. În mod implicit, toate etichetele întrerup secvența.

    Etichetele trebuie să fie sub forma <aaa>, dar puteți alătura unele (<bbb><aaa>), dacă o etichetă (<aaa>) ar trebui să fie luată în considerare numai atunci când este în interiorul unei alte etichete (<bbb>).

    Vă rugăm să rețineți că o etichetă trebuie să fie listată într-un singur șir de definiții break, inline placeholder, sau customtag.

inline
    Listă de etichete separate prin spațiu care ar trebui tratate ca fiind inline. În mod implicit, toate etichetele întrerup secvența.

    Etichetele trebuie să fie sub forma <aaa>, dar puteți alătura unele (<bbb><aaa>), dacă o etichetă (<aaa>) ar trebui să fie luată în considerare numai atunci când este în interiorul unei alte etichete (<bbb>).

placeholder
    Listă de etichete, separate prin spații, care ar trebui să fie tratate ca marcatori de poziție. Marcatorii de poziție nu întrerup secvența, dar conținutul acestora este tradus separat.

    Locația marcatorului de poziție în blocul său va fi marcată cu un șir similar cu:

      <placeholder type=\"footnote\" id=\"0\"/>

    Etichetele trebuie să fie sub forma <aaa>, dar puteți alătura unele (<bbb><aaa>), dacă o etichetă (<aaa>) ar trebui să fie luată în considerare numai atunci când este în interiorul unei alte etichete (<bbb>).

break-pi
    În mod implicit, instrucțiunile de procesare (de exemplu, etichetele "<? ... ?>") sunt tratate ca etichete inline. Treceți această opțiune dacă doriți ca PI să fie tratată ca o etichetă de întrerupere. Rețineți că etichetele PHP neprocesate sunt tratate ca Instrucțiuni de procesare de către analizatorul analitic.

nodefault
    Listă de etichete separate prin spații pe care modulul nu ar trebui să încerce să le definească implicit în nicio categorie.

    Dacă aveți o etichetă a cărei definiție implicită este stabilită de subclasa acestui modul, dar doriți să stabiliți o definiție alternativă, trebuie să listați eticheta respectivă ca parte a șirului de definiții nodefault.

cpp Acceptă directivele preprocesorului C. Atunci când această opțiune este activată, po4a va considera directivele preprocesorului ca separatoare de paragraf. Acest lucru este important dacă fișierul XML trebuie preprocesat, deoarece în caz contrar directivele pot fi inserate în mijlocul liniilor dacă po4a consideră că aparțin paragrafului curent, iar acestea nu vor fi recunoscute de preprocesor. Notă: directivele preprocesorului trebuie să apară numai între etichete (ele nu trebuie să rupă o etichetă).

translated
    Listă de etichete separate prin spații pe care doriți să le traduceți.

    Etichetele trebuie să fie sub forma <aaa>, dar puteți alătura unele (<bbb><aaa>), dacă o etichetă (<aaa>) ar trebui să fie luată în considerare numai atunci când este în interiorul unei alte etichete (<bbb>).

    De asemenea, puteți specifica unele opțiuni de etichetă prin introducerea unor caractere în fața ierarhiei etichetei. Aceasta înlocuiește comportamentul implicit specificat de opțiunea globală wrap și defaulttranslateoption.

    w   Etichetele trebuie să fie traduse, iar conținutul poate fi reîncadrat (redimensionat).

    W   Etichetele trebuie să fie traduse, iar conținutul nu trebuie să fie reîncadrat (redimensionat).

    i   Etichetele trebuie traduse inline.

    p   Etichetele trebuie traduse ca marcatori de poziție.

    Intern, analizorului XML îi pasă doar de aceste patru opțiuni: w W i p.

    * Etichetele enumerate în break sunt stabilite la w sau W în funcție de opțiunea wrap.

    * Etichetele enumerate în inline sunt stabilite la i.

    Etichetele enumerate în placeholder sunt stabilite la p.

    * Etichetele enumerate în untranslated sunt fără niciuna dintre aceste opțiuni definite.

    Puteți verifica comportamentul parametrului intern real invocând po4a cu opțiunea --debug.

    Exemplu: W<capitolr><titlu>

    Vă rugăm să rețineți că o etichetă trebuie listată în șirul de definiții translated sau untranslated.

untranslated
    Listă de etichete separate prin spații pe care nu doriți să le traduceți.

    Etichetele trebuie să fie sub forma <aaa>, dar puteți alătura unele (<bbb><aaa>), dacă o etichetă (<aaa>) ar trebui să fie luată în considerare numai atunci când este în interiorul unei alte etichete (<bbb>).

    Vă rugăm să rețineți că o etichetă inline traductibilă într-o etichetă netradusă este tratată ca o etichetă de întrerupere traductibilă, opțiunea i este eliminată și w sau W este stabilită în funcție de opțiunea wrap.

defaulttranslateoption
    Categoriile implicite pentru etichetele care nu sunt în niciuna dintre categoriile „translated”, „untranslated”, „break”, „inline” sau „placeholder”.

    Acesta este un set de litere definit în translated și această opțiune este valabilă numai pentru etichetele traductibile.

SCRIEREA MODULELOR DERIVATE

  DEFINIȚI ETICHETELE ȘI ATRIBUTELE CARE URMEAZĂ SĂ FIE TRADUSE
Cea mai simplă personalizare este să definiți etichetele și atributele pe care doriți ca analizatorul să le traducă. Acest lucru ar trebui făcut în funcția initialize(). Mai întâi ar trebui să apelați funcția principală initialize(), pentru a obține opțiunile din linia de comandă, iar apoi să adăugați definițiile dvs. personalizate la tabelul opțiunilor. Dacă doriți să tratați unele opțiuni noi din linia de comandă, trebuie să le definiți înainte de a apela funcția principală initialize():

  $self->{options}{'new_option'}='';
  $self->SUPER::initialize(%options);
  $self->{options}{'_default_translated'}.=' <p> <head><title>';
  $self->{options}{'attributes'}.=' <p>lang id';
  $self->{options}{'_default_inline'}.=' <br>';
  $self->treat_options;

Trebuie să utilizați opțiunile _default_inline, _default_break, _default_placeholder, _default_translated, _default_untranslated și _default_attributes în modulele derivate. Acest lucru permite utilizatorilor să înlocuiască comportamentul implicit definit în modulul dvs. cu opțiuni de linie de comandă.

  SUPRASCRIE COMPORTAMENTUL IMPLICIT CU OPȚIUNI DE LINIE DE COMANDĂ
Dacă nu vă place comportamentul implicit al modulului xml și al modulelor sale derivate, puteți furniza opțiuni de linie de comandă pentru a le modifica comportamentul.

Vedeți Locale::Po4a::Docbook(3pm),

  SUPRASCRIEREA FUNCȚIEI found_string()
Un alt pas simplu este să 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 să le traduceți și puteți efectua transformări ale acestora înainte sau după traducerea propriu-zisă.

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 să traducă, cum să le traducă și să genereze comentariul.

Conținutul acestor opțiuni depinde de tipul de șir de caractere (specificat într-o intrare a acestui tabel):

type="tag"
    Șirul găsit este conținutul unei etichete traductibile. Intrarea „tag_options” conține caracterele de opțiune din fața ierarhiei etichetelor în opțiunea „tags” a modulului.

type="attribute"
    Înseamnă că șirul găsit este valoarea unui atribut traductibil. Intrarea „attribute” are numele atributului.

Aceasta trebuie să returneze textul care va înlocui originalul în documentul tradus. Iată un exemplu de bază 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;
  }

Există un alt exemplu simplu în noul modul Dia, care filtrează doar câteva șiruri de caractere.

  MODIFICAREA TIPURILOR DE ETICHETE (DE FĂCUT)
Acesta este unul mai complex, dar permite o personalizare (aproape) totală. Se bazează pe o listă de tabele de elemente asociate, fiecare definind comportamentul unui tip de etichetă. Lista ar trebui să fie ordonată astfel încât cele mai generale etichete să fie după cele mai concrete (ordonate mai întâi după cheile de început și apoi după cele de sfârșit). Pentru a defini un tip de etichetă, va trebui să creați un tabel cu următoarele chei:

beginning
    Specifică începutul etichetei, după „<”.

end Specifică sfârșitul etichetei, înainte de „>”.

breaking
    Spune dacă aceasta este o clasă de etichetă de întrerupere. O etichetă de neîntrerupere (inline) este una care poate fi luată ca parte a conținutului unei alte etichete. Aceasta poate lua valorile fals (0), adevărat (1) sau nedefinită. Dacă o lăsați nedefinită, va trebui să definiți funcția f_breaking care va spune dacă o etichetă concretă din această clasă este o etichetă de întrerupere sau nu.

f_breaking
    Este o funcție care va spune dacă următoarea etichetă este una de întrerupere sau nu. Ar trebui să fie definită dacă opțiunea breaking nu este.

f_extract
    Dacă lăsați această cheie nedefinită, funcția de extragere generică va trebui să extragă eticheta în sine. Este util pentru etichetele care pot conține alte etichete sau structuri speciale, astfel încât analizatorul principal să nu înnebunească. Această funcție primește un argument boolean care spune dacă eticheta trebuie sau nu să fie eliminată din fluxul de intrare.

f_translate
    Această funcție primește eticheta (în formatul get_string_until()) și returnează eticheta tradusă (atributele traduse sau toate transformările necesare) ca un singur șir.

FUNCȚII INTERNE utilizate pentru scrierea analizatorilor derivativi

  LUCRÂND CU ETICHETE

get_path()
    Această funcție returnează ruta către eticheta curentă din rădăcina documentului, sub forma <html><body><p>.

    O matrice suplimentară de etichete (fără paranteze) poate fi trecută ca argument. Aceste elemente de rută sunt adăugate la sfârșitul rutei curente.

tag_type()
    Această funcție returnează indexul din lista tag_types care se potrivește cu următoarea etichetă din fluxul de intrare sau -1 dacă este la sfârșitul fișierului de intrare.

    Aici, eticheta are o structură care începe cu < și se termină cu > și poate conține mai multe linii.

    Aceasta funcționează pe matricea "@{$self->{TT}{doc_in}}" care conține datele documentului de intrare și referință indirectă prin "$self->shiftline()" și "$self->unshiftline($$)".

extract_tag($$)
    Această funcție returnează următoarea etichetă din fluxul de intrare fără început și sfârș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 indică dacă aceasta ar trebui eliminată din fluxul de intrare.

    Aceasta funcționează pe matricea "@{$self->{TT}{doc_in}}" care conține datele documentului de intrare și referință indirectă prin "$self->shiftline()" și "$self->unshiftline($$)".

get_tag_name(@)
    Această funcție returnează numele etichetei transmise ca argument, în forma de matrice returnată de extract_tag.

breaking_tag()
    Această funcție returnează un argument boolean care spune dacă următoarea etichetă din fluxul de intrare este o etichetă de întrerupere sau nu (etichetă inline). Aceasta lasă fluxul de intrare intact.

treat_tag()
    Această funcție traduce următoarea etichetă din fluxul de intrare. Folosind funcțiile de traducere personalizate ale fiecărui tip de etichetă.

    Aceasta funcționează pe matricea "@{$self->{TT}{doc_in}}" care conține datele documentului de intrare și referință indirectă prin "$self->shiftline()" și "$self->unshiftline($$)".

tag_in_list($@)
    Această funcție returnează o valoare șir de caractere care spune dacă primul argument (o ierarhie de etichete) se potrivește cu oricare dintre etichetele din al doilea argument (o listă de etichete sau ierarhii de etichete). Dacă nu se potrivește, returnează 0. În caz contrar, returnează opțiunile etichetei potrivite (caracterele din fața etichetei) sau 1 (dacă eticheta respectivă nu are opțiuni).

  LUCRÂND CU ATRIBUTE

treat_attributes(@)
    Această funcție se ocupă de traducerea atributelor etichetelor. Primește eticheta fără semnele de început / sfârșit, apoi găsește atributele și le traduce pe cele traductibile (specificate de opțiunea modulului attributes). Aceasta returnează un șir simplu cu eticheta tradusă.

  LUCRÂND CU CONȚINUT ETICHETAT

treat_content()
    Această funcție obține textul până la următoarea etichetă de întrerupere (nu în linie) din fluxul de intrare. Îl traduce utilizând funcțiile de traducere personalizate ale fiecărui tip de etichetă.

    Aceasta funcționează pe matricea "@{$self->{TT}{doc_in}}" care conține datele documentului de intrare și referință indirectă prin "$self->shiftline()" și "$self->unshiftline($$)".

  LUCRÂND CU OPȚIUNILE MODULULUI

treat_options()
    Această funcție completează structurile interne care conțin etichetele, atributele și datele inline cu opțiunile modulului (specificate în linia de comandă sau în funcția de inițializare).

  OBȚINEREA TEXTULUI DIN DOCUMENTUL DE INTRARE

get_string_until($%)
    Această funcție returnează o matrice cu liniile (și referințele) din documentul de intrare până când găsește primul argument. Al doilea argument este un șir de valori numerice pentru opțiuni. Valoarea 0 înseamnă dezactivat (implicit) și 1, activat.

    Opțiunile valide sunt:

    include
        Aceasta face ca matricea returnată să conțină textul căutat

    remove
        Aceasta elimină fluxul returnat de la intrare

    unquoted
        Aceasta asigură că textul căutat se află în afara oricăror ghilimele

    regex
        Aceasta indică faptul că primul argument este o expresie regulată în loc de un șir simplu

skip_spaces(\@)
    Această funcție primește ca argument referința la un paragraf (în formatul returnat de get_string_until), ignoră spațiile de titlu ale acestuia și le returnează sub forma unui șir simplu.

join_lines(@)
    Această funcție returnează un șir de caractere simplu cu textul din matricea de argumente (eliminând referințele).

STAREA ACESTUI MODUL
Acest modul poate traduce etichete și atribute.

LISTA CU LUCRURI DE FĂCUT
DOCTYPE (ENTITĂȚI)

Există un suport minim pentru traducerea entităților. Acestea sunt traduse ca un întreg, iar etichetele nu sunt luate în considerare. Entitățile multilinie nu sunt acceptate, iar entitățile sunt întotdeauna reîncadrate (redimensionate) în timpul traducerii.

MODIFICAREA TIPURILOR DE ETICHETE DIN MODULELE EREDATE (mutarea structurii tag_types în interiorul tabelului de elemente asociate $self?)

CONSULTAȚI ȘI
Locale::Po4a::TransTractor(3pm), po4a(7)

AUTORI
 Jordi Vilalta <jvprat@gmail.com>
 Nicolas François <nicolas.francois@centraliens.net>

DREPTURI DE AUTOR și LICENȚĂ
 Drepturi de autor © 2004 Jordi Vilalta <jvprat@gmail.com>
 Drepturi de autor © 2008-2009 Nicolas François <nicolas.francois@centraliens.net>

Acest program este software liber; îl puteți redistribui și/sau modifica în conformitate cu termenii GPL v2.0 sau o versiune ulterioară (consultați fișierul COPYING).