
        *****************************************************
        *           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 NAZWA

Locale::Po4a::TransTractor - ogólny moduł wyodrębniania tłumaczeń.

=head1 OPIS

Celem projektu po4a ("PO for anything") jest ułatwienie tłumaczeń (oraz, co ciekawsze, zarządzania tłumaczeniami) przy użyciu narzędzi gettext w tych obszarach, gdzie nie były używane, jak na przykład w obszarze dokumentacji.

Ta klasa jest przodkiem wszystkich parserów po4a używanych do przetwarzania dokumentu w poszukiwaniu komunikatów do przetłumaczenia, wyodrębniania ich do pliku PO oraz zastępowania ich tłumaczeniami w wyjściowym dokumencie.

Bardziej formalnie mówiąc, przyjmuje następujące argumenty jako wejście:

=over 2

=item -

dokument do przetłumaczenia;

=item -

plik PO zawierający tłumaczenia do użycia.

=back

Jako wynik dostajemy:

=over 2

=item -

inny plik PO, czego wynikiem jest wyciągnięcie komunikatów możliwych do przetłumaczenia z dokumentu wejściowego;

=item -

przetłumaczony dokument o takiej samej strukturze, co dokument wejściowy, ale ze wszystkimi komunikatami możliwymi do przetłumaczenia zamienionymi na tłumaczenia znalezione w wejściowym pliku PO.

=back

Graficzna reprezentacja tego procesu:

   Dokument wejściowy --\                          /--> Dokument wyjściowy
                         \                        /     (przetłumaczony)
                          +-> funkcja parse() ---+
                         /                        \
   Wejściowy PO --------/                          \--> Wyjściowy PO
                                                        (wyodrębniony)

=head1 FUNKCJE, KTÓRE TWÓJ PARSER POWINIEN NADPISAĆ

=over 4

=item parse()

Jest to miejsce, gdzie odbywa się cała praca: parsowanie dokumentów wejściowych, generowanie wyjścia, wyodrębnianie komunikatów do przetłumaczenia. Jest to bardzo proste, jeśli użyje się funkcji opisanych poniżej, w sekcji B<FUNKCJE WEWNĘTRZNE>. Patrz także sekcja B<SKŁADNIA>, zawierająca przykład.

Ta funkcja jest wywoływana przez poniższą funkcję proces(), ale jeżeli wybierze się użycie funkcji new() i ręczenie się doda zawartość do dokumentu, trzeba będzie wywołać tę funkcję samemu.

=item docheader()

Funkcja zwraca nagłówek, który powinien zostać dodany do wygenerowanego dokumentu, odpowiednio przygotowany, tak żeby mógł być komentarzem w języku docelowym. Aby dowiedzieć się, do czego to służy, proszę przeczytać sekcję B<Przekazywanie deweloperom wiedzy o tłumaczeniu> w L<po4a(7)|po4a.7>.

=back

=head1 SKŁADNIA

Następujący przykład przetwarza listę akapitów rozpoczynających się od "<p>". Dla uproszczenia, zakładamy, że dokument jest dobrze sformatowany, tj. występują tylko elementy "<p>" i są one umieszczone na samym początku każdego akapitu.

 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--; ) {
               # Nie po raz pierwszy widzimy <p>.
               # Włóż z powrotem bieżącą linię do wejścia,
               #  i dodaj zbudowany akapit do wyjścia
               $self->unshiftline($line,$lref);

               # Teraz, gdy dokument jest sformatowany, przetłumaczmy go:
               #   - Usunięcie początkowych tagów
               $paragraph =~ s/^<p>//s;

               #   - push to output the leading tag (untranslated) and the
               #     rest of the paragraph (translated)
               $self->pushline(  "<p>"
                               . $self->translate($paragraph,$pararef)
                               );

               next PARAGRAPH;
           } else {
               # Dodanie do akapitu
               $paragraph .= $line;
               $pararef = $lref unless(length($pararef));
           }

           # Ponowna inicjacja pętli
           ($line,$lref)=$self->shiftline();
       }
       # Nie dostaliśmy zdefiniowanej linii? Koniec pliku wejściowego.
       return;
   }
 }

Po zaimplementowaniu funkcji parsującej, można użyć własnych klas dokumentu, używając publicznego interfejsu zaprezentowanego w następnym rozdziale.

=head1 INTERFEJS PUBLICZNY dla skryptów używających Twojego parsera

=head2 Konstruktor

=over 4

=item process(%)

Funkcja zrobi  w jednym uruchomieniu wszystko, co tylko trzeba zrobić z dokumentem po4a. Jej argumenty muszą być umieszczone w hashu. AKCJE:

=over 3

=item a.

Czyta wszystkie pliki określone w po_in_name

=item b.

Czyta wszystkie oryginalne dokumenty określone w file_in_name

=item c.

Przetwarza (parsuje) dokument

