LOCALE::PO4A::TRANSTRACTOR.3PM(1)          User Contributed Perl Documentation


NUME
       Locale::Po4a::TransTractor - trans(lator -- ex)tractor generic.

DESCRIERE
       Scopul proiectului po4a (PO pentru orice) este de a u<?>ura traducerile
       (<?>i mai interesant, intre<?>inerea traducerilor) folosind instrumente
       gettext in domenii in care nu erau a<?>teptate, cum ar fi
       documenta<?>ia.

       Aceasta clasa este stramo<?>ul fiecarui analizator po4a utilizat pentru
       a analiza un document, pentru a cauta <?>iruri traductibile, pentru a
       le extrage intr-un fi<?>ier PO <?>i pentru a le inlocui cu traducerea
       lor in documentul de ie<?>ire.

       Mai formal, acesta prime<?>te urmatoarele argumente ca intrare:

       - un document de tradus;

       - un fi<?>ier PO care con<?>ine traducerile care urmeaza sa fie
         utilizate.

       Ca ie<?>ire, produce:

       - un alt fi<?>ier PO, care rezulta din extragerea <?>irurilor
         traductibile din documentul de intrare;

       - un document tradus, cu aceea<?>i structura ca cel de la intrare, dar
         cu toate <?>irurile traductibile inlocuite cu traducerile gasite in
         fi<?>ierul PO furnizat la intrare.

       Iata o reprezentare grafica a acestui lucru:

          document intrare --\                             /---> Document ie<?>ire
                              \                           /         (tradus)
                               +--> func<?>ia parse() -----+
                              /                           \
          PO intrare --------/                             \---> PO ie<?>ire
                                                                 (extras)

FUNC<?>II PE CARE ANALIZATORUL TREBUIE SA LE SUPRASCRIE
       parse()
           Aici are loc toata munca: analizarea documentelor de intrare,
           generarea rezultatelor <?>i extragerea <?>irurilor traductibile.
           Acest lucru este destul de simplu folosind func<?>iile furnizate
           prezentate in sec<?>iunea FUNC<?>II INTERNE de mai jos.
           Consulta<?>i <?>i sec<?>iunea SINOPSIS, care prezinta un exemplu.

           Aceasta func<?>ie este apelata de func<?>ia process() de mai jos,
           dar daca alege<?>i sa utiliza<?>i func<?>ia new() <?>i sa
           adauga<?>i manual con<?>inut documentului, va trebui sa apela<?>i
           aceasta func<?>ie.

       docheader()
           Aceasta func<?>ie returneaza antetul pe care ar trebui sa il
           adaugam documentului produs, citat corespunzator pentru a fi un
           comentariu in limba <?>inta. Consulta<?>i sec<?>iunea Educarea
           dezvoltatorilor cu privire la traduceri, din po4a(7), pentru a afla
           la ce este buna aceasta func<?>ie.

SINOPSIS
       Urmatorul exemplu analizeaza o lista de paragrafe care incep cu ,,<p>".
       De dragul simplita<?>ii, presupunem ca documentul este bine formatat,
       adica ca etichetele ,,<p>" sunt singurele etichete prezente <?>i ca
       aceasta eticheta se afla chiar la inceputul fiecarui paragraf.

        sub parse {
          my $self = shift;

          PARAGRAPH: while (1) {
              my ($paragraph,$pararef)=("","");
              my $first=1;
              my ($line,$lref)=$self->shiftline();
              while (defined($line)) {
                  if ($line =~ m/<p>/ && !$first--; ) {
                      # Nu este prima data cand vedem <p>.
                      # Repune<?>i linia curenta in intrare,
                      # <?>i pune<?>i paragraful construit la ie<?>ire.
                      $self->unshiftline($line,$lref);

                      # Acum ca documentul este format, traduce<?>i-l:
                      #   - Elimina<?>i eticheta de inceput
                      $paragraph =~ s/^<p>//s;

                      #   - Introduce<?>i pentru a afi<?>a eticheta de inceput (netradusa)
                      #     <?>i restul paragrafului (tradus)
                      $self->pushline(  "<p>"
                                      . $self->translate($paragraph,$pararef)
                                      );

                      next PARAGRAPH;
                  } else {
                      # Adauga<?>i la paragraf
                      $paragraph .= $line;
                      $pararef = $lref unless(length($pararef));
                  }

                  # Reini<?>ializa<?>i bucla
                  ($line,$lref)=$self->shiftline();
              }
              # Nu a<?>i ob<?>inut o linie definita? Sfar<?>itul fi<?>ierului de intrare.
              return;
          }
        }

       Odata ce a<?>i implementat func<?>ia de analizare, pute<?>i utiliza
       clasa dvs. de documente, folosind interfa<?>a publica prezentata in
       sec<?>iunea urmatoare.

