Provided by: po4a_0.52-1_all 
名前
Locale::Po4a::Xml - PO ファイルと XML ドキュメントや派生物の変換
説明
po4a (PO for anything) プロジェクトは、gettext ツールが想定していないドキュメントのような
領域で翻訳をしやすくすること (またより興味深いのは、翻訳文の保守がしやすくなること) を目標
にしています。
Locale::Po4a::Xml は、XML ドキュメントをほかの [自然] 言語へ翻訳するのを助けるモジュールで
す。XML を元にしたドキュメント用モジュールを作成するベースにもなります。
PO4A::XML での翻訳
このモジュールは、一般的な XML ドキュメントを直接扱うのに使用できます。ほとんどの XML を元
にしたドキュメントでは、タグの内容にテキストが書かれているため、タグの内容を抽出し属性は抽
出しません。
振る舞いをカスタマイズできるような、(次節で説明する) オプションがあります。あなたのドキュ
メントフォーマットに合わない場合は、フォーマットの詳細に合わせて、迷わず派生し作成してくだ
さい。その方法は、以下にある「派生モジュールの作成」節を参照してください。
このモジュールで使用できるオプション
グローバルデバッグオプションにより、このモジュールは何か重要なものをスキップしていないか確
認するように、除外した文字列を表示するようになります。
以下は、このモジュール固有のオプションです:
nostrip
抽出した文字列の前後にある空白の除去を防ぎます。
wrap
翻訳する文字列を正規化し、空白は重要ではないとみなして、翻訳されたドキュメントに改行を
差し込みます。このオプションは、カスタムタグオプションで上書きされます。以下の "tags"
オプションを参照してください。
unwrap_attributes
Attributes are wrapped by default. This option disables wrapping.
caseinsensitive
タグや属性の検索を、大文字小文字を意識せずに行います。これを定義すると、<BooK>laNG や
<BOOK>Lang は <book>lang として扱います。
escapequotes
Escape quotes in output strings. Necessary, for example, for creating string
resources for use by Android build tools.
See also: https://developer.android.com/guide/topics/resources/string-resource.html
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
翻訳する文字列を正規化し、空白は重要ではないとみなして、翻訳されたドキュメントに改行を
差し込みます。このオプションは、カスタムタグオプションで上書きされます。以下の "tags"
オプションを参照してください。
foldattributes
インラインタグの中で翻訳しない属性です。そうでなければ、タグのすべての属性を
po4a-id=<id> 置換します。
これは、属性を翻訳しない場合、翻訳者向けに文字列を簡素化し、タイプミスを防ぎます。
customtag
タグとして扱いたくないタグの空白区切りリストです。このタグはインラインとして扱われ、閉
じる必要はありません。
break
改行するとして扱いたいタグの空白区切りリストです。デフォルトでは、すべてのタグに対して
改行を行います。
タグは <aaa> の形でなければなりませんが、別のタグ (<bbb>) の中に入っているときにのみタ
グ (<aaa>) の内容を翻訳したい場合、つなげて書く (<bbb><aaa>) ことができます。
inline
インラインとして扱いたいタグの空白区切りリストです。デフォルトでは、すべてのタグに対し
て改行を行います。
タグは <aaa> の形でなければなりませんが、別のタグ (<bbb>) の中に入っているときにのみタ
グ (<aaa>) の内容を翻訳したい場合、つなげて書く (<bbb><aaa>) ことができます。
placeholder
プレースホルダとして扱われるべきタグの空白区切りリストです。プレースホルダはシーケンス
を改行しませんが、プレースホルダの内容は別々に翻訳されます。
そのブロック内のプレースホルダの場所は、以下のような文字列で印が付きます:
<placeholder type=\"footnote\" id=\"0\"/>
タグは <aaa> の形でなければなりませんが、別のタグ (<bbb>) の中に入っているときにのみタ
グ (<aaa>) の内容を翻訳したい場合、つなげて書く (<bbb><aaa>) ことができます。
nodefault
デフォルトではいずれのカテゴリにも設定しようとするべきではないモジュールのタグの空白区
切りリストです。
cpp C プリプロセッサディレクティブをサポートします。このオプションをセットすると、po4a は
プリプロセッサディレクティブを段落区切りとして扱います。XML ファイルが前処理
(preprocess) されなければならない場合に重要です。そうでなければ、po4a が現在の段落に属
すと見なせなければ、行の中にディレクティブを挿入する可能性があり、これをプリプロセッサ
が認識できないからです。注意: プリプロセッサディレクティブは、タグとタグの間にのみ現れ
なければなりません (タグを分断してはなりません)。
translated
翻訳するタグの空白区切りリストです。
タグは <aaa> の形でなければなりませんが、別のタグ (<bbb>) の中に入っているときにのみタ
グ (<aaa>) の内容を翻訳したい場合、つなげて書く (<bbb><aaa>) ことができます。
タグ階層の前に文字を付けてタグのオプションを指定できます。例えば、'w' (改行) や 'W'
(改行なし) を付けて、グローバル "wrap" オプションで指定したデフォルトの振る舞いを上書
きできます。
例: W<chapter><title>
untranslated
翻訳しないタグの空白区切りリストです。
タグは <aaa> の形でなければなりませんが、別のタグ (<bbb>) の中に入っているときにのみタ
グ (<aaa>) の内容を翻訳したい場合、つなげて書く (<bbb><aaa>) ことができます。
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() のフォーマットで) 受け取り、変換タグ (翻訳属性
や変換が必要なすべて) を単一の文字列で返します。
派生パーサ作成時に使用する内部関数
タグに対する動作
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 ファイルを参照してください)。