=item d.

Dodaje i stosuje wszystkie podane załączniki

=item e.

Zapisuje przetłumaczony dokument do file_out_name (jeśli podano)

=item f.

Zapisuje wygenerowany plik PO do po_out_name (jeśli podano)

=back

ARGUMENTY, poza tymi akceptowanymi przez new() (z oczekiwanym typem):

=over 4

=item file_in_name (@)

Lista nazw plików, z których powinniśmy odczytać plik wejściowy.

=item file_in_charset ($)

Kodowanie znaków dokumentu wejściowego (jeśli nie podano, nastąpi próba określenia kodowania z dokumentu wejściowego).

=item file_out_name ($)

Nazwa pliku, do którego należy zapisać wynikowy dokument.

=item file_out_charset ($)

Kodowanie znaków wyjściowego dokumentu (jeśli nie podano, będzie użyte kodowanie znaków pliku PO).

=item po_in_name (@)

Lista nazw plików, z których powinniśmy odczytać wejściowe pliki PO zawierające tłumaczenia, które będą użyte podczas tłumaczenia dokumentu.

=item po_out_name ($)

Nazwa pliku, do którego powinien być zapisany wynikowy plik PO, zawierający komunikaty wyciągnięte z dokumentu wejściowego.

=item addendum (@)

Lista nazw plików, z których powinniśmy odczytać pliki załączników.

=item addendum_charset ($)

Kodowanie znaków załączników.

=back

=item new(%)

Create a new po4a document. Accepted options (in the hash passed as a parameter):

=over 4

=item verbose ($)

Ustawia gadatliwość.

=item debug ($)

Ustawia debugowanie.

=back

=back

=head2 Manipulowanie plikami z dokumentacją

=over 4

=item read($$)

Add another input document data at the end of the existing array C<< @{$self->{TT}{doc_in}} >>. The argument is the filename to read. If a second argument is provided, it is the filename to use in the references.

This array C<< @{$self->{TT}{doc_in}} >> holds this input document data as an
array of strings with alternating meanings.
 * The string C<$textline> holding each line of the input text data.
 * The string C<< $filename:$linenum >> holding its location and called as
   "reference" (C<linenum> starts with 1).

Proszę zauważyć, że to niczego nie przetwarza. Należy użyć funkcji parse() po zakończeniu pakowania plików wejściowych do dokumentu.

=item write($)

Zapisuje przetłumaczony dokument do pliku o podanej nazwie.

This translated document data are provided by:
 * C<< $self->docheader() >> holding the header text for the plugin, and
 * C<< @{$self->{TT}{doc_out}} >> holding each line of the main translated text in the array.

=back

=head2 Manipulowanie plikami PO

=over 4

=item readpo($)

Dodaje zawartość pliku (którego nazwa jest podawana w argumencie) do istniejącego pliku wejściowego PO. Stara zawartość nie jest tracona.

=item writepo($)

Zapisuje wygenerowany plik PO do pliku o podanej nazwie.

=item stats()

Zwraca statystyki dotyczące tłumaczeń. Proszę zauważyć, że nie są to te same statystyki, które wypisuje msgfmt --statistic. Tutaj są to statystyki o obecnym wykorzystaniu pliku PO, podczas gdy msgfmt wyświetla status tego pliku. Funkcja jest opakowaniem funkcji Locale::Po4a::Po::stats_get zastosowanej do wejściowego pliku PO. Przykład użycia:

    [zwykłe użycie dokumentu po4a ...]

    ($percent,$hit,$queries) = $document->stats();
    print "Znaleźliśmy tłumaczenia $percent\% ($hit z $queries) komunikatów.\n";

=back

=head2 Manipulowanie załącznikami

=over 4

=item addendum($)

Więcej informacji o tym, czym są załączniki, i jak tłumacze powinni je pisać, można znaleźć w L<po4a(7)|po4a.7>. Aby dodać załącznik do przetłumaczonego dokumentu, wystarczy po prostu tej funkcji przekazać nazwę pliku, w którym się znajduje, i gotowe ;)

Funkcja zwraca liczbę nie będącą nullem lub błąd.

=back

=head1 FUNKCJE WEWNĘTRZNE, używane do pisania parserów

=head2 Pobieranie wejścia, dostarczanie wyjścia

Dostarczone są cztery funkcje pobierania wejścia i zwracania wyjścia. Są one bardzo podobne do shift/unshift i push/pop w Perlu.

 * Perl shift returns the first array item and drop it from the array.
 * Perl unshift prepends an item to the array as the first array item.
 * Perl pop returns the last array item and drop it from the array.
 * Perl push appends an item to the array as the last array item.

Pierwsza para dotyczy wejścia, a druga - wyjścia. Mnemonik: w wejściu interesuje Cię pierwsza linia, co daje shift, a w wyjściu chcesz dostać wynik na końcu, tak jak do robi push.

