NAZWA¶

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

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:

• dokument do przetłumaczenia;
• plik PO zawierający tłumaczenia do użycia.

Jako wynik dostajemy:

• inny plik PO, czego wynikiem jest wyciągnięcie komunikatów możliwych do przetłumaczenia z dokumentu wejściowego;
• 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.

Graficzna reprezentacja tego procesu:

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

FUNKCJE, KTÓRE TWÓJ PARSER POWINIEN NADPISAƶ

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 FUNKCJE WEWNĘTRZNE. Patrz także sekcja 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.

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ę Przekazywanie deweloperom wiedzy o tłumaczeniu w po4a(7).

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.

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

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

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

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

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ą:

• pobieranie hasha jak po_in_name (lista dla języka)
• dodawanie argumentu do przetłumaczenia, wskazując język docelowy
• 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)
                          });
      

Zobaczymy, czy to wystarczy ;)

AUTORZY¶

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

TŁUMACZENIE¶

 Robert Luberda <robert@debian.org>