man Locale::Po4a::Xml (3): PO ファイルと XML ドキュメントや派生物の変換

説明

po4a (PO for anything) プロジェクトは、gettext ツールが想定していないドキュメントのような領域で翻訳をしやすくすること (またより興味深いのは、翻訳文の保守がしやすくなること) を目標にしています。

Locale::Po4a::Xml は、XML ドキュメントを他の [自然] 言語へ翻訳するのを助けるモジュールです。XML を元にしたドキュメント用モジュールを作成するベースにもなります。

PO4A::XML での翻訳

このモジュールは、一般的な XML ドキュメントを直接扱うのに使用できます。ほとんどの XML を元にしたドキュメントでは、タグの内容にテキストが書かれているため、タグの内容を抽出し属性は抽出しません。

振る舞いをカスタマイズできるような、(次節で説明する) オプションがあります。あなたのドキュメントフォーマットに合わない場合は、フォーマットの詳細に合わせて、迷わず派生し作成してください。その方法は、以下にある「派生モジュールの作成」節をご覧ください。

このモジュールで使用できるオプション

グローバルデバッグオプションにより、このモジュールは何か重要なものをスキップしていないか確認するように、除外した文字列を表示するようになります。

以下は、このモジュール固有のオプションです。

nostrip

抽出した文字列の前後にある空白の除去を防ぎます。

wrap

空白は重要ではないとみなし、翻訳したドキュメントでは改行して、翻訳した文字列を納めます。このオプションは、カスタムタグオプションで上書きされます。以下の ``tags'' オプションをご覧ください。

caseinsensitive

タグや属性の検索を、大文字小文字を意識せずに行います。これを定義すると、<BooK>laNG や <BOOK>Lang は <book>lang として扱います。

includeexternal

定義されていると、外部エンティティを生成した (翻訳した) ドキュメントに含め、文字列の抽出を行います。定義されていなければ、外部エンティティを独立したドキュメントと同様に、別個に訳さなければなりません。

ontagerror

このオプションは、不正な XML 文法 (開始タグが見つからない終了タグや、値のないタグの属性) があった場合のこのモジュールの振る舞いを定義します。以下の値があります。

fail: デフォルト値です。エラーを表示して終了します。
warn: 警告を表示して、処理を継続します。
silent: 何も警告を表示せず、処理を継続します。

: このオプションを使用する場合は注意してください。通常、入力ファイルを修正するのをお勧めします。

tagsonly

``tags'' オプションで指定したタグしか抽出しません。もしくは、指定したタグを除くすべてのタグを抽出します。

注: このオプションは非推奨です。

doctype

先頭行にあるドキュメントの doctype と (定義されていれば) マッチさせようとする文字列。マッチしなければ、ドキュメントは不正なタイプと見なし警告します。

addlang

lang=``...'' 属性を追加するタグをパスで示した文字列です。言語は、PO ファイルの .po 拡張子を除いた basename で定義されます。

tags

翻訳する、あるいは翻訳しないタグの空白区切りリストです。デフォルトでは、指定したタグは除外されますが、``tagsonly'' オプションを使用すると、指定したタグのみを含めるようになります。タグは <aaa> の形でなければなりませんが、<bbb> タグの中に入っているときのみ <aaa> タグの内容を翻訳したい場合、つなげて書く (<bbb><aaa>) ことができます。

タグ階層の前に文字を付けてタグのオプションを指定できます。例えば、'w' (改行) や 'W' (改行なし) を付けて、グローバル ``wrap'' オプションで指定したデフォルトの振る舞いを上書きできます。

例: W<chapter><title>

注意: このオプションは非推奨です。代わりに translated オプションや untranslated オプションを使用してください。

attributes

翻訳するタグ属性の空白区切りリストです。属性名 (例: ``lang'') を指定できますが、指定したタグの中にある属性のみを翻訳するように、タグ階層を前に付けられます。例: <bbb><aaa>lang と指定すると、<bbb> タグの中の <aaa> タグにある場合、lang 属性を翻訳するようになります。

foldattributes

インラインタグの中で、翻訳しない属性です。そうでなければ、タグのすべての属性を po4a-id=<id> 置換します。

これは、属性を翻訳しない場合、翻訳者向けに文字列を簡素化し、タイプミスを防ぎます。

customtag

タグとして扱いたくないタグの、空白区切りリストです。このタグはインラインとして扱われ、閉じる必要はありません。

break

改行するとして扱いたいタグの、空白区切りリストです。デフォルトでは、すべてのタグに対して改行を行います。

タグは <aaa> の形でなければなりませんが、別のタグ (<bbb>) の中に入っているときのみタグ (<aaa>) の内容を翻訳したい場合、つなげて書く (<bbb><aaa>) ことができます。

