NAZWA¶

OPIS¶

-

dokument do przetłumaczenia;

-

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

-

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.

   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¶

 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;
               #   - dodanie do wyjścia początkowego elementu (nieprzetłumaczonego)
               #     i reszty akapitu (przetłumaczonej)
               $self->pushline(  "<p>"
                               . $document->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;
   }
 }

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

Konstruktor¶

process(%)

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

new(%)

Tworzy nowy dokument po4a. Akceptowane opcje (będące w hashu):

Manipulowanie plikami z dokumentacją¶

read($)

Dodaje kolejny dokument wejściowy na koniec istniejącego dokumentu. Argumentem jest nazwa pliku do odczytania.

 

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

write($)

Zapisuje przetłumaczony dokument do pliku o podanej nazwie.

Manipulowanie plikami PO¶

readpo($)

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

writepo($)

Zapisuje wygenerowany plik PO do pliku o podanej nazwie.

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

Manipulowanie załącznikami¶

addendum($)

Więcej informacji o tym, czym są załączniki, i jak tłumacze powinni je pisać, można znaleźć w 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.

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

Pobieranie wejścia, dostarczanie wyjścia¶

shiftline()

Funkcja zwraca kolejną linię z doc_in do przetworzenia oraz jej odnośnik (spakowany jako tablica).

unshiftline($$)

Zwraca z powrotem linię dokumentu wejściowego i jej odnośnik.

pushline($)

Dodaje nową linię na koniec doc_out.

popline()

Pobiera ostatnio wstawioną linię z doc_out.

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

translate($$$)

Argumenty obowiązkowe:

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

Różne funkcje¶

verbose()

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

debug()

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

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.

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

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.

DALSZE WSKAZÓWKI¶

-

pobieranie hasha jak po_in_name (lista dla języka)

-

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

-

stworzenie funkcję pushline_all, która robiłaby pushline jej zawartości dla wszystkich języków, używając składni podobnej do składni map:

 

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

AUTORZY¶

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