Provided by: po4a_0.41-1_all bug

NAZWA

       Locale::Po4a::Po - modul manipulujcy plikami PO

SK/LADNIA

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

           # Czytanie pliku PO
           $pofile->read('plik.po');

           # Dodanie wpisu
           $pofile->push('msgid' => 'Hello', 'msgstr' => 'bonjour',
                         'flags' => "wrap", 'reference'=>'file.c:46');

           # Wycignicie tlumaczenia
           $pofile->gettext("Hello"); # zwraca 'bonjour'

           # Zapisanie z powrotem do pliku
           $pofile->write('inny_plik.po');

OPIS

       Locale::Po4a::Po jest modulem pozwalajcym manipulowa katalogami
       wiadomoci. Mona zaladowa i zapisa plik po (ktorego rozszerzeniem czsto
       jest po), mona zbudowa nowe wpisy w locie albo zada przetlumaczenia
       komunikatu.

       Bardziej calociowy opis katalogow wiadomoci w formacie PO i ich uycia
       mona znale w dokumentacji programu gettext.

       Ten modul jest czci projektu PO4A, ktorego celem jest uycie plikow PO
       (z zaloenia przeznaczonych do ulatwienia tlumaczenia komunikatow
       programu) do tlumaczenia wszystkiego, wlczajc dokumentacj (strony
       podrcznika man, strony info), opisy pakietow, szablony debconfa i
       wszystkiego, co moe korzysta z tego.

OPCJE AKCEPTOWANE PRZEZ MODU/L

       porefs
           Okrela format odnonika. Moe to by: none - nie dodaje adnych
           odnonikow, noline - nie dodaje numeru linii, full - dodaje
           kompletne odnoniki.

Funkcje ca/lego katalogu wiadomoci

       new()
           Tworzy nowy katalog wiadomoci. Jeli podano argument, jest on nazw
           pliku PO, ktory powinien by zaladowany.

       read($)
           Czyta plik PO (o nazwie podanej jako argument). Wczeniej istniejce
           wpisy nie s usuwane, a nowe wpisy s dodawane na kocu katalogu.

       write($)
           Zapisuje biecy katalog do podanego pliku.

       write_if_needed($$)
           Podobne do write, ale jeeli pliki PO lub POT ju istniej, to wynik
           zostanie zapisany do pliku tymczasowego, ktory bdzie porownany z
           istniejcym plikiem, aby sprawdzi, czy aktualizacja jest rzeczywicie
           potrzebna (pozwala to unikn zmieniania pliku POT tylko po to, by
           zaktualizowa odnoniki lub pole POT-Creation-Date).

       gettextize($$)
           Funkcja tworzy jeden katalog przetlumaczonych wiadomoci z dwoch
           katalogow - oryginalu i tlumaczenia. Proces tej jest opisany w
           sekcji Proces przekszta/lcania do formatu gettext: jak to dzia/la?
           podrcznika po4a(7).

       filter($)
           Funkcja wyodrbnia katalog wiadomoci z istniejcego katalogu. W pliku
           wynikowym bd umieszczone tylko te wpisy, do ktorych istnieje
           odniesienie w podanym pliku.

           Funkcja przetwarza swoje argumenty, generuje z nich definicj
           funkcji Perla, ewaluuje t definicj i filtruje pola, dla ktorych ta
           wygenerowana funkcja zwroci warto true.

           Czasami uwielbiam Perla ;)

       to_utf8()
           Zmienia kodowanie wpisow msgstr pliku PO do UTF-8. Nic nie robi,
           jeli w pliku PO nie jest podane kodowanie znakow (warto "CHARSET")
           albo gdy jest ono ustawione na UTF-8 lub ASCII.

