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

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, întreținerea traducerilor) folosind instrumente gettext în domenii în care nu erau așteptate, cum ar fi documentația.

Această clasă este strămoșul fiecărui analizator po4a utilizat pentru a analiza un document, pentru a căuta șiruri traductibile, pentru a le extrage într-un fișier PO și pentru a le înlocui cu traducerea lor în documentul de ieșire.

Mai formal, acesta primește următoarele argumente ca intrare:

-   un document de tradus;

-   un fișier PO care conține traducerile care urmează să fie utilizate.

Ca ieșire, produce:

-   un alt fișier PO, care rezultă din extragerea șirurilor traductibile din documentul de intrare;

-   un document tradus, cu aceeași structură ca cel de la intrare, dar cu toate șirurile traductibile înlocuite cu traducerile găsite în fișierul PO furnizat la intrare.

Iată o reprezentare grafică a acestui lucru:

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

FUNCȚII PE CARE ANALIZATORUL TREBUIE SĂ LE SUPRASCRIE

parse()
    Aici are loc toată munca: analizarea documentelor de intrare, generarea rezultatelor și extragerea șirurilor traductibile. Acest lucru este destul de simplu folosind funcțiile furnizate prezentate în secțiunea FUNCȚII INTERNE de mai jos. Consultați și secțiunea SINOPSIS, care prezintă un exemplu.

    Această funcție este apelată de funcția process() de mai jos, dar dacă alegeți să utilizați funcția new() și să adăugați manual conținut documentului, va trebui să apelați această funcție.

docheader()
    Această funcție returnează antetul pe care ar trebui să îl adăugăm documentului produs, citat corespunzător pentru a fi un comentariu în limba țintă. Consultați secțiunea Educarea dezvoltatorilor cu privire la traduceri, din po4a(7), pentru a afla la ce este bună această funcție.

SINOPSIS
Următorul exemplu analizează o listă de paragrafe care încep cu „<p>”. De dragul simplității, presupunem că documentul este bine formatat, adică că etichetele „<p>” sunt singurele etichete prezente și că această etichetă se află chiar la începutul fiecărui 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 dată când vedem <p>.
               # Repuneți linia curentă în intrare,
               # și puneți paragraful construit la ieșire.
               $self->unshiftline($line,$lref);

               # Acum că documentul este format, traduceți-l:
               #   - Eliminați eticheta de început
               $paragraph =~ s/^<p>//s;

               #   - Introduceți pentru a afișa eticheta de început (netradusă)
               #     ș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 definită? Sfârșitul fișierului de intrare.
       return;
   }
 }

Odată ce ați implementat funcția de analizare, puteți utiliza clasa dvs. de documente, folosind interfața publică prezentată în secțiunea următoare.

INTERFAȚA PUBLICĂ pentru scripturile care utilizează analizatorul dvs.

  Constructor

