\*(R" で始まる段落のリストをパースします。簡単にするために、ドキュメントは整形されている、すなわち、現れるタグは '
' のみで、各段落はこのタグで必ず始まると仮定します。 .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\-\-; ) { \& # Not the first time we see
. \& # Reput the current line in input, \& # and put the built paragraph to output \& $self\->unshiftline($line,$lref); \& \& # Now that the document is formed, translate it: \& # \- Remove the leading tag \& $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 {
\& # Append to the paragraph
\& $paragraph .= $line;
\& $pararef = $lref unless(length($pararef));
\& }
\&
\& # Reinit the loop
\& ($line,$lref)=$self\->shiftline();
\& }
\& # Did not get a defined line? End of input file.
\& return;
\& }
\& }
.Ve
.PP
parse 関数を実装したら、次節で説明するパブリックインターフェースを用いて document クラスを使用できます。
.SH "パーサで使用するスクリプトのパブリックインターフェース"
.IX Header "パーサで使用するスクリプトのパブリックインターフェース"
.SS "コンストラクタ"
.IX Subsection "コンストラクタ"
.IP "process(%)" 4
.IX Item "process(%)"
この関数は、po4a ドキュメントで行うのに必要なすべてを、一度の実行で行います。引数はハッシュとしてパックしなくてはなりません。動作は以下のようになります:
.RS 4
.IP "a." 3
.IX Item "a."
po_in_name で指定したすべての \s-1PO\s0 ファイルの読み込み
.IP "b." 3
.IX Item "b."
file_in_name で指定したすべてのオリジナルドキュメントの読み込み
.IP "c." 3
.IX Item "c."
ドキュメントのパース
.IP "d." 3
.IX Item "d."
指定したすべての追加内容の読み込みと適用
.IP "e." 3
.IX Item "e."
翻訳したドキュメントの file_out_name への書き出し (与えられた場合)
.IP "f." 3
.IX Item "f."
抽出した \s-1PO\s0 ファイルの po_out_name への書き出し (与えられた場合)
.RE
.RS 4
.Sp
\&\fBnew()\fR で受け付けるもの以外の引数 (と想定する型):
.IP "file_in_name (@)" 4
.IX Item "file_in_name (@)"
読み込むべき入力ドキュメントのファイル名のリストです。
.IP "file_in_charset ($)" 4
.IX Item "file_in_charset ($)"
入力ドキュメントで使用している文字セットです (指定しない場合、入力ドキュメントから検出しようとします)。
.IP "file_out_name ($)" 4
.IX Item "file_out_name ($)"
書き出すべき出力ドキュメントのファイル名です。
.IP "file_out_charset ($)" 4
.IX Item "file_out_charset ($)"
出力ドキュメントで使用する文字セットです (指定しない場合、PO ファイルの文字セットを使用します)。
.IP "po_in_name (@)" 4
.IX Item "po_in_name (@)"
読み込むべき入力 \s-1PO\s0 ファイル (ドキュメントの翻訳に使用する翻訳) のファイル名のリストです。
.IP "po_out_name ($)" 4
.IX Item "po_out_name ($)"
入力ドキュメントから抽出した文字列を含む、書き出すべき出力 \s-1PO\s0 ファイルのファイル名です。
.IP "addendum (@)" 4
.IX Item "addendum (@)"
読み込むべき追加内容のファイル名のリストです。
.IP "addendum_charset ($)" 4
.IX Item "addendum_charset ($)"
追加内容の文字セット
.RE
.RS 4
.RE
.IP "new(%)" 4
.IX Item "new(%)"
Create a new po4a document. Accepted options (in the hash passed as a parameter):
.RS 4
.IP "verbose ($)" 4
.IX Item "verbose ($)"
冗長表示を有効にします。
.IP "debug ($)" 4
.IX Item "debug ($)"
デバッグを有効にします。
.RE
.RS 4
.RE
.SS "ドキュメントファイルの操作"
.IX Subsection "ドキュメントファイルの操作"
.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
パースは一切行わないことに注意してください。入力ファイルがドキュメントに格納した時点で \fBparse()\fR 関数を使用するべきです。
.IP "write($)" 4
.IX Item "write($)"
与えたファイル名で翻訳済みドキュメントを書き出します。
.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 "\s-1PO\s0 ファイルの操作"
.IX Subsection "PO ファイルの操作"
.IP "readpo($)" 4
.IX Item "readpo($)"
既存の入力 \s-1PO\s0 に、(引数で渡した名前の) ファイルの内容を追加します。古い内容は破棄されません。
.IP "writepo($)" 4
.IX Item "writepo($)"
抽出した \s-1PO\s0 ファイルを与えたファイル名で書き出します。
.IP "\fBstats()\fR" 4
.IX Item "stats()"
現在までに翻訳した内容に関する統計を返します。msgfmt \-\-statistic が出力する統計とは同じとは限らないことに注意してください。ここでは、PO ファイルの最新の使用法についての統計ですが、msgfmt が報告するのは、ファイルの状態についてです。これは、Locale::Po4a::Po::stats_get 関数を入力した \s-1PO\s0 ファイルに適用するラッパーです。サンプルは以下のようになります:
.Sp
.Vb 1
\& [po4a ドキュメントの通常の使用...]
\&
\& ($percent,$hit,$queries) = $document\->stats();
\& print "We found translations for $percent\e% ($hit from $queries) of strings.\en";
.Ve
.SS "追加内容の操作"
.IX Subsection "追加内容の操作"
.IP "addendum($)" 4
.IX Item "addendum($)"
追加内容とは何か、や、翻訳者はどのように書いたらよいのかといった情報は、\fBpo4a\fR\|(7) を参照してください。翻訳したドキュメントに追加内容を適用するには、この関数に単純にファイル名を渡し、実行するだけです ;)
.Sp
この関数は、エラー時に null 以外の数値を返します。
.SH "派生パーサ作成時に使用する内部関数"
.IX Header "派生パーサ作成時に使用する内部関数"
.SS "入力と出力"
.IX Subsection "入力と出力"
Four functions are provided to get input and return output. They are very similar to shift/unshift and push/pop of Perl.
.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
The first pair is about input, while the second is about output. Mnemonic: in input, you are interested in the first line, what shift gives, and in output you want to add your result at the end, like push does.
.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 "文字列を翻訳可能としてマーク"
.IX Subsection "文字列を翻訳可能としてマーク"
翻訳するべきテキストを扱う関数を一つ用意しています。
.IP "translate($$$)" 4
.IX Item "translate($$$)"
必須の引数:
.RS 4
.IP "\-" 2
翻訳する文字列
.IP "\-" 2
この文字列の参照 (言い換えると、入力ファイルの場所)
.IP "\-" 2
文字列の型 (つまり構造上の役割をテキストで説明したもの。\fBLocale::Po4a::Po::gettextization()\fR で使用します。 \fBpo4a\fR\|(7) の \fBgettext 化: どのように動作しますか?\fR 節も参照してください)
.RE
.RS 4
.Sp
この関数は、いくつか追加引数を取れます。ハッシュとしてまとめなければなりません。例えば:
.Sp
.Vb 2
\& $self\->translate("string","ref","type",
\& \*(Aqwrap\*(Aq => 1);
.Ve
.IP "\fBwrap\fR" 4
.IX Item "wrap"
文字列中の空白が重要でないとして扱うかどうかを示す真偽値です。重要でない場合、この関数は、翻訳を探したり抽出したりする前の文字列を納め、翻訳を折り返します。
.IP "\fBwrapcol\fR" 4
.IX Item "wrapcol"
改行を行う幅です (デフォルト: 76)。
.IP "\fBcomment\fR" 4
.IX Item "comment"
エントリに追加する更なるコメント。
.RE
.RS 4
.Sp
動作:
.IP "\-" 2
文字列、参照、型を po_out に push します。
.IP "\-" 2
パーサが doc_out をビルドできるように、文字列の翻訳 (po_in に見つかったもの) を返します。
.IP "\-" 2
文字列を po_out に送る前や翻訳を返す前に、文字列を再コード化する文字セットを扱います。
.RE
.RS 4
.RE
.SS "その他の関数"
.IX Subsection "その他の関数"
.IP "\fBverbose()\fR" 4
.IX Item "verbose()"
TransTractor の生成時に verbose オプションが渡された場合、返します。
.IP "\fBdebug()\fR" 4
.IX Item "debug()"
TransTractor の生成時に debug オプションが渡された場合、返します。
.IP "detected_charset($)" 4
.IX Item "detected_charset($)"
これは、入力ドキュメントから新しい文字セット (第一引数) を検出したと、TransTractor に伝えます。通常、ドキュメントのヘッダから読むことができます。\fBprocess()\fR の引数から来たものとドキュメントから検出したもののうち、最初の文字セットのみが対象となります。
.IP "\fBget_out_charset()\fR" 4
.IX Item "get_out_charset()"
この関数は、出力文書で使用する文字セットを返します（この関数により見付かった入力文書で検出された文字セットを置き換えるのに、大抵の場合で便利です）。
.Sp
コマンドラインで指定した出力文字セットが使われます。指定しない場合は、入力 \s-1PO\s0 ファイルの文字セットを使用します。入力 \s-1PO\s0 ファイルにデフォルトの \*(L"\s-1CHARSET\*(R"\s0 がある場合は、入力ドキュメントの文字セットを返します。そして、エンコーディングの変換は行われません。
.IP "recode_skipped_text($)" 4
.IX Item "recode_skipped_text($)"
この関数は、引数で渡したテキストを、入力ドキュメントの文字セットから、出力ドキュメントの文字セットへ、再コード化して返します。これは、文字列を翻訳する際には必要ありませんが (\fBtranslate()\fR は、自分ですべて再コード化します)、入力ドキュメントからの文字列をスキップし、出力ドキュメントを共通のエンコードで一致させたい場合に必要です。
.SH "将来の方向性"
.IX Header "将来の方向性"
現在の TransTractor の欠点の一つに、(debconf テンプレートや、.desktop ファイルのような) すべての言語を含む翻訳済みドキュメントを扱えないというものがあります。
.PP
この問題に対処するには、以下のようにインターフェースのみを変更することが必要です:
.IP "\-" 2
po_in_name (言語ごとのリスト) としてハッシュを取ります
.IP "\-" 2
対象言語を示すための翻訳する引数を追加します
.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
これで十分だといいのですが ;)
.SH "著者"
.IX Header "著者"
.Vb 3
\& Denis Barbier