
        *****************************************************
        *           GENERATED FILE, DO NOT EDIT             *
        * THIS IS NO SOURCE FILE, BUT RESULT OF COMPILATION *
        *****************************************************

This file was generated by po4a(7). Do not store it (in VCS, for example),
but store the PO file used as source file by po4a-translate.

In fact, consider this as a binary, and the PO file as a regular .c file:
If the PO get lost, keeping this translation up-to-date will be harder.

=encoding UTF-8

=head1 NUME

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

=head1 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:

=over 2

=item -

un document de tradus;

=item -

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

=back

Ca ieșire, produce:

=over 2

=item -

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

=item -

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.

=back

Iată o reprezentare grafică a acestui lucru:

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

=head1 FUNCȚII PE CARE ANALIZATORUL TREBUIE SĂ LE SUPRASCRIE

=over 4

=item 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 B<FUNCȚII
INTERNE> de mai jos. Consultați și secțiunea B<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.

=item 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 B<Educarea dezvoltatorilor cu privire la
traduceri>, din L<po4a(7)|po4a.7>, pentru a afla la ce este bună această
funcție.

=back

=head1 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.

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

=head2 Constructor

=over 4

=item 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:

=over 3

=item a.

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

=item b.

Citește toate documentele originale specificate în file_in_name

=item c.

Analizează documentul

=item d.

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

=item e.

Scrie documentul tradus la file_out_name (dacă este dat)

=item f.

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

=back

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

=over 4

=item file_in_name (@)

Lista de nume de fișiere din care trebuie să citim documentul de intrare.

=item file_in_charset ($)

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

=item file_out_name ($)

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

=item file_out_charset ($)

Setul de caractere utilizat în documentul de ieșire (dacă nu este
specificat, se utilizează UTF-8).

=item 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.

=item 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.

=item addendum (@)

Lista de nume de fișiere din care trebuie să citim addenda.

=item addendum_charset ($)

Setul de caractere pentru addendă.

=back

=item new(%)

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

=over 4

=item verbose ($)

Stabilește nivelul de detaliere al informațiilor.

=item debug ($)

Definește depanarea.

=item 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).

=back

De asemenea, acceptă următoarele opțiuni pentru fișierele Po subiacente:
B<porefs>, B<copyright-holder>, B<msgid-bugs-address>, B<package-name>,
B<package-version>, B<wrap-po>.

=back

=head2 Manipularea fișierelor de documente

=over 4

=item read($$$)

Adaugă un alt document de intrare de date la sfârșitul matricei existente
C<< @{$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 C<< @{$self->{TT}{doc_in}} >> conține datele acestui document de intrare
 ca o matrice de șiruri de caractere cu semnificații alternante.
 * Șirul C<$textline> conține fiecare linie a datelor text de intrare.
 * Șirul C<< $filename:$linenum >> conține locația acestuia și se numește
   „referință” (C<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.

=item write($)

Scrie documentul tradus în fișierul specificat.

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

=back

=head2 Manipularea fișierelor PO

=over 4

=item 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.

=item writepo($)

Scrie fișierul PO extras la numele de fișier dat.

=item 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";

=back

=head2 Manipularea addendelor

=over 4

=item addendum($)

Vă rugăm să consultați L<po4a(7)|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.

=back

=head1 FUNCȚII INTERNE utilizate pentru scrierea analizatorilor derivativi

=head2 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().

=over 4

=item shiftline()

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

=item unshiftline($$)

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

=item pushline($)

Introduce o linie nouă la sfârșitul C<< {$self->{TT}{doc_out}} >>.

=item popline()

Extrage ultima linie introdusă de la sfârșitul C<< {$self->{TT}{doc_out}}
>>.

=back

=head2 Marcarea șirurilor de caractere ca traductibile

O funcție este furnizată pentru a gestiona textul care trebuie tradus.

=over 4

=item translate($$$)

Argumente obligatorii:

=over 2

=item -

Un șir de caractere de tradus

=item -

Referința acestui șir de caractere (de exemplu, poziția în fișierul de
intrare)

=item -

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

=back

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);

=over

=item B<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.

=item B<wrapcol>

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

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

=item B<comment>

un comentariu suplimentar pentru a adăuga la intrare.

=back

Acțiuni:

=over 2

=item -

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

=item -

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

=item -

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

=back

=back

=head2 Diverse funcții

=over 4

=item verbose()

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

=item debug()

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

=item get_in_charset()

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

=item 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.

=back

=head1 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:

=over 2

=item -

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

=item -

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

=item -

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)
                        });

=back

Vom vedea dacă este suficient ;)

=head1 AUTORI

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