INTERFA<?>A PUBLICA pentru scripturile care utilizeaza analizatorul dvs.
   Constructor
       process(%)
           Aceasta func<?>ie poate face tot ce ave<?>i nevoie sa face<?>i cu
           un document po4a intr-o singura invocare. Argumentele sale trebuie
           sa fie impachetate ca o serie de elemente asociative. AC<?>IUNI:

           a. Cite<?>te toate fi<?>ierele PO specificate in po_in_name

           b. Cite<?>te toate documentele originale specificate in
              file_in_name

           c. Analizeaza documentul

           d. Cite<?>te <?>i aplica toate actele adi<?>ionale (addendele)
              specificate

           e. Scrie documentul tradus la file_out_name (daca este dat)

           f. Scrie fi<?>ierul PO extras la po_out_name (daca este dat)

           ARGUMENTE, in afara de cele acceptate de new() (cu tipul
           a<?>teptat):

           file_in_name (@)
               Lista de nume de fi<?>iere din care trebuie sa citim documentul
               de intrare.

           file_in_charset ($)
               Setul de caractere utilizat in documentul de intrare (daca nu
               este specificat, se utilizeaza UTF-8).

           file_out_name ($)
               Numele fi<?>ierului in care trebuie sa scriem documentul de
               ie<?>ire.

           file_out_charset ($)
               Setul de caractere utilizat in documentul de ie<?>ire (daca nu
               este specificat, se utilizeaza UTF-8).

           po_in_name (@)
               Lista de nume de fi<?>iere din care trebuie citite fi<?>ierele
               PO de intrare, care con<?>in traducerea ce va fi utilizata
               pentru a traduce documentul.

           po_out_name ($)
               Numele fi<?>ierului in care trebuie sa scriem fi<?>ierul PO de
               ie<?>ire, care con<?>ine <?>irurile extrase din documentul de
               intrare.

           addendum (@)
               Lista de nume de fi<?>iere din care trebuie sa citim addenda.

           addendum_charset ($)
               Setul de caractere pentru addenda.

       new(%)
           Creeaza un nou document po4a. Op<?>iuni acceptate (in seria de
           elemente asociative trecuta ca parametru):

           verbose ($)
               Stabile<?>te nivelul de detaliere al informa<?>iilor.

           debug ($)
               Define<?>te depanarea.

           wrapcol ($)
               Coloana la care ar trebui sa incadram textul in documentul de
               ie<?>ire (implicit: 76).

               Valoarea negativa inseamna sa nu se incadreze liniile deloc
               (fara intreruperi de linie).

           De asemenea, accepta urmatoarele op<?>iuni pentru fi<?>ierele Po
           subiacente: porefs, copyright-holder, msgid-bugs-address,
           package-name, package-version, wrap-po.

   Manipularea fi<?>ierelor de documente
       read($$$)
           Adauga un alt document de intrare de date la sfar<?>itul matricei
           existente "@{$self->{TT}{doc_in}}".

           Aceasta func<?>ie are doua argumente obligatorii <?>i unul
           op<?>ional.
            * Numele fi<?>ierului care urmeaza sa fie citit pe disc;
            * Numele care trebuie utilizat ca nume de fi<?>ier la construirea
           referin<?>ei in fi<?>ierul PO;
            * Setul de caractere care trebuie utilizat pentru a citi
           fi<?>ierul respectiv (UTF-8 in mod implicit)

           Aceasta matrice "@{$self->{TT}{doc_in}}" con<?>ine datele acestui
           document de intrare
            ca o matrice de <?>iruri de caractere cu semnifica<?>ii
           alternante.
            * <?>irul $textline con<?>ine fiecare linie a datelor text de
           intrare.
            * <?>irul "$filename:$linenum" con<?>ine loca<?>ia acestuia <?>i
           se nume<?>te
              ,,referin<?>a" ("linenum" incepe cu 1).

           Va rugam sa re<?>ine<?>i ca aceasta nu analizeaza nimic. Ar trebui
           sa utiliza<?>i func<?>ia parse() atunci cand a<?>i terminat cu
           impachetarea fi<?>ierelor de intrare in document.

       write($)
           Scrie documentul tradus in fi<?>ierul specificat.

           Aceste date de document traduse sunt furnizate de:
            * "$self->docheader()" care con<?>ine textul antetului pentru
           modul <?>i
            * "@{$self->{TT}{doc_out}}" care con<?>ine fiecare linie a
           textului principal tradus in matrice.

   Manipularea fi<?>ierelor PO
       readpo($)
           Adauga con<?>inutul unui fi<?>ier (al carui nume este trecut ca
           argument) la PO de intrare existent. Con<?>inutul vechi nu este
           eliminat.

       writepo($)
           Scrie fi<?>ierul PO extras la numele de fi<?>ier dat.

       stats()
           Returneaza cateva statistici despre traducerea efectuata pana in
           prezent. Va rugam sa re<?>ine<?>i ca nu sunt acelea<?>i statistici
           ca cele afi<?>ate de <<msgfmt --statistic>>. Aici, este vorba de
           statistici despre utilizarea recenta a fi<?>ierului PO, in timp ce
           <<msgfmt>> raporteaza starea fi<?>ierului. Este o func<?>ie de
           invaluire pentru func<?>ia Locale::Po4a::Po::stats_get aplicata la
           fi<?>ierul PO de intrare. Exemplu de utilizare:

               [utilizarea normala a documentului po4a...]

               ($percent,$hit,$queries) = $document->stats();
               print "Am gasit traduceri pentru $percent\% ($hit din $queries) de <?>iruri.\n";

   Manipularea addendelor
       addendum($)
           Va rugam sa consulta<?>i po4a(7) pentru mai multe informa<?>ii
           despre ce sunt addendele <?>i cum ar trebui sa le scrie
           traducatorii. Pentru a aplica un addendum documentului tradus, pur
           <?>i simplu trece<?>i numele sau de fi<?>ier la aceasta func<?>ie
           <?>i a<?>i terminat ;)

           Aceasta func<?>ie returneaza un numar intreg nenul in caz de
           eroare.