inline

インラインとして扱いたいタグの、空白区切りリストです。デフォルトでは、すべてのタグに対して改行を行います。

placeholder

プレースフォルダとして扱いたいタグの、空白区切りリストです。プレースフォルダは改行しませんが、プレースフォルダの内容は別に翻訳することになります。

そのブロック内のプレースフォルダの場所は、以下のような文字列で印が付きます。

  <placeholder type=\"footnote\" id=\"0\"/>

nodefault

モジュールがデフォルトで、いずれのカテゴリでも設定しようとするべきでないタグの、空白区切りリストです。

cpp

C プリプロセッサディレクティブをサポートします。このオプションをセットすると、po4a はプリプロセッサディレクティブを段落区切りとして扱います。XML ファイルが前処理 (preprocess) されなければならない場合に重要です。そうでなければ、po4a が現在の段落に属すと見なせなければ、行の中にディレクティブを挿入する可能性があり、これをプリプロセッサが認識できないからです。注意: プリプロセッサディレクティブは、タグとタグの間にのみ現れなければなりません (タグを分断してはなりません)。

translated

翻訳するタグの、空白区切りリストです。

タグ階層の前に文字を付けてタグのオプションを指定できます。例えば、'w' (改行) や 'W' (改行なし) を付けて、グローバルの ``wrap'' オプションで指定したデフォルトの挙動を上書きできます。

例: W<chapter><title>

untranslated

翻訳しないタグの、空白区切りリストです。

defaulttranslateoption

タグのデフォルトカテゴリは、translated, untranslated, break, inline, placeholder のいずれでもありません。

以下の文字で設定します。

w: 翻訳し、内容を際改行するタグです。
W: 翻訳を行うが改行を行うべきでない内容のカンマ区切りリストです。
i: インラインで訳されるべきタグです。
p: プレースフォルダとして訳されるべきタグです。

派生モジュールの作成

翻訳するタグや属性の定義

最も簡単なカスタマイズとして、パーサに変換させたいタグや属性を定義できます。これを初期化関数で行うべきです。まず、main 関数を呼び出し、コマンドラインオプションを取得し、カスタム定義をオプションハッシュに追加します。コマンドラインから新しいオプションを扱いたい場合は、main の初期化を呼び出す前に、以下のように定義してください。

  $self->{options}{'new_option'}='';
  $self->SUPER::initialize(%options);
  $self->{options}{'_default_translated'}.=' <p> <head><title>';
  $self->{options}{'attributes'}.=' <p>lang id';
  $self->{options}{'_default_inline'}.=' <br>';
  $self->treat_options;

派生モジュール内では、_default_inline, _default_break, _default_placeholder, _default_translated, _default_untranslated, _default_attributes の各オプションを使用するべきです。このオプションは、ユーザがコマンドラインオプションで、あなたのモジュールのデフォルトの挙動をオーバーライドできます。

found_string 関数の上書き

その他の簡単なステップとしては、パーサから抽出した文字列を翻訳するために受け取る ``found_string'' 関数の上書きがあります。そこでは、翻訳する文字列を制御し、翻訳自体の前後での変換を行えます。

抽出したテキスト、それがどこにあったかの参照位置、そして、どの文字列を翻訳するか、どのように翻訳するか、どのようにコメントを生成するか、といったことを制御する追加情報を含むハッシュを受け取ります。

このオプションの内容は、(このハッシュのエントリで指定する) 文字列の種類に依存します。

type="tag": 見つかった文字列は翻訳するタグの内容です。``tag_options'' エントリにはモジュールの ``tags'' オプションにあるタグ階層の、直前のオプション文字を含みます。
type="attribute": 検出した文字列が、翻訳可能な属性値であることを意味します。``attribute'' エントリは、属性名を持っています。

これは、翻訳済みドキュメントでオリジナルを置き換えるテキストを、返さなければなりません。以下に、この関数の基本的な例を示します。

  sub found_string {
    my ($self,$text,$ref,$options)=@_;
    $text = $self->translate($text,$ref,"type ".$options->{'type'},
      'wrap'=>$self->{options}{'wrap'});
    return $text;
  }

別のシンプルな例は、(いくつかの文字列のフィルタでしかない) 新しい Dia モジュールにあります。

タグタイプの変更 (TODO)

これはかなり複雑な部分ですが、全体のカスタマイズを行うことができます。それぞれタグタイプの振る舞いを定義した、ハッシュのリストを基にしています。このリストはソートされるべきなので、もっとも具体的なもの (beginning キーで始まり end キーの順) の後に一般的なタグがきます。タグタイプを定義するには、以下のキーを持つハッシュを作成する必要があります。

