Provided by: po4a_0.57-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 translated option
below.
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
注意: このオプションは非推奨です。代わりに translated オプションや untranslated オプションを使用して
ください。
翻訳する、あるいは翻訳しないタグの空白区切りリストです。デフォルトでは、指定したタグは除外されます
が、"tagsonly" オプションを使用すると、指定したタグのみを含めるようになります。タグは <aaa> の形でな
ければなりませんが、<bbb> タグの中に入っているときのみ <aaa> タグの内容を翻訳したい場合、つなげて書く
(<bbb><aaa>) ことができます。
タグ階層の前に文字を付けてタグのオプションを指定できます。例えば、'w' (改行) や 'W' (改行なし) を付け
て、グローバル "wrap" オプションで指定したデフォルトの振る舞いを上書きできます。
例: W<chapter><title>
attributes
翻訳する文字列を正規化し、空白は重要ではないとみなして、翻訳されたドキュメントに改行を差し込みま
す。このオプションは、カスタムタグオプションで上書きされます。以下の "tags" オプションを参照してくだ
さい。
foldattributes
インラインタグの中で翻訳しない属性です。そうでなければ、タグのすべての属性を po4a-id=<id> 置換しま
す。
これは、属性を翻訳しない場合、翻訳者向けに文字列を簡素化し、タイプミスを防ぎます。
customtag
タグとして扱いたくないタグの空白区切りリストです。このタグはインラインとして扱われ、閉じる必要はあり
ません。
break
改行するとして扱いたいタグの空白区切りリストです。デフォルトでは、すべてのタグに対して改行を行いま
す。
タグは <aaa> の形でなければなりませんが、別のタグ (<bbb>) の中に入っているときにのみタグ (<aaa>) の内
容を翻訳したい場合、つなげて書く (<bbb><aaa>) ことができます。
Please note a tag should be listed in only one of the break, inline placeholder, or customtag setting
string.
inline
インラインとして扱いたいタグの空白区切りリストです。デフォルトでは、すべてのタグに対して改行を行いま
す。
タグは <aaa> の形でなければなりませんが、別のタグ (<bbb>) の中に入っているときにのみタグ (<aaa>) の内
容を翻訳したい場合、つなげて書く (<bbb><aaa>) ことができます。
placeholder
プレースホルダとして扱われるべきタグの空白区切りリストです。プレースホルダはシーケンスを改行しません
が、プレースホルダの内容は別々に翻訳されます。
そのブロック内のプレースホルダの場所は、以下のような文字列で印が付きます:
<placeholder type=\"footnote\" id=\"0\"/>
タグは <aaa> の形でなければなりませんが、別のタグ (<bbb>) の中に入っているときにのみタグ (<aaa>) の内
容を翻訳したい場合、つなげて書く (<bbb><aaa>) ことができます。
nodefault
デフォルトではいずれのカテゴリにも設定しようとするべきではないモジュールのタグの空白区切りリストで
す。
If you have a tag which has its default setting by the subclass of this module but you want to set
alternative setting, you need to list that tag as a part of the nodefault setting string.
cpp C プリプロセッサディレクティブをサポートします。このオプションをセットすると、po4a はプリプロセッサ
ディレクティブを段落区切りとして扱います。XML ファイルが前処理 (preprocess) されなければならない場合
に重要です。そうでなければ、po4a が現在の段落に属すと見なせなければ、行の中にディレクティブを挿入する
可能性があり、これをプリプロセッサが認識できないからです。注意: プリプロセッサディレクティブは、タグ
とタグの間にのみ現れなければなりません (タグを分断してはなりません)。
translated
翻訳するタグの空白区切りリストです。
タグは <aaa> の形でなければなりませんが、別のタグ (<bbb>) の中に入っているときにのみタグ (<aaa>) の内
容を翻訳したい場合、つなげて書く (<bbb><aaa>) ことができます。
You can also specify some tag options by putting some characters in front of the tag hierarchy. This
overrides the default behavior specified by the global wrap and defaulttranslateoption option.
w 翻訳し、内容を再改行するタグです。
W 翻訳を行うが改行を行うべきでない内容のコンマ区切りリストです。
i インラインで訳されるべきタグです。
p プレースホルダとして翻訳されるべきタグです。
Internally, the XML parser only cares about these four options: w W i p.
* Tags listed in B<break> are set to I<w> or I<W> depending on the <wrap> option.
* Tags listed in B<inline> are set to I<i>.
* Tags listed in B<placeholder> are set to I<p>.
* Tags listed in B<untranslated> are without any of these options set.
You can verify actual internal parameter behavior by invoking po4a with --debug option.
例: W<chapter><title>
Please note a tag should be listed in either translated or untranslated setting string.
untranslated
翻訳しないタグの空白区切りリストです。
タグは <aaa> の形でなければなりませんが、別のタグ (<bbb>) の中に入っているときにのみタグ (<aaa>) の内
容を翻訳したい場合、つなげて書く (<bbb><aaa>) ことができます。
Please note a translatable inline tag in an untranslated tag is treated as a translatable breaking
tag, i setting is dropped and w or W is set depending on the <wrap> option.
defaulttranslateoption
translated、untranslated、break、inline、または placeholder のいずれでもないタグのデフォルトカテゴ
リ。
This is a set of letters as defined in translated and this setting is only valid for translatable
tags.
WRITING DERIVATIVE MODULES
翻訳するタグや属性の定義
最も簡単なカスタマイズとして、パーサに変換させたいタグや属性を定義できます。これを初期化関数で行うべきで
す。まず、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;
You should use the _default_inline, _default_break, _default_placeholder, _default_translated,
_default_untranslated, and _default_attributes options in derivative modules. This allow users to
override the default behavior defined in your module with command line options.
OVERRIDE THE DEFAULT BEHAVIOR WITH COMMAND LINE OPTIONS
If you don't like the default behavior of this xml module and its derivative modules, you can provide
command line options to change their behavior.
See Locale::Po4a::Docbook(3pm),
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() のフォーマットで) 受け取り、変換タグ (翻訳属性や変換が必要なす
べて) を単一の文字列で返します。
INTERNAL FUNCTIONS used to write derivative parsers
タグに対する動作
get_path()
この関数は、ドキュメントのルートからの現在のタグのパスを、<html><body><p> の形態で返します。
タグ (括弧なし) の追加配列を引数に渡せます。要素パスは現在のパスの最後に追加されます。
tag_type()
この関数は、tag_types リストから、入力ストリームの次のタグに一致するもののインデックスを返します。入
力ファイルの最後の場合は、-1 を返します。
Here, the tag has structure started by < and end by > and it can contain multiple lines.
This works on the array "@{$self->{TT}{doc_in}}" holding input document data and reference indirectly
via "$self->shiftline()" and "$self->unshiftline($$)".
extract_tag($$)
この関数は、入力ストリームから、開始部と終了部を除いた次のタグを、入力ファイルからの参照を管理するた
め配列の形で返します。パラメータは以下の二つがあります。タグのタイプ (tag_type が返す形) と入力スト
リームから削除するかどうかを指定する真偽値です。
This works on the array "@{$self->{TT}{doc_in}}" holding input document data and reference indirectly
via "$self->shiftline()" and "$self->unshiftline($$)".
get_tag_name(@)
この関数は、extract_tag が返した配列を引数で受け取り、受け取ったタグの名前を返します。
breaking_tag()
この関数は、入力ストリームの次のタグが、改行タグかそうでない (インラインタグ) かを真偽値で返しま
す。入力ストリームは変化しません。
treat_tag()
この関数は入力ストリームから次のタグを翻訳します。タグタイプのカスタム翻訳関数ごとに使用します。
This works on the array "@{$self->{TT}{doc_in}}" holding input document data and reference indirectly
via "$self->shiftline()" and "$self->unshiftline($$)".
tag_in_list($@)
この関数は、第一引数 (タグ階層) が第二引数 (タグのリストやタグ階層) にあるタグと一致するかどうかの文
字列の値を返します。一致しない場合、0 を返します。そうでない場合、一致したタグのオプション (タグの前
の文字列) か 1 (オプションがない場合) を返します。
属性に対する動作
treat_attributes(@)
この関数は、タグの属性の翻訳を扱います。/ 終了マークで始まらないタグを受けとり、属性を探し、翻訳可能
のもの (モジュールオプション "attributes" で指定されたもの) を翻訳します。翻訳済みタグのテキストを返
します。
WORKING WITH TAGGED CONTENTS
treat_content()
This function gets the text until the next breaking tag (not inline) from the input stream.
Translate it using each tag type's custom translation functions.
This works on the array "@{$self->{TT}{doc_in}}" holding input document data and reference indirectly
via "$self->shiftline()" and "$self->unshiftline($$)".
モジュールオプションに対する動作
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 © 2004 Jordi Vilalta <jvprat@gmail.com>
Copyright © 2008-2009 Nicolas François <nicolas.francois@centraliens.net>
本プログラムはフリーソフトウェアです。GPL の条項に基づき再頒布と変更を行うことができます (COPYING ファイ
ルを参照してください)。
Po4a Tools 2020-04-15 Locale::Po4a::Xml(3pm)