FUNC<?>II INTERNE utilizate pentru scrierea analizatorilor derivativi
   Ob<?>inerea intrarilor, furnizarea ie<?>irilor
       Sunt furnizate patru func<?>ii pentru a ob<?>ine intrare <?>i a returna
       ie<?>ire. Acestea sunt foarte asemanatoare cu shift/unshift <?>i
       push/pop din Perl.

        * Perl shift returneaza primul element din matrice <?>i il elimina din matrice.
        * Perl unshift antepune un element in matrice ca primul element din matrice.
        * Perl pop returneaza ultimul element al matricei <?>i il elimina din matrice.
        * Perl push adauga un element in matrice ca ultim element al matricei.

       Prima pereche este despre intrare, in timp ce a doua este despre
       ie<?>ire. Mnemonic: la intrare, sunte<?>i interesat de prima linie,
       ceea ce ofera shift(), iar la ie<?>ire dori<?>i sa adauga<?>i
       rezultatul la sfar<?>it, a<?>a cum face push().

       shiftline()
           Aceasta func<?>ie returneaza prima linie care urmeaza sa fie
           analizata <?>i referin<?>a corespunzatoare (impachetata ca o
           matrice) din matricea "@{$self->{TT}{doc_in}}" <?>i elimina aceste
           prime doua elemente ale matricei.  Aici, referin<?>a este furnizata
           de un <?>ir "$filename:$linenum".

       unshiftline($$)
           Deplaseaza ultima linie deplasata a documentului de intrare <?>i
           referin<?>a corespunzatoare inapoi la inceputul
           "{$self->{TT}{doc_in}}".

       pushline($)
           Introduce o linie noua la sfar<?>itul "{$self->{TT}{doc_out}}".

       popline()
           Extrage ultima linie introdusa de la sfar<?>itul
           "{$self->{TT}{doc_out}}".

   Marcarea <?>irurilor de caractere ca traductibile
       O func<?>ie este furnizata pentru a gestiona textul care trebuie
       tradus.

       translate($$$)
           Argumente obligatorii:

           - Un <?>ir de caractere de tradus

           - Referin<?>a acestui <?>ir de caractere (de exemplu, pozi<?>ia in
             fi<?>ierul de intrare)

           - Tipul acestui <?>ir (adica descrierea textuala a rolului sau
             structural; utilizat in Locale::Po4a::Po::gettextization(); vezi
             <?>i po4a(7), sec<?>iunea Gettextizarea: cum func<?>ioneaza?)

           Aceasta func<?>ie poate primi <?>i cateva argumente suplimentare.
           Acestea trebuie sa fie organizate ca p serie de elemente
           asociative. De exemplu:

             $self->translate("string","ref","type",
                              'wrap' => 1);

           wrap
               argument boolean care indica daca putem considera ca spa<?>iile
               albe din <?>ir nu sunt importante. Daca da, func<?>ia
               canonizeaza <?>irul de caractere inainte de a cauta o traducere
               sau de a-l extrage <?>i include traducerea.

           wrapcol
               coloana la care trebuie sa se incadreze (implicit: valoarea lui
               wrapcol specificata la crearea TransTractor sau 76).

               Valoarea negativa va fi sustrasa din valoarea implicita.

           comment
               un comentariu suplimentar pentru a adauga la intrare.

           Ac<?>iuni:

           - Trimite <?>irul, referin<?>a <?>i tipul in po_out.

           - Returneaza traducerea <?>irului de caractere (a<?>a cum se
             gase<?>te in po_in) astfel incat analizatorul sa poata construi
             doc_out.

           - Gestioneaza seturile de caractere pentru a recodifica <?>irurile
             inainte de a le trimite la po_out <?>i inainte de a returna
             traducerile.

   Diverse func<?>ii
       verbose()
           Returneaza daca op<?>iunea ,,verbose" (de detaliere a
           informa<?>iilor) a fost trecuta in timpul crearii TransTractor.

       debug()
           Returneaza daca op<?>iunea ,,debug" (de depanare) a fost trecuta in
           timpul crearii TransTractor.

       get_in_charset()
           Aceasta func<?>ie returneaza setul de caractere care a fost
           furnizat ca set de caractere principal

       get_out_charset()
           Aceasta func<?>ie va returna setul de caractere care trebuie
           utilizat in documentul de ie<?>ire (de obicei util pentru a inlocui
           setul de caractere detectat in documentul de intrare, in cazul in
           care acesta a fost gasit).

           Aceasta va utiliza setul de caractere de ie<?>ire specificat in
           linia de comanda. Daca nu a fost specificat, va utiliza setul de
           caractere al PO de intrare, iar daca PO de intrare are valoarea
           implicita ,,CHARSET", va returna setul de caractere al documentului
           de intrare, astfel incat sa nu fie efectuata nicio codificare.

PERSPECTIVE
       Un neajuns al TransTractor-ului actual este ca nu poate gestiona
       documente traduse care con<?>in toate limbile, cum ar fi <?>abloanele
       ,,debconf" sau fi<?>ierele ,,.desktop".

       Pentru a aborda aceasta problema, singurele modificari de interfa<?>a
       necesare sunt:

       - luarea unui tabel de elemente asociate ca po_in_name (o lista pentru
         fiecare limba)

       - adaugarea unui argument la traducere pentru a indica limba <?>inta

       - crearea unei func<?>ii pushline_all*(, care ar face ,,pushline" din
         con<?>inutul sau pentru toate limbile, folosind o sintaxa de tip
         harta:

             $self->pushline_all({ "Description[".$langcode."]=".
                                   $self->translate($line,$ref,$langcode)
                                 });

       Vom vedea daca este suficient ;)

AUTORI
        Denis Barbier <barbier@linuxfr.org>
        Martin Quinson (mquinson#debian.org)
        Jordi Vilalta <jvprat@gmail.com>

perl v5.42.0                      2025-11-22 LOCALE::PO4A::TRANSTRACTOR.3PM(1)