Provided by: po4a_0.47-2_all 
名前
Locale::Po4a::Xml - PO ファイルと XML ドキュメントや派生物の変換
説明
po4a (PO for anything) プロジェクトは、gettext ツールが想定していないドキュメントのような
領域で翻訳をしやすくすること (またより興味深いのは、翻訳文の保守がしやすくなること) を目標
にしています。
Locale::Po4a::Xml は、XML ドキュメントを他の [自然] 言語へ翻訳するのを助けるモジュールで
す。XML を元にしたドキュメント用モジュールを作成するベースにもなります。
PO4A::XML での翻訳
このモジュールは、一般的な XML ドキュメントを直接扱うのに使用できます。ほとんどの XML を元
にしたドキュメントでは、タグの内容にテキストが書かれているため、タグの内容を抽出し属性は抽
出しません。
振る舞いをカスタマイズできるような、(次節で説明する) オプションがあります。あなたのドキュ
メントフォーマットに合わない場合は、フォーマットの詳細に合わせて、迷わず派生し作成してくだ
さい。その方法は、以下にある「派生モジュールの作成」節をご覧ください。
このモジュールで使用できるオプション
グローバルデバッグオプションにより、このモジュールは何か重要なものをスキップしていないか確
認するように、除外した文字列を表示するようになります。
以下は、このモジュール固有のオプションです。
nostrip
抽出した文字列の前後にある空白の除去を防ぎます。
wrap
Canonicalizes the string to translate, considering that whitespaces are not important,
and wraps the translated document. This option can be overridden by custom tag
options. See the "tags" option below.
caseinsensitive
タグや属性の検索を、大文字小文字を意識せずに行います。これを定義すると、<BooK>laNG や
<BOOK>Lang は <book>lang として扱います。
includeexternal
定義されていると、外部エンティティを生成した (翻訳した) ドキュメントに含め、文字列の抽
出を行います。定義されていなければ、外部エンティティを独立したドキュメントと同様に、別
個に訳さなければなりません。
ontagerror
This option defines the behavior of the module when it encounters invalid XML syntax
(a closing tag which does not match the last opening tag, or a tag's attribute without
value). It can take the following values:
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
Space-separated list of tag's attributes you want to translate. You can specify the
attributes by their name (for example, "lang"), but you can prefix it with a tag
hierarchy, to specify that this attribute will only be translated when it's in the
specified tag. For example: <bbb><aaa>lang specifies that the lang attribute will only
be translated if it's in an <aaa> tag, and it's in a <bbb> tag.
foldattributes
インラインタグの中で、翻訳しない属性です。そうでなければ、タグのすべての属性を
po4a-id=<id> 置換します。
これは、属性を翻訳しない場合、翻訳者向けに文字列を簡素化し、タイプミスを防ぎます。
customtag
タグとして扱いたくないタグの、空白区切りリストです。このタグはインラインとして扱わ
れ、閉じる必要はありません。
break
改行するとして扱いたいタグの、空白区切りリストです。デフォルトでは、すべてのタグに対し
て改行を行います。
The tags must be in the form <aaa>, but you can join some (<bbb><aaa>), if a tag
(<aaa>) should only be considered when it's within another tag (<bbb>).
inline
インラインとして扱いたいタグの、空白区切りリストです。デフォルトでは、すべてのタグに対
して改行を行います。
The tags must be in the form <aaa>, but you can join some (<bbb><aaa>), if a tag
(<aaa>) should only be considered when it's within another tag (<bbb>).
placeholder
プレースフォルダとして扱いたいタグの、空白区切りリストです。プレースフォルダは改行しま
せんが、プレースフォルダの内容は別に翻訳することになります。
そのブロック内のプレースフォルダの場所は、以下のような文字列で印が付きます。
<placeholder type=\"footnote\" id=\"0\"/>
The tags must be in the form <aaa>, but you can join some (<bbb><aaa>), if a tag
(<aaa>) should only be considered when it's within another tag (<bbb>).
nodefault
モジュールがデフォルトで、いずれのカテゴリでも設定しようとするべきでないタグの、空白区
切りリストです。
cpp C プリプロセッサディレクティブをサポートします。このオプションをセットすると、po4a は
プリプロセッサディレクティブを段落区切りとして扱います。XML ファイルが前処理
(preprocess) されなければならない場合に重要です。そうでなければ、po4a が現在の段落に属
すと見なせなければ、行の中にディレクティブを挿入する可能性があり、これをプリプロセッサ
が認識できないからです。注意: プリプロセッサディレクティブは、タグとタグの間にのみ現れ
なければなりません (タグを分断してはなりません)。
translated
翻訳するタグの、空白区切りリストです。
The tags must be in the form <aaa>, but you can join some (<bbb><aaa>), if a tag
(<aaa>) should only be considered when it's within another tag (<bbb>).
タグ階層の前に文字を付けてタグのオプションを指定できます。例えば、'w' (改行) や 'W'
(改行なし) を付けて、グローバル "wrap" オプションで指定したデフォルトの振る舞いを上書
きできます。
例: W<chapter><title>
untranslated
翻訳しないタグの、空白区切りリストです。
The tags must be in the form <aaa>, but you can join some (<bbb><aaa>), if a tag
(<aaa>) should only be considered when it's within another tag (<bbb>).
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)
This is a more complex one, but it enables a (almost) total customization. It's based on
a list of hashes, each one defining a tag type's behavior. The list should be sorted so
that the most general tags are after the most concrete ones (sorted first by the beginning
and then by the end keys). To define a tag type you'll have to make a hash with the
following keys:
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 ハッシュ内に移動?)
関連項目
Locale::Po4a::TransTractor(3pm), po4a(7)
著者
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-2009 by Nicolas François <nicolas.francois@centraliens.net>
本プログラムはフリーソフトウェアです。GPL の条項に基づき再頒布と変更を行うことができます
(COPYING ファイルをご覧ください)。