Locale::Po4a::TransTractor

名前

説明

-

翻訳する文書；

-

使用する翻訳を含むPO ファイル。

-

入力ドキュメントから翻訳可能な文字列を抽出した、別の PO ファイル。

-

入力したものと同じ構造で、入力した PO ファイルにある翻訳で翻訳可能な文字列を置換した、翻訳済みドキュメント。

   入力ドキュメント-\                             /---> 出力ドキュメント
                     \                           /          (翻訳済)
                      +-> parse() 関数 ---------+
                     /                           \
   入力 PO  --------/                             \---> 出力 PO
                                                         (抽出済)

個別のパーサでオーバーライドするべき関数

parse()

ここに、入力ドキュメントのパース、出力の生成、翻訳可能文字列の抽出といった、すべての動作を定義しています。後述する 内部関数 節で説明する提供された関数を使用するのはかなり簡単です。サンプル付きの 書式 も参照してください。 この関数は後述の process() 関数から呼ばれますが、 new() 関数を使用してドキュメントに内容を手で追加するのを選んだ場合、この関数自体を呼ばねばなりません。

docheader()

この関数は、ターゲットの言語でコメントにするために適切にクォートした、生成したドキュメントに追加するべきヘッダを返します。この何がよいのかは、po4a(7) の 翻訳についての開発者教育 節を参照してください。

書式

 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--; ) {
               # Not the first time we see <p>.
               # 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/^<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 {
               # 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;
   }
 }

パーサで使用するスクリプトのパブリックインターフェース

コンストラクタ

process(%)

この関数は、po4a ドキュメントで行うのに必要なすべてを、一度の実行で行います。引数はハッシュとしてパックしなくてはなりません。動作は以下のようになります:

new(%)

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

ドキュメントファイルの操作

read($$)

Add another input document data at the end of the existing array "@{$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 "@{$self->{TT}{doc_in}}" holds this input document data as an array of strings with alternating meanings.
* The string $textline holding each line of the input text data.
* The string "$filename:$linenum" holding its location and called as
"reference" ("linenum" starts with 1). パースは一切行わないことに注意してください。入力ファイルがドキュメントに格納した時点で parse() 関数を使用するべきです。

write($)

与えたファイル名で翻訳済みドキュメントを書き出します。 This translated document data are provided by:
* "$self->docheader()" holding the header text for the plugin, and
* "@{$self->{TT}{doc_out}}" holding each line of the main translated text in the array.

PO ファイルの操作

readpo($)

既存の入力 PO に、(引数で渡した名前の) ファイルの内容を追加します。古い内容は破棄されません。

writepo($)

抽出した PO ファイルを与えたファイル名で書き出します。

stats()

現在までに翻訳した内容に関する統計を返します。msgfmt --statistic が出力する統計とは同じとは限らないことに注意してください。ここでは、PO ファイルの最新の使用法についての統計ですが、msgfmt が報告するのは、ファイルの状態についてです。これは、Locale::Po4a::Po::stats_get 関数を入力した PO ファイルに適用するラッパーです。サンプルは以下のようになります:

    [po4a ドキュメントの通常の使用...]
    ($percent,$hit,$queries) = $document->stats();
    print "We found translations for $percent\%  ($hit from $queries) of strings.\n";
    

追加内容の操作

addendum($)

追加内容とは何か、や、翻訳者はどのように書いたらよいのかといった情報は、po4a(7) を参照してください。翻訳したドキュメントに追加内容を適用するには、この関数に単純にファイル名を渡し、実行するだけです ;) この関数は、エラー時に null 以外の数値を返します。

派生パーサ作成時に使用する内部関数

入力と出力

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

shiftline()

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

unshiftline($$)

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

pushline($)

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

popline()

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

文字列を翻訳可能としてマーク

translate($$$)

必須の引数:

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

その他の関数

verbose()

TransTractor の生成時に verbose オプションが渡された場合、返します。

debug()

TransTractor の生成時に debug オプションが渡された場合、返します。

detected_charset($)

これは、入力ドキュメントから新しい文字セット (第一引数) を検出したと、TransTractor に伝えます。通常、ドキュメントのヘッダから読むことができます。 process() の引数から来たものとドキュメントから検出したもののうち、最初の文字セットのみが対象となります。

get_out_charset()

この関数は、出力文書で使用する文字セットを返します（この関数により見付かった入力文書で検出された文字セットを置き換えるのに、大抵の場合で便利です）。 コマンドラインで指定した出力文字セットが使われます。指定しない場合は、入力 PO ファイルの文字セットを使用します。入力 PO ファイルにデフォルトの "CHARSET" がある場合は、入力ドキュメントの文字セットを返します。そして、エンコーディングの変換は行われません。

recode_skipped_text($)

この関数は、引数で渡したテキストを、入力ドキュメントの文字セットから、出力ドキュメントの文字セットへ、再コード化して返します。これは、文字列を翻訳する際には必要ありませんが ( translate() は、自分ですべて再コード化します)、入力ドキュメントからの文字列をスキップし、出力ドキュメントを共通のエンコードで一致させたい場合に必要です。

将来の方向性

-

po_in_name (言語ごとのリスト) としてハッシュを取ります

-

対象言語を示すための翻訳する引数を追加します

-

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)
                        });
    

著者

 Denis Barbier <[email protected]>
 Martin Quinson (mquinson#debian.org)
 Jordi Vilalta <[email protected]>

訳者

 倉澤 望 <[email protected]>
 Debian JP Documentation ML <[email protected]>