process(%)
    Această funcție poate face tot ce aveți nevoie să faceți cu un document po4a într-o singură invocare. Argumentele sale trebuie să fie împachetate ca o serie de elemente asociative. ACȚIUNI:

    a.  Citește toate fișierele PO specificate în po_in_name

    b.  Citește toate documentele originale specificate în file_in_name

    c.  Analizează documentul

    d.  Citește și aplică toate actele adiționale (addendele) specificate

    e.  Scrie documentul tradus la file_out_name (dacă este dat)

    f.  Scrie fișierul PO extras la po_out_name (dacă este dat)

    ARGUMENTE, în afară de cele acceptate de new() (cu tipul așteptat):

    file_in_name (@)
        Lista de nume de fișiere din care trebuie să citim documentul de intrare.

    file_in_charset ($)
        Setul de caractere utilizat în documentul de intrare (dacă nu este specificat, se utilizează UTF-8).

    file_out_name ($)
        Numele fișierului în care trebuie să scriem documentul de ieșire.

    file_out_charset ($)
        Setul de caractere utilizat în documentul de ieșire (dacă nu este specificat, se utilizează 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 utilizată pentru a traduce documentul.

    po_out_name ($)
        Numele fișierului în care trebuie să 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 să citim addenda.

    addendum_charset ($)
        Setul de caractere pentru addendă.

new(%)
    Creează un nou document po4a. Opțiuni acceptate (în seria de elemente asociative trecută ca parametru):

    verbose ($)
        Stabilește nivelul de detaliere al informațiilor.

    debug ($)
        Definește depanarea.

    wrapcol ($)
        Coloana la care ar trebui să încadrăm textul în documentul de ieșire (implicit: 76).

        Valoarea negativă înseamnă să nu se încadreze liniile deloc (fără întreruperi de linie).

    De asemenea, acceptă următoarele 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($$$)
    Adaugă un alt document de intrare de date la sfârșitul matricei existente "@{$self->{TT}{doc_in}}".

    Această funcție are două argumente obligatorii și unul opțional.
     * Numele fișierului care urmează să fie citit pe disc;
     * Numele care trebuie utilizat ca nume de fișier la construirea referinței în fișierul PO;
     * Setul de caractere care trebuie utilizat pentru a citi fișierul respectiv (UTF-8 în mod implicit)

    Această 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ță” ("linenum" începe cu 1).

    Vă rugăm să rețineți că aceasta nu analizează nimic. Ar trebui să utilizați funcția parse() atunci când ați terminat cu împachetarea fișierelor de intrare în document.

write($)
    Scrie documentul tradus în 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 în matrice.

  Manipularea fișierelor PO

readpo($)
    Adaugă conținutul unui fișier (al cărui 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()
    Returnează câteva statistici despre traducerea efectuată până în prezent. Vă rugăm să rețineți că nu sunt aceleași statistici ca cele afișate de «msgfmt --statistic». Aici, este vorba de statistici despre utilizarea recentă a fișierului PO, în timp ce «msgfmt» raportează starea fișierului. Este o funcție de învăluire pentru funcția Locale::Po4a::Po::stats_get aplicată la fișierul PO de intrare. Exemplu de utilizare:

        [utilizarea normală a documentului po4a...]

        ($percent,$hit,$queries) = $document->stats();
        print "Am găsit traduceri pentru $percent\% ($hit din $queries) de șiruri.\n";

  Manipularea addendelor

addendum($)
    Vă rugăm să consultați po4a(7) pentru mai multe informații despre ce sunt addendele și cum ar trebui să le scrie traducătorii. Pentru a aplica un addendum documentului tradus, pur și simplu treceți numele său de fișier la această funcție și ați terminat ;)

    Această funcție returnează un număr întreg nenul în caz de eroare.

FUNCȚII INTERNE utilizate pentru scrierea analizatorilor derivativi

  Obținerea intrărilor, furnizarea ieșirilor
Sunt furnizate patru funcții pentru a obține intrare și a returna ieșire. Acestea sunt foarte asemănătoare cu shift/unshift și push/pop din Perl.

 * Perl shift returnează primul element din matrice și îl elimină din matrice.
 * Perl unshift antepune un element în matrice ca primul element din matrice.
 * Perl pop returnează ultimul element al matricei și îl elimină din matrice.
 * Perl push adaugă un element în matrice ca ultim element al matricei.

Prima pereche este despre intrare, în timp ce a doua este despre ieșire. Mnemonic: la intrare, sunteți interesat de prima linie, ceea ce oferă shift(), iar la ieșire doriți să adăugați rezultatul la sfârșit, așa cum face push().

shiftline()
    Această funcție returnează prima linie care urmează să fie analizată și referința corespunzătoare (împachetată ca o matrice) din matricea "@{$self->{TT}{doc_in}}" și elimină aceste prime două elemente ale matricei. Aici, referința este furnizată de un șir "$filename:$linenum".

unshiftline($$)
    Deplasează ultima linie deplasată a documentului de intrare și referința corespunzătoare înapoi la începutul "{$self->{TT}{doc_in}}".

pushline($)
    Introduce o linie nouă la sfârșitul "{$self->{TT}{doc_out}}".

popline()
    Extrage ultima linie introdusă de la sfârșitul "{$self->{TT}{doc_out}}".

  Marcarea șirurilor de caractere ca traductibile
O funcție este furnizată 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 în fișierul de intrare)

    -   Tipul acestui șir (adică descrierea textuală a rolului său structural; utilizat în Locale::Po4a::Po::gettextization(); vezi și po4a(7), secțiunea Gettextizarea: cum funcționează?)

    Această funcție poate primi și câteva argumente suplimentare. Acestea trebuie să fie organizate ca p serie de elemente asociative. De exemplu:

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

    wrap
        argument boolean care indică dacă putem considera că spațiile albe din șir nu sunt importante. Dacă da, funcția canonizează șirul de caractere înainte de a căuta o traducere sau de a-l extrage și include traducerea.

    wrapcol
        coloana la care trebuie să se încadreze (implicit: valoarea lui wrapcol specificată la crearea TransTractor sau 76).

        Valoarea negativă va fi sustrasă din valoarea implicită.

    comment
        un comentariu suplimentar pentru a adăuga la intrare.

    Acțiuni:

    -   Trimite șirul, referința și tipul în po_out.

    -   Returnează traducerea șirului de caractere (așa cum se găsește în po_in) astfel încât analizatorul să poată construi doc_out.

    -   Gestionează seturile de caractere pentru a recodifica șirurile înainte de a le trimite la po_out și înainte de a returna traducerile.

  Diverse funcții

verbose()
    Returnează dacă opțiunea „verbose” (de detaliere a informațiilor) a fost trecută în timpul creării TransTractor.

debug()
    Returnează dacă opțiunea „debug” (de depanare) a fost trecută în timpul creării TransTractor.

get_in_charset()
    Această funcție returnează setul de caractere care a fost furnizat ca set de caractere principal

get_out_charset()
    Această funcție va returna setul de caractere care trebuie utilizat în documentul de ieșire (de obicei util pentru a înlocui setul de caractere detectat în documentul de intrare, în cazul în care acesta a fost găsit).

    Aceasta va utiliza setul de caractere de ieșire specificat în linia de comandă. Dacă nu a fost specificat, va utiliza setul de caractere al PO de intrare, iar dacă PO de intrare are valoarea implicită „CHARSET”, va returna setul de caractere al documentului de intrare, astfel încât să nu fie efectuată nicio codificare.

PERSPECTIVE
Un neajuns al TransTractor-ului actual este că nu poate gestiona documente traduse care conțin toate limbile, cum ar fi șabloanele „debconf” sau fișierele „.desktop”.

Pentru a aborda această problemă, singurele modificări de interfață necesare sunt:

-   luarea unui tabel de elemente asociate ca po_in_name (o listă pentru fiecare limbă)

-   adăugarea unui argument la traducere pentru a indica limba țintă

-   crearea unei funcții pushline_all*(, care ar face „pushline” din conținutul său pentru toate limbile, folosind o sintaxă de tip hartă:

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

Vom vedea dacă este suficient ;)

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