Locale::Po4a::Xml.3pm

Autres langues

Langue: ja

Autres versions - même langue

Version: 2010-06-01 (fedora - 01/12/10)

Section: 3 (Bibliothèques de fonctions)

Sommaire

名前

Locale::Po4a::Xml - 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 とマッチさせようとする文字列。そうしなければ、ドキュメントは不正なタイプと見なします。
tags
翻訳する、あるいは翻訳しないタグの空白区切りリストです。デフォルトでは、指定したタグは除外されますが、``tagsonly'' オプションを使用すると、指定したタグのみを含めるようになります。タグは<aaa> の形でなければなりませんが、<bbb> タグの中に入っているときのみ <aaa> タグの内容を翻訳したい場合、つなげて書く (<bbb><aaa>) ことができます。

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

例: W<chapter><title>

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

attributes
翻訳するタグ属性の空白区切りリストです。属性名 (例: ``lang'') を指定できますが、指定したタグの中にある属性のみを翻訳するように、タグ階層を前に付けられます。例: <bbb><aaa>lang と指定すると、<bbb> タグの中にある <aaa> タグの中にある場合、lang 属性を翻訳するようになります。
inline
インラインとして扱いたいタグの、空白区切りリストです。デフォルトでは、すべてのタグに対して改行を行います。tags オプションと同じ文法です。
nodefault
モジュールがデフォルトで ``tags'' や ``inline'' カテゴリで設定しようとするべきでない、空白区切りリストです。
cpp
C プリプロセッサディレクティブをサポートします。このオプションをセットすると、po4a はプリプロセッサディレクティブを段落区切りとして扱います。XML ファイルが前処理 (preprocess) されなければならない場合に重要です。そうでなければ、po4a が現在の段落に属すと見なせなければ、行の中にディレクティブを挿入する可能性があり、これをプリプロセッサが認識できないからです。注意: プリプロセッサディレクティブは、タグとタグの間にのみ現れなければなりません (タグを分断してはなりません)。
translated
翻訳するタグの空白区切りリストです。タグは <aaa> の形でなければなりませんが、<bbb> タグの中に入っているときのみ <aaa> タグの内容を翻訳したい場合、つなげて書く (<bbb><aaa>) ことができます。

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

例: W<chapter><title>

untranslated
翻訳しないタグの、空白区切りリストです。translated オプションと同じ文法です。

派生モジュールの作成

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

最も簡単なカスタマイズとして、パーサに変換させたいタグや属性を定義できます。これを初期化関数で行うべきです。まず、main 関数を呼び出し、コマンドラインオプションを取得し、カスタム定義をオプションハッシュに追加します。コマンドラインから新しいオプションを扱いたい場合は、main の初期化を呼び出す前に、以下のように定義してください。 
   $self->{options}{'new_option'}='';
   $self->SUPER::initialize(%options);
   $self->{options}{'tags'}.=' <p> <head><title>';
   $self->{options}{'attributes'}.=' <p>lang id';
   $self->{options}{'inline'}.=' <br>';
   $self->treat_options;

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 リストにあります。

派生モジュールを書くのは、むしろ制限されています。

TODO リスト

DOCTYPE (エンティティ)

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

インクルードファイル

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

じゃまなコメント用に、非改行タグの中の改行タグ (可能 ?)

関連項目

po4a(7), Locale::Po4a::TransTractor(3pm).

著者

  Jordi Vilalta <jvprat@gmail.com>
  Nicolas François <nicolas.francois@centraliens.net>

訳者

  倉澤 望 <nabetaro@debian.or.jp>
  Debian JP Documentation ML <debian-doc@debian.or.jp>

著作権・ライセンス

  Copyright (c) 2004 by Jordi Vilalta  <jvprat@gmail.com>
  Copyright (c) 2008 by Nicolas François <nicolas.francois@centraliens.net>

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