名前

Locale::Po4a::Xml - XML文書及びその派生をPOファイルと相互変換する

説明

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

Locale::Po4a::Xml は、XML 文書をほかの [自然] 言語へ翻訳するのを助けるモジュールです。XML を元にした文書用モジュールを作成する土台としても使うことができます。

PO4A::XML を使った翻訳

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

振る舞いをカスタマイズできるような、（次節で説明する）オプションがあります。手元の文書形式と合わない場合は、形式を詳細に記述できるよう、迷わずこれから派生した独自のモジュールを書いてください。その方法は以下にある「派生モジュールの書き方」節を参照してください。

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

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

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

nostrip

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

wrap

翻訳する文字列を正規化し、空白は重要ではないとみなして、翻訳された文書を折り返します。このオプションは、カスタムタグオプションで上書きされます。以下の translated オプションを参照してください。

unwrap_attributes

属性は既定で折り返されます。このオプションは折り返しを無効にします。

caseinsensitive

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

escapequotes

出力文字列で引用符をエスケープします。例えばAndroidのビルドツールで使用する文字列リソースを作成する場合などに必要です。

https://developer.android.com/guide/topics/resources/string-resource.html も参照してください

includeexternal

定義されている場合、外部実体が生成した（翻訳済み）文書に含まれ、文字列の抽出のために使用されます。定義されていなければ、外部実体を独立した文書として、個別に翻訳する必要があります。

ontagerror

このオプションは、（開始タグと一致しない終了タグといった）不正な XML 文法があった場合のこのモジュールの振る舞いを定義します。以下の値を取り得ます。

tagsonly

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

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

doctype

文書の最初の行の doctype （が定義されていればそれ）と照合させようとする文字列。照合しなければ、文書は不正な型と見なし警告します。

addlang

lang="..." 属性を追加するタグへのパス（例： <bbb><aaa>）を示す文字列です。言語は、PO ファイルの .po 拡張子を除いた basename で定義されます。

optionalclosingtag

（HTMLのように）終了タグを省略可能かどうかを示す真偽値。既定では、閉じタグがない場合は ontagerror に従って制御されるエラーが発生します。

tags

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

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

タグ階層の前に文字を付けてタグのオプションを指定できます。例えば、l<w>（改行）や l<W> （改行なし）を付けて、グローバル wrap オプションで指定した既定の振る舞いを上書きできます。

例：W<chapter><title>

attributes

翻訳したいタグの属性の空白区切りリスト。属性の名前（例えば "lang"）で指定することもできますが、タグの階層を前につけて、この属性が指定されたタグの中にあるときだけ翻訳されるように指定することができます。例えば<bbb><aaa>lang は、lang属性が<aaa>タグの中にあり、さらにそれが<bbb>の中にある場合のみ翻訳されるように指定します。

foldattributes

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

これは、属性を翻訳してはならない場合に有効で、翻訳者のために文字列を単純化し、誤植を避けることができます。

customtag

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

break

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

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

タグは、break、inline、placeholder、 customtag 設定文字列のうち1つだけのリスト中に含まれている必要があります。

inline

インラインとして扱いたいタグの空白区切りリストです。既定では、すべてのタグのところで文字の並びが改行されます。

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

placeholder

プレースホルダとして扱われるべきタグの空白区切りリストです。プレースホルダは文字の並びを改行しませんが、プレースホルダの内容は別々に翻訳されます。

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

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

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

break-pi

既定では、処理命令（すなわち、"<? ... ?>"タグ）はインラインタグとして扱われます。 PIを改行タグとして処理したい場合は、このオプションを渡します。 未処理のPHPタグは、構文解析器によって処理命令として扱われることに注意してください。

nodefault

モジュールが既定でいずれの分類にも設定するべきではないタグの空白区切りリストです。

このモジュールの副クラス由来の既定の設定があるタグがあるけれども、これに別の設定をしたいようなときは、nodefault設定文字列の一部としてそのタグをリストにする必要があります。

cpp

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

translated

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

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

タグ階層の前に文字を付けてタグのオプションを指定できます。こうすると大域的なwrapやdefaulttranslateoptionオプションによって指定された既定の挙動を上書きできます。

untranslated

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

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

翻訳されていないタグにある翻訳できる文中のタグは、翻訳できる行折り返しタグとして扱われ、iの設定が除かれてwないしWがwrapオプションによって設定される点に注意してください。

defaulttranslateoption

translated、untranslated、break、inline、または placeholder のいずれでもないタグのデフォルトカテゴリ。

これはtranslatedに定義されているような文字の集合でこの設定は翻訳できるタグについてのみ妥当です。

派生モジュールの作成

  $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;

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

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

このモジュールの状態

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

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 v2.0以降の条項に基づき再頒布と変更を行えます（COPYINGファイルを参照）。