=over 4

=item shiftline()

This function returns the first line to be parsed and its corresponding reference (packed as an array) from the array C<< @{$self->{TT}{doc_in}} >> and drop these first 2 array items.  Here, the reference is provided by a string C<< $filename:$linenum >>.

=item unshiftline($$)

Unshifts the last shifted line of the input document and its corresponding reference back to the head of C<< {$self->{TT}{doc_in}} >>.

=item pushline($)

Push a new line to the end of C<< {$self->{TT}{doc_out}} >>.

=item popline()

Pop the last pushed line from the end of C<< {$self->{TT}{doc_out}} >>.

=back

=head2 Zaznaczanie łańcuchów znaków jako możliwych do przetłumaczenia

Dostarczona jest jedna funkcja obsługująca tekst, który powinien być przetłumaczony.

=over 4

=item translate($$$)

Argumenty obowiązkowe:

=over 2

=item -

Łańcuch znaków do przetłumaczenia

=item -

Odnośnik tego komunikatu (tj. pozycja w pliku wejściowym)

=item -

Typ tego komunikatu (tj. tekstowy opis jego roli w strukturze; używany w Locale::Po4a::Po::gettextization(); patrz także L<po4a(7)|po4a.7>, sekcja B<Proces przekształcania do formatu gettext: jak to działa?>)

=back

Funkcja przyjmuje także kilka dodatkowych argumentów. Muszą być zorganizowane jako hash. Na przykład:

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

=over 

=item B<wrap>

flaga logiczna określająca, czy traktujemy białe znaki w komunikacie jako nieistotne. Jeśli tak, to funkcja przed wyszukaniem lub wyciągnięciem tłumaczenia kanonizuje komunikat, a następnie zawija tekst tłumaczenia.

=item B<wrapcol>

kolumna, w której tekst powinien być zawijany (domyślnie: 76).

=item B<comment>

dodatkowy komentarz do dodania do wpisu.

=back

Akcje:

=over 2

=item -

Dodaje nowy komunikat, odnośnik i typ do po_out.

=item -

Zwraca tłumaczenie tekstu (znalezione w po_in), tak że parser może zbudować doc_out.

=item -

Obsługuje kodowania znaków, aby zmienić kodowanie komunikatów przed wysłaniem do po_out i przed zwróceniem tłumaczeń.

=back

=back

=head2 Różne funkcje

=over 4

=item verbose()

Zwraca informację, czy podczas uruchomienia TransTractora, podano opcję verbose.

=item debug()

Zwraca informację, czy podczas uruchomienia TransTractora podano opcję debug.

=item detected_charset($)

Mówi TransTractorowi, że w dokumencie źródłowym wykryto nowe kodowanie znaków (podane jako pierwszy argument wywołania). Zwykle kodowanie może być odczytane z nagłówka dokumentu. Pozostawione będzie tylko pierwsze kodowanie znaków, pochodzące albo z argumentów funkcji process(), albo z dokumentu.

=item get_out_charset()

Funkcja zwraca kodowanie znaków, które powinno być użyte w dokumencie wyjściowym (zazwyczaj użyteczne do zamienienia wykrytego kodowania znaków dokumentu wejściowego, tam gdzie został znaleziony).

Użyje wyjściowego kodowania znaków podanego w linii poleceń. Jeśli go nie podano, użyje kodowania znaków wejściowego pliku PO, a jeżeli jako to kodowanie w pliku był ustawiony domyślny tekst "CHARSET", to zwróci kodowanie znaków wejściowego dokumentu, tak że nie zostanie przeprowadzona żadna konwersja kodowań.

=item recode_skipped_text($)

Funkcja zwraca tekst przekazany jako argument przekodowany z kodowania znaków dokumentu wejściowego na kodowanie znaków dokumentu wyjściowego. Nie jest to potrzebne podczas tłumaczenia komunikatu (translate() wszystko przekodowuje samodzielnie), ale wtedy, gdy pominięto komunikat z dokumentu wejściowego, a dokument wyjściowy powinien mieć spójne kodowanie znaków.

=back

=head1 DALSZE WSKAZÓWKI

Mankamentem obecnego TransTractora jest brak obsługi dokumentów zawierających wszystkie języki naraz, jak na przykład szablony debconf lub pliki .desktop.

Aby rozwiązać ten problem, jedynymi potrzebnymi zmianami w interfejsie są:

=over 2

=item -

pobieranie hasha jak po_in_name (lista dla języka)

=item -

dodawanie argumentu do przetłumaczenia, wskazując język docelowy

=item -

make a pushline_all function, which would make pushline of its content for all languages, using a map-like syntax:

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

=back

Zobaczymy, czy to wystarczy ;)

=head1 AUTORZY

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


=head1 TŁUMACZENIE

 Robert Luberda <robert@debian.org>

