.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Locale::Po4a::TransTractor 3pm" .TH Locale::Po4a::TransTractor 3pm "2020-08-19" "Narzędzia po4a" "Narzędzia po4a" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAZWA" .IX Header "NAZWA" Locale::Po4a::TransTractor \- ogólny moduł wyodrębniania tłumaczeń. .SH "OPIS" .IX Header "OPIS" Celem projektu po4a (\*(L"\s-1PO\s0 for anything\*(R") 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. .PP 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 \s-1PO\s0 oraz zastępowania ich tłumaczeniami w wyjściowym dokumencie. .PP Bardziej formalnie mówiąc, przyjmuje następujące argumenty jako wejście: .IP "\-" 2 dokument do przetłumaczenia; .IP "\-" 2 plik \s-1PO\s0 zawierający tłumaczenia do użycia. .PP Jako wynik dostajemy: .IP "\-" 2 inny plik \s-1PO,\s0 czego wynikiem jest wyciągnięcie komunikatów możliwych do przetłumaczenia z dokumentu wejściowego; .IP "\-" 2 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 \s-1PO.\s0 .PP Graficzna reprezentacja tego procesu: .PP .Vb 6 \& Dokument wejściowy \-\-\e /\-\-> Dokument wyjściowy \& \e / (przetłumaczony) \& +\-> funkcja parse() \-\-\-+ \& / \e \& Wejściowy PO \-\-\-\-\-\-\-\-/ \e\-\-> Wyjściowy PO \& (wyodrębniony) .Ve .SH "FUNKCJE, KTÓRE TWÓJ PARSER POWINIEN NADPISAĆ" .IX Header "FUNKCJE, KTÓRE TWÓJ PARSER POWINIEN NADPISAĆ" .IP "\fBparse()\fR" 4 .IX 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 \fB\s-1FUNKCJE\s0 WEWNĘTRZNE\fR. Patrz także sekcja \fBSKŁADNIA\fR, zawierająca przykład. .Sp Ta funkcja jest wywoływana przez poniższą funkcję \fBproces()\fR, ale jeżeli wybierze się użycie funkcji \fBnew()\fR i ręczenie się doda zawartość do dokumentu, trzeba będzie wywołać tę funkcję samemu. .IP "\fBdocheader()\fR" 4 .IX 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ę \&\fBPrzekazywanie deweloperom wiedzy o tłumaczeniu\fR w \fBpo4a\fR\|(7). .SH "SKŁADNIA" .IX Header "SKŁADNIA" Następujący przykład przetwarza listę akapitów rozpoczynających się od \&\*(L"
\*(R". Dla uproszczenia, zakładamy, że dokument jest dobrze sformatowany, tj. występują tylko elementy \*(L"
\*(R" i są one umieszczone na samym początku każdego akapitu. .PP .Vb 2 \& 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/
/ && !$first\-\-; ) { \& # Nie po raz pierwszy widzimy
. \& # 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/^
//s; \& \& # \- push to output the leading tag (untranslated) and the \& # rest of the paragraph (translated) \& $self\->pushline( "
"
\& . $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;
\& }
\& }
.Ve
.PP
Po zaimplementowaniu funkcji parsującej, można użyć własnych klas dokumentu,
używając publicznego interfejsu zaprezentowanego w następnym rozdziale.
.SH "INTERFEJS PUBLICZNY dla skryptów używających Twojego parsera"
.IX Header "INTERFEJS PUBLICZNY dla skryptów używających Twojego parsera"
.SS "Konstruktor"
.IX Subsection "Konstruktor"
.IP "process(%)" 4
.IX Item "process(%)"
Funkcja zrobi w jednym uruchomieniu wszystko, co tylko trzeba zrobić z
dokumentem po4a. Jej argumenty muszą być umieszczone w hashu. \s-1AKCJE:\s0
.RS 4
.IP "a." 3
.IX Item "a."
Czyta wszystkie pliki określone w po_in_name
.IP "b." 3
.IX Item "b."
Czyta wszystkie oryginalne dokumenty określone w file_in_name
.IP "c." 3
.IX Item "c."
Przetwarza (parsuje) dokument
.IP "d." 3
.IX Item "d."
Dodaje i stosuje wszystkie podane załączniki
.IP "e." 3
.IX Item "e."
Zapisuje przetłumaczony dokument do file_out_name (jeśli podano)
.IP "f." 3
.IX Item "f."
Zapisuje wygenerowany plik \s-1PO\s0 do po_out_name (jeśli podano)
.RE
.RS 4
.Sp
\&\s-1ARGUMENTY,\s0 poza tymi akceptowanymi przez \fBnew()\fR (z oczekiwanym typem):
.IP "file_in_name (@)" 4
.IX Item "file_in_name (@)"
Lista nazw plików, z których powinniśmy odczytać plik wejściowy.
.IP "file_in_charset ($)" 4
.IX 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).
.IP "file_out_name ($)" 4
.IX Item "file_out_name ($)"
Nazwa pliku, do którego należy zapisać wynikowy dokument.
.IP "file_out_charset ($)" 4
.IX Item "file_out_charset ($)"
Kodowanie znaków wyjściowego dokumentu (jeśli nie podano, będzie użyte
kodowanie znaków pliku \s-1PO\s0).
.IP "po_in_name (@)" 4
.IX Item "po_in_name (@)"
Lista nazw plików, z których powinniśmy odczytać wejściowe pliki \s-1PO\s0
zawierające tłumaczenia, które będą użyte podczas tłumaczenia dokumentu.
.IP "po_out_name ($)" 4
.IX Item "po_out_name ($)"
Nazwa pliku, do którego powinien być zapisany wynikowy plik \s-1PO,\s0 zawierający
komunikaty wyciągnięte z dokumentu wejściowego.
.IP "addendum (@)" 4
.IX Item "addendum (@)"
Lista nazw plików, z których powinniśmy odczytać pliki załączników.
.IP "addendum_charset ($)" 4
.IX Item "addendum_charset ($)"
Kodowanie znaków załączników.
.RE
.RS 4
.RE
.IP "new(%)" 4
.IX Item "new(%)"
Tworzy nowy dokument po4a. Akceptowane opcje (będące w hashu):
.RS 4
.IP "verbose ($)" 4
.IX Item "verbose ($)"
Ustawia gadatliwość.
.IP "debug ($)" 4
.IX Item "debug ($)"
Ustawia debugowanie.
.RE
.RS 4
.RE
.SS "Manipulowanie plikami z dokumentacją"
.IX Subsection "Manipulowanie plikami z dokumentacją"
.IP "read($$)" 4
.IX Item "read($$)"
Add another input document data at the end of the existing array \f(CW\*(C`@{$self\->{TT}{doc_in}}\*(C'\fR. The argument is the filename to read. If a second
argument is provided, it is the filename to use in the references.
.Sp
This array \f(CW\*(C`@{$self\->{TT}{doc_in}}\*(C'\fR holds this input document data as an
array of strings with alternating meanings.
* The string \f(CW$textline\fR holding each line of the input text data.
* The string \f(CW\*(C`$filename:$linenum\*(C'\fR holding its location and called as
\*(L"reference\*(R" (\f(CW\*(C`linenum\*(C'\fR starts with 1).
.Sp
Proszę zauważyć, że to niczego nie przetwarza. Należy użyć funkcji \fBparse()\fR
po zakończeniu pakowania plików wejściowych do dokumentu.
.IP "write($)" 4
.IX Item "write($)"
Zapisuje przetłumaczony dokument do pliku o podanej nazwie.
.Sp
This translated document data are provided by:
* \f(CW\*(C`$self\->docheader()\*(C'\fR holding the header text for the plugin, and
* \f(CW\*(C`@{$self\->{TT}{doc_out}}\*(C'\fR holding each line of the main translated text in the array.
.SS "Manipulowanie plikami \s-1PO\s0"
.IX Subsection "Manipulowanie plikami PO"
.IP "readpo($)" 4
.IX Item "readpo($)"
Dodaje zawartość pliku (którego nazwa jest podawana w argumencie) do
istniejącego pliku wejściowego \s-1PO.\s0 Stara zawartość nie jest tracona.
.IP "writepo($)" 4
.IX Item "writepo($)"
Zapisuje wygenerowany plik \s-1PO\s0 do pliku o podanej nazwie.
.IP "\fBstats()\fR" 4
.IX 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 \s-1PO,\s0 podczas gdy msgfmt wyświetla status tego
pliku. Funkcja jest opakowaniem funkcji Locale::Po4a::Po::stats_get
zastosowanej do wejściowego pliku \s-1PO.\s0 Przykład użycia:
.Sp
.Vb 1
\& [zwykłe użycie dokumentu po4a ...]
\&
\& ($percent,$hit,$queries) = $document\->stats();
\& print "Znaleźliśmy tłumaczenia $percent\e% ($hit z $queries) komunikatów.\en";
.Ve
.IP "\fBis_po_uptodate()\fR" 4
.IX Item "is_po_uptodate()"
Returns ($uptodate, \f(CW$diagnostic\fR) where \f(CW$uptodate\fR is whether the input po and
the output po match (if not, it means that the input po should be updated)
and \f(CW$diagnostic\fR is a string explaining why the po file is not uptodate, when
this happens.
.SS "Manipulowanie załącznikami"
.IX Subsection "Manipulowanie załącznikami"
.IP "addendum($)" 4
.IX Item "addendum($)"
Więcej informacji o tym, czym są załączniki, i jak tłumacze powinni je
pisać, można znaleźć w \fBpo4a\fR\|(7). Aby dodać załącznik do
przetłumaczonego dokumentu, wystarczy po prostu tej funkcji przekazać nazwę
pliku, w którym się znajduje, i gotowe ;)
.Sp
Funkcja zwraca liczbę nie będącą nullem lub błąd.
.SH "FUNKCJE WEWNĘTRZNE, używane do pisania parserów"
.IX Header "FUNKCJE WEWNĘTRZNE, używane do pisania parserów"
.SS "Pobieranie wejścia, dostarczanie wyjścia"
.IX Subsection "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.
.PP
.Vb 4
\& * 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.
.Ve
.PP
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.
.IP "\fBshiftline()\fR" 4
.IX Item "shiftline()"
This function returns the first line to be parsed and its corresponding
reference (packed as an array) from the array \f(CW\*(C`@{$self\->{TT}{doc_in}}\*(C'\fR
and drop these first 2 array items. Here, the reference is provided by a
string \f(CW\*(C`$filename:$linenum\*(C'\fR.
.IP "unshiftline($$)" 4
.IX Item "unshiftline($$)"
Unshifts the last shifted line of the input document and its corresponding
reference back to the head of \f(CW\*(C`{$self\->{TT}{doc_in}}\*(C'\fR.
.IP "pushline($)" 4
.IX Item "pushline($)"
Push a new line to the end of \f(CW\*(C`{$self\->{TT}{doc_out}}\*(C'\fR.
.IP "\fBpopline()\fR" 4
.IX Item "popline()"
Pop the last pushed line from the end of \f(CW\*(C`{$self\->{TT}{doc_out}}\*(C'\fR.
.SS "Zaznaczanie łańcuchów znaków jako możliwych do przetłumaczenia"
.IX Subsection "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.
.IP "translate($$$)" 4
.IX Item "translate($$$)"
Argumenty obowiązkowe:
.RS 4
.IP "\-" 2
Łańcuch znaków do przetłumaczenia
.IP "\-" 2
Odnośnik tego komunikatu (tj. pozycja w pliku wejściowym)
.IP "\-" 2
Typ tego komunikatu (tj. tekstowy opis jego roli w strukturze; używany w
\&\fBLocale::Po4a::Po::gettextization()\fR; patrz także \fBpo4a\fR\|(7), sekcja
\&\fBProces przekształcania do formatu gettext: jak to działa?\fR)
.RE
.RS 4
.Sp
Funkcja przyjmuje także kilka dodatkowych argumentów. Muszą być
zorganizowane jako hash. Na przykład:
.Sp
.Vb 2
\& $self\->translate("string","ref","type",
\& \*(Aqwrap\*(Aq => 1);
.Ve
.IP "\fBwrap\fR" 4
.IX Item "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.
.IP "\fBwrapcol\fR" 4
.IX Item "wrapcol"
kolumna, w której tekst powinien być zawijany (domyślnie: 76).
.IP "\fBcomment\fR" 4
.IX Item "comment"
dodatkowy komentarz do dodania do wpisu.
.RE
.RS 4
.Sp
Akcje:
.IP "\-" 2
Dodaje nowy komunikat, odnośnik i typ do po_out.
.IP "\-" 2
Zwraca tłumaczenie tekstu (znalezione w po_in), tak że parser może zbudować
doc_out.
.IP "\-" 2
Obsługuje kodowania znaków, aby zmienić kodowanie komunikatów przed
wysłaniem do po_out i przed zwróceniem tłumaczeń.
.RE
.RS 4
.RE
.SS "Różne funkcje"
.IX Subsection "Różne funkcje"
.IP "\fBverbose()\fR" 4
.IX Item "verbose()"
Zwraca informację, czy podczas uruchomienia TransTractora, podano opcję
verbose.
.IP "\fBdebug()\fR" 4
.IX Item "debug()"
Zwraca informację, czy podczas uruchomienia TransTractora podano opcję
debug.
.IP "detected_charset($)" 4
.IX 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 \fBprocess()\fR, albo z dokumentu.
.IP "\fBget_out_charset()\fR" 4
.IX 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).
.Sp
Użyje wyjściowego kodowania znaków podanego w linii poleceń. Jeśli go nie
podano, użyje kodowania znaków wejściowego pliku \s-1PO,\s0 a jeżeli jako to
kodowanie w pliku był ustawiony domyślny tekst \*(L"\s-1CHARSET\*(R",\s0 to zwróci
kodowanie znaków wejściowego dokumentu, tak że nie zostanie przeprowadzona
żadna konwersja kodowań.
.IP "recode_skipped_text($)" 4
.IX 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 (\fBtranslate()\fR wszystko
przekodowuje samodzielnie), ale wtedy, gdy pominięto komunikat z dokumentu
wejściowego, a dokument wyjściowy powinien mieć spójne kodowanie znaków.
.SH "DALSZE WSKAZÓWKI"
.IX Header "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.
.PP
Aby rozwiązać ten problem, jedynymi potrzebnymi zmianami w interfejsie są:
.IP "\-" 2
pobieranie hasha jak po_in_name (lista dla języka)
.IP "\-" 2
dodawanie argumentu do przetłumaczenia, wskazując język docelowy
.IP "\-" 2
make a pushline_all function, which would make pushline of its content for
all languages, using a map-like syntax:
.Sp
.Vb 3
\& $self\->pushline_all({ "Description[".$langcode."]=".
\& $self\->translate($line,$ref,$langcode)
\& });
.Ve
.PP
Zobaczymy, czy to wystarczy ;)
.SH "AUTORZY"
.IX Header "AUTORZY"
.Vb 3
\& Denis Barbier