Funkcje uywajce katalogu wiadomoci do t/lumacze

       gettext($%)
           da przetlumaczenia przez biecy katalog komunikatu podanego jako
           argument. Jeli nie znaleziono tlumaczenia, funkcja zwroci
           oryginalny (nieprzetlumaczony) komunikat.

           Po komunikacie do przetlumaczenia mona przekaza hasha z dodatkowymi
           argumentami. Poniej podano poprawne wpisy:

           wrap
               warto logiczna, okrelajca, czy biale znaki w tekcie maj
               znaczenie. Jeli tak, to funkcja kanonizuje tekst przed
               wyszukaniem tlumaczenia oraz zawija tekst wynikowy.

           wrapcol
               kolumna, w ktorej tekst powinien by zawijany (domylnie: 76).

       stats_get()
           Zwraca statystyki dotyczce stosunku trafie od ostatniego wywolania
           funkcji stats_clear(). Prosz zauway, e to nie s te same statystyki,
           ktore wypisuje msgfmt --statistic. Tutaj, statystyki dotycz biecego
           uycia pliku PO, a msgfmt podaje stan pliku. Przyklad uycia:

               [klika uy pliku PO do tlumaczenia rzeczy]

               ($percent,$hit,$queries) = $pofile->stats_get();
               print "Do tej pory znalelimy tlumaczenia $percent\% ($hit z $queries) komunikatow.\n";

       stats_clear()
           Czyci statystyki dotyczce trafienia gettexta.

Funkcje budujce katalog wiadomoci

       push(%)
           Dodaje nowy wpis na koniec biecego katalogu. Argumenty powinny by
           przekazane w hashu. Dostpne klucze:

           msgid
               lacuch znakow w oryginalnym jzyku.

           msgstr
               tlumaczenie.

           reference
               wskazanie, gdzie dany komunikat zostal znaleziony. Przyklad
               plik.c:46 (w linii 46 pliku "plik.c"). W razie wielokrotnych
               wystpie moe by to lista rozdzielona znakami spacji.

           comment
               komentarz dodany tutaj rcznie (przez tlumaczy). Format jest
               dowolny.

           automatic
               komentarz dodany automatycznie przez program wycigajcy
               komunikaty. Szczegoly w opisie opcji --add-comments programu
               xgettext.

           flags
               rozdzielona spacjami lista wszystkich zdefiniowanych flag dla
               tego wpisu.

               Poprawne flagi: 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.

               Ich znaczenie mona znale w dokumentacji pakietu gettext.

           type
               jest to w wikszoci argument wewntrzny uywany podczas
               przeksztalcania dokumentow do formatu gettext. Ide jest
               przetworzenie do obiektu PO zarowno oryginalu, jak i
               tlumaczenia, scalenie ich, uywajc msgid jednego jako msgstr
               drugiego i msgid drugiego jako msgstr pierwszego. Aby mie
               pewno, e wszystko jest OK, kady msgid w obiekcie ma przypisany
               typ, oparty na strukturze dokumentu (jak "chap", "sect1", "p" w
               formacie DocBook). Jeli typy komunikatow nie s takie same,
               oznacza to, e struktura obu plikow jest rona i proces koczy si
               bldem.

               Ta informacja jest zapisywana jako automatyczny komentarz w
               pliku PO, poniewa dostarcza tlumaczom kontekstu o komunikatach,
               ktore tlumacz.

           wrap
               warto logiczna, okrelajca, czy biale znaki mog by scalane. Jeli
               tak, komunikat przed uyciem bdzie ujednolicony.

               Ta informacja jest zapisywana do pliku PO z uyciem flagi wrap
               lub no-wrap.

           wrapcol
               kolumna, w ktorej tekst powinien by zawijany (domylnie: 76).

               Ta informacja nie jest zapisywana w pliku PO.

R'one funkcje

       count_entries()
           Zwraca liczb wpisow w katalogu (nie liczc naglowka).

       count_entries_doc()
           Zwraca liczb wpisow w dokumencie. Komunikaty pojawiajce si wiele
           razy w tym dokumencie bd policzone wiele razy.

       msgid($)
           Zwraca msgid o zadanym numerze.

       msgid_doc($)
           Zwraca msgid znajdujce si w dokumencie na podanej pozycji.

       get_charset()
           Zwraca kodowanie znakow okrelone w naglowku pliku PO. Jeli nie
           zostalo ustawione, to zwraca tekst "CHARSET".

       set_charset($)
           Ustawia kodowanie znakow naglowka pliku PO na warto okrelon przez
           pierwszy argument. Jeli ta funkcja nie zostanie nigdy wywolana (i
           nie bdzie przeczytany aden plik majcy podane kodowanie znakow),
           zostanie pozostawiona domylna warto, czyli "CHARSET". Ta warto nie
           zmienia zachowania modulu, jest uywana tylko do wypelnienia
           odpowiedniego pola naglowka; zostanie take zwrocona przez
           get_charset().

AUTORZY

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