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

NUME
Locale::Po4a::Po - modul de manipulare a fișierelor PO

SINOPSIS
    use Locale::Po4a::Po;
    my $pofile=Locale::Po4a::Po->new();

    # Citește fișierul PO
    $pofile->read('fișier.po');

    # Adaugă o intrare
    $pofile->push('msgid' => 'Hello', 'msgstr' => 'Salut',
                  'flags' => "wrap", 'reference'=>'file.c:46');

    # Extrage o traducere
    $pofile->gettext("Hello"); # returnează 'Salut'

    # Scrie înapoi într-un fișier
    $pofile->write('alt-fișier.po');

DESCRIERE
Locale::Po4a::Po este un modul care vă permite să manipulați cataloagele de mesaje. Puteți încărca și scrie din/într-un fișier (a cărui extensie este adesea po), puteți construi noi intrări din mers sau solicita traducerea unui șir de caractere.

Pentru o descriere mai completă a cataloagelor de mesaje în format PO și a utilizării acestora, consultați documentația info a programului gettext (nodul „`PO Files”').

Acest modul face parte din proiectul po4a, al cărui obiectiv este de a utiliza fișierele PO (concepute la origine pentru a facilita traducerea mesajelor de program) pentru a traduce totul, inclusiv documentația (pagina man, manualul info), descrierea pachetului, șabloanele debconf și tot ceea ce se poate beneficia de acest lucru.

OPȚIUNI ACCEPTATE DE ACEST MODUL

--porefs tip
    Specifică formatul referinței. Argumentul tip poate fi unul dintre never pentru a nu produce nicio referință, file pentru a specifica doar fișierul fără numărul de linie, counter pentru a înlocui numărul de linie cu un contor crescător și full pentru a include referințe complete (implicit: full).

--wrap-po no|newlines|număr (implicit: 76)
    Specifică modul în care liniile din fișierul po ar trebui să fie încadrate. Acest lucru oferă posibilitatea de a alege între fișiere care sunt bine ajustate ca încadrare, dar ar putea duce la conflicte git, sau fișiere care sunt mai ușor de gestionat automat, dar mai greu de citit pentru oameni.

    Din punct de vedere istoric, suita gettext a reformatat fișierele po la a 77-a coloană pentru cosmetică. Această opțiune specifică comportamentul lui po4a. Dacă este definită la o valoare numerică, po4a va împacheta fișierul po după această coloană și după noile linii din conținut. Dacă este definită la newlines, po4a va împărți doar msgid și msgstr după linii noi din conținut. Dacă este definită la no, po4a nu va încadra deloc fișierul po. Comentariile de referință sunt întotdeauna încadrate de instrumentele gettext pe care le folosim intern.

    Rețineți că această opțiune nu are niciun impact asupra modului în care msgid și msgstr sunt încadrate, adică asupra modului în care sunt adăugate linii noi la conținutul acestor șiruri.

--msgid-bugs-address adresă@poștă.electronică
    Definește adresa de raportare pentru erori din msgid. În mod implicit, fișierele POT create nu au câmpuri Report-Msgid-Bugs-To.

--copyright-holder șir
    Definește deținătorul drepturilor de autor în antetul POT. Valoarea implicită este „Free Software Foundation, Inc.”

--package-name șir
    Definește numele pachetului pentru antetul POT. Valoarea implicită este „PACKAGE”.

--package-version șir
    Definește versiunea pachetului pentru antetul POT. Valoarea implicită este „VERSION”.

Funcții privind cataloage întregi de mesaje

new()
    Creează un nou catalog de mesaje. Dacă este furnizat un argument, acesta este numele unui fișier PO pe care ar trebui să îl încărcăm.

read($)
    Citește un fișier PO (al cărui nume este dat ca argument). Intrările existente anterior în acesta nu sunt eliminate, cele noi sunt adăugate la sfârșitul catalogului.

write($)
    Scrie catalogul curent în fișierul dat.

write_if_needed($$)
    Precum „write($)”, dar dacă fișierul PO sau POT există deja, obiectul va fi scris într-un fișier temporar care va fi comparat cu fișierul existent pentru a verifica dacă actualizarea este necesară (astfel se evită modificarea unui POT doar pentru a actualiza o referință de linie sau câmpul POT-Creation-Date).

filter($)
    Această funcție extrage un catalog dintr-unul existent. Doar intrările care au o referință în fișierul dat vor fi plasate în catalogul rezultat.

    Această funcție analizează argumentul său, îl convertește într-o definiție de funcție Perl, verifică această definiție și filtrează câmpurile pentru care această funcție returnează „true”.

    Iubesc Perl uneori ;)

Funcții pentru utilizarea unui catalog de mesaje pentru traduceri

gettext($%)
    Solicită traducerea șirului de caractere dat ca argument în catalogul curent. Funcția returnează șirul original (netradus) dacă șirul nu a fost găsit.

    După șirul de caractere de tradus, puteți trece o serie de argumente suplimentare. Iată intrările valide:

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

    wrapcol
        coloana la care ar trebui să se facă încadrarea (implicit: 76).

stats_get()
    Returnează statistici despre rata de succes a gettext de la ultima dată când a fost apelat stats_clear(). Vă rugăm să rețineți că nu este vorba de 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. Exemplu de utilizare:

        [unele utilizări ale fișierului PO pentru a traduce lucruri]

        ($percent,$hit,$queries) = $pofile->stats_get();
        print "Până acum, am găsit traduceri pentru $percent\% ($hit din $queries) de șiruri.\n";

stats_clear()
    Șterge statisticile privind rezultatele (găsirile de șiruri) gettext.

Funcții pentru a construi un catalog de mesaje

push(%)
    Introduce o nouă intrare la sfârșitul catalogului curent. Argumentele trebuie să formeze un tabel de elemente asociative. Cheile valide sunt:

    msgid
        șirul de caractere în limba originală.

    msgstr
        traducerea.

    reference
        o indicație a locului în care a fost găsit acest șir de caractere. Exemplu: file.c:46 (adică în „file.c” la linia 46). Poate fi o listă separată prin spații în cazul ocurențelor multiple.

    comment
        un comentariu adăugat aici manual (de către traducători). Formatul acestuia este liber.

    automatic
        un comentariu care a fost adăugat automat de programul de extragere a șirurilor de caractere. Consultați opțiunea --add-comments a programului xgettext pentru mai multe informații.

    flags
        listă separată prin spații a tuturor fanioanelor definite pentru această intrare.

        Fanioanele valide sunt: c-text, python-text, lisp-text, elisp-text, librep-text, smalltalk-text, java-text, awk-text, object-pascal-text, ycp-text, tcl-text, wrap, no-wrap și fuzzy.

        Consultați documentația gettext pentru semnificația acestora.

    type
        acesta este în principal un argument intern: este utilizat în timpul gettextizării documentelor. Ideea aici este de a analiza atât originalul, cât și traducerea într-un obiect PO și de a le uni, folosind msgid-ul unuia ca msgid și msgid-ul celuilalt ca msgstr. Pentru a ne asigura că lucrurile merg bine, fiecărui msgid din obiectele PO i se atribuie un tip, bazat pe structura lor (precum „chapt”, „sect1”, „p” și așa mai departe în DocBook). Dacă tipurile de șiruri de caractere nu sunt identice, înseamnă că ambele fișiere nu au aceeași structură, iar procesul raportează o eroare.

        Aceste informații sunt scrise ca un comentariu automat în fișierul PO, deoarece oferă traducătorilor un anumit context cu privire la șirurile de caractere de tradus.

    wrap
        boolean care indică dacă spațiile albe pot fi manipulate în reformatările cosmetice. Dacă este adevărat, șirul este canonizat înainte de utilizare.

        Aceste informații sunt scrise în fișierul PO cu ajutorul fanionului wrap sau no-wrap.

    wrapcol
        ignorat; cheia este păstrată pentru compatibilitatea cu versiunile anterioare.

Funcții diverse

count_entries()
    Returnează numărul de intrări din catalog (fără antet).

count_entries_doc()
    Returnează numărul de intrări din document. Dacă un șir de caractere apare de mai multe ori în document, acesta va fi numărat de mai multe ori.

msgid($)
    Returnează msgid-ul numărului dat.

msgid_doc($)
    Returnează msgid-ul cu poziția dată în document.

type_doc($)
    Returnează tipul msgidului cu poziția dată în document. Acest lucru este probabil util doar pentru gettextizare și este stocat separat de {$msgid}{'type'} deoarece locația ulterioară poate fi suprascrisă de un alt tip atunci când $msgid este duplicat în documentul principal.

get_charset()
    Returnează setul de caractere specificat în antetul PO. Dacă nu a fost definit, se va returna „UTF-8”.

AUTORI
 Denis Barbier <barbier@linuxfr.org>
 Martin Quinson (mquinson#debian.org)