beginning: ``<'' に続くタグの開始記号を指定します。
end: ``>'' の前のタグの終了記号を指定します。
breaking: 改行するタグクラスであることを指定します。改行しない (インライン) タグは、別のタグの内容の一部として取られるものです。値は偽 (0)、真 (1)、未定義のいずれかを取ります。未定義のままにすると、このクラスの具体的なタグが、タグを改行するかどうかを指定するため、f_breaking 関数を定義しなければなりません。
f_breaking: 次のタグが改行されているかどうかを調べる関数です。breaking オプションが定義されていなければ、定義する必要があります。
f_extract: このキーを未定義にしておくと、汎用抽出関数はタグ自体を抽出しなければなりません。これは、内部に別のタグがある、または特殊な構造を持つタグにとって、メインのパーサがおかしくならないですみ、役に立ちます。この関数は、入力ストリームからタグを削除するかどうかを決める、真偽値を受け付けます。
f_translate: この関数は、タグを (get_string_until() のフォーマットで) 受け取り、変換タグ (翻訳属性や変換が必要なすべて) を 1 文字列で返します。

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

タグに対する動作

get_path(): この関数は、ドキュメントのルートからの現在のタグのパスを、<html><body><p> の形態で返します。
タグ (括弧なし) の追加配列を引数に渡せます。要素パスは現在のパスの最後に追加されます。
tag_type(): この関数は、tag_types リストから、入力ストリームの次のタグに一致するもののインデックスを返します。入力ファイルの最後の場合は、-1 を返します。
extract_tag($$): この関数は、入力ストリームから、開始部と終了部を除いた次のタグを、入力ファイルからの参照を管理するため配列の形で返します。パラメータは以下の二つがあります。タグのタイプ (tag_type が返す形) と入力ストリームから削除するかどうかを指定する真偽値です。
get_tag_name(@): この関数は、extract_tag が返した配列を引数で受け取り、受け取ったタグの名前を返します。
breaking_tag(): この関数は、入力ストリームの次のタグが、改行タグかそうでない (インラインタグ) かを真偽値で返します。入力ストリームは変化しません。
treat_tag(): この関数は入力ストリームから次のタグを翻訳します。タグタイプのカスタム翻訳関数ごとに使用します。
tag_in_list($@): この関数は、第一引数 (タグ階層) が第二引数 (タグのリストやタグ階層) にあるタグと一致するかどうかの文字列の値を返します。一致しない場合、0 を返します。そうでない場合、一致したタグのオプション (タグの前の文字列) か 1 (オプションがない場合) を返します。

属性に対する動作

treat_attributes(@): この関数は、タグの属性の翻訳を扱います。/ 終了マークで始まらないタグを受けとり、属性を探し、翻訳可能のもの (モジュールオプション ``attributes'' で指定されたもの) を翻訳します。翻訳済みタグのテキストを返します。

モジュールオプションに対する動作

treat_options(): この関数は、内部構造をモジュールのオプションの (コマンドラインや initialize 関数で指定した) タグ、属性、インラインデータで満たします。

入力ドキュメントからのテキスト取得

get_string_until($%)

この関数は入力ドキュメントから、第一引数に指定した文字列が見つかるまで、行 (とその参照) を配列で返します。第二引数は、オプションのハッシュです。値が 0 は無効を表し、1 は有効を表します。

以下のオプションが有効です。

include: 検索したテキストを含む配列を返すようになります。
remove: 入力から返ったストリームを削除します。
unquoted: 検索テキストが、クォート外にあることを保証します。

skip_spaces(\@)

この関数は引数として段落の参照 (get_string_until が返すフォーマット) を受け取り、頭の空白をスキップし、単純な文字列として返します。

join_lines(@)

この関数は、属性の配列から、テキストのシンプルな文字列を返します (参照を廃棄)。

このモジュールの状態

このモジュールはタグや属性を翻訳できます。

TODO リスト

DOCTYPE (エンティティ)

エンティティの翻訳は最小限しかサポートしていません。翻訳は全体が対象となり、タグは考慮しません。複数行のエンティティはサポートしておらず、翻訳中ではエンティティは常に再度折り返されます。

継承モジュールでのタグタイプ変更 (tag_types 構造体を $self ハッシュ内に移動?)

著者

 Jordi Vilalta <[email protected]>
 Nicolas François <[email protected]>

著作権・ライセンス

 Copyright (c) 2004 by Jordi Vilalta  <[email protected]>
 Copyright (c) 2008-2009 by Nicolas François <[email protected]>

本プログラムはフリーソフトウェアです。GPL の条項に基づき再頒布と変更を行うことができます (COPYING ファイルをご覧ください)。

説明