po4av0.73

LOCALE::PO4A::XML.3PM

Section: User Contributed Perl Documentation (1)
Updated: 2024-06-17
Index Return to Main Contents
 

名前

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 文法があった場合のこのモジュールの振る舞いを定義します。以下の値を取り得ます。
fail
既定値です。エラーを表示して終了します。
warn
処理を継続し警告を表示します。
silent
何も警告を表示せずに処理を継続します。

このオプションを使用する場合は注意してください。通常、入力ファイルを修正するのをお勧めします。

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オプションによって指定された既定の挙動を上書きできます。

w
翻訳し、内容を再改行するタグです。
W
翻訳を行うが改行を行うべきでない内容のコンマ区切りリストです。
i
インラインで訳されるべきタグです。
p
プレースホルダとして翻訳されるべきタグです。

内部的にはXML解析器はw、W、i、pの4オプションのみを考慮します。

* breakに挙げられたタグはwrapオプションによってwないしWに設定されます。

* inlineに挙げられたタグはiに設定されます。

* placeholderに挙げられたタグはpに設定されます。

* untranslatedに挙げられたタグはこれらのオプションが設定されません。

po4aを実行することによる実際の内部的な変数の挙動は--debugオプションで確かめられます。

例：W<chapter><title>

タグはtranslated オプションや untranslated オプションの設定文字列で書き並べるべきだということに注意してください。

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

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

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

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

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

 

派生モジュールの作成

 

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

最も簡単なカスタマイズとして、パーサに変換させたいタグや属性を定義できます。これを初期化関数で行うべきです。まず、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 の各オプションを使用するべきです。このオプションがあると、コマンドラインオプションを使って利用者がそのモジュールの既定の挙動を上書きすることができます。  

コマンドラインオプションで既定の挙動を上書きする

このxmlモジュールや派生モジュールの既定の挙動が好みでなければ、コマンドラインオプションを与えて挙動を変更することができます。

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() のフォーマットで) 受け取り、変換タグ (翻訳属性や変換が必要なすべて) を単一の文字列で返します。
 

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

 

タグに対する動作

get_path()
この関数は、ドキュメントのルートからの現在のタグのパスを、<html><body><p> の形態で返します。

タグ (括弧なし) の追加配列を引数に渡せます。要素パスは現在のパスの最後に追加されます。

tag_type()
この関数は、tag_types リストから、入力ストリームの次のタグに一致するもののインデックスを返します。入力ファイルの最後の場合は、-1 を返します。

ここではタグは<から始まり>で終わる構造を持ち複数行を含められます。

これは入力の文書データと参照を持つ配列"@{$self->{TT}{doc_in}}"に対して、"$self->shiftline()"及び"$self->unshiftline($$)"を介して動作します。

extract_tag($$)
この関数は、入力ストリームから、開始部と終了部を除いた次のタグを、入力ファイルからの参照を管理するため配列の形で返します。パラメータは以下の二つがあります。タグのタイプ (tag_type が返す形) と入力ストリームから削除するかどうかを指定する真偽値です。

これは入力の文書データと参照を持つ配列"@{$self->{TT}{doc_in}}"に対して、"$self->shiftline()"及び"$self->unshiftline($$)"を介して動作します。

get_tag_name(@)
この関数は、extract_tag が返した配列を引数で受け取り、受け取ったタグの名前を返します。
breaking_tag()
この関数は、入力ストリームの次のタグが、改行タグかそうでない (インラインタグ) かを真偽値で返します。入力ストリームは変化しません。
treat_tag()
この関数は入力ストリームから次のタグを翻訳します。タグタイプのカスタム翻訳関数ごとに使用します。

これは入力の文書データと参照を持つ配列"@{$self->{TT}{doc_in}}"に対して、"$self->shiftline()"及び"$self->unshiftline($$)"を介して動作します。

tag_in_list($@)
この関数は、第一引数 (タグ階層) が第二引数 (タグのリストやタグ階層) にあるタグと一致するかどうかの文字列の値を返します。一致しない場合、0 を返します。そうでない場合、一致したタグのオプション (タグの前の文字列) か 1 (オプションがない場合) を返します。
 

属性に対する動作

treat_attributes(@)
この関数は、タグの属性の翻訳を扱います。/ 終了マークで始まらないタグを受けとり、属性を探し、翻訳可能のもの（モジュールオプション attributes で指定されたもの）を翻訳します。翻訳済みのタグと共に純粋な文字列を返します。
 

タグ付けされた内容を扱う

treat_content()
この関数は入力ストリームから次の（インラインではない）改行タグまでのテキストを翻訳します。そのテキストはそれぞれのタグの種類で固有の翻訳関数を使って翻訳します。

これは入力の文書データと参照を持つ配列"@{$self->{TT}{doc_in}}"に対して、"$self->shiftline()"及び"$self->unshiftline($$)"を介して動作します。

 

モジュールオプションに対する動作

treat_options()
この関数は、内部構造をモジュールのオプションの (コマンドラインや initialize 関数で指定した) タグ、属性、インラインデータで満たします。
 

入力ドキュメントからのテキスト取得

get_string_until($%)
この関数は入力ドキュメントから、第一引数に指定した文字列が見つかるまで、行 (とその参照) を配列で返します。第二引数は、オプションのハッシュです。値が 0 は無効を表し、1 は有効を表します。

以下のオプションが有効です:

include
検索したテキストを含む配列を返すようになります
remove
入力から返ったストリームを削除します
unquoted
検索テキストが、クォート外にあることを保証します
regex
これは最初の引数が純粋な文字列ではなく正規表現であることを示すものです
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 v2.0以降の条項に基づき再頒布と変更を行えます（COPYINGファイルを参照）。

 

Index

名前
説明
PO4A::XML を使った翻訳
このモジュールで使用できるオプション
派生モジュールの作成
翻訳するタグや属性の定義
コマンドラインオプションで既定の挙動を上書きする
found_string 関数の上書き
タグタイプの変更 (TODO)
派生パーサ作成時に使用する内部関数
タグに対する動作
属性に対する動作
タグ付けされた内容を扱う
モジュールオプションに対する動作
入力ドキュメントからのテキスト取得
このモジュールの状態
TODO リスト
関連項目
著者
訳者
著作権とライセンス
This document was created by using the manual pages.
Time: 20:30:48 GMT, June 17, 2024
català Deutsch English Esperanto español français hrvatski Magyar Italiano 日本語 Bokmål Nederlands polski Português Português (Brasil) Русский српски језик српски језик український 简体中文 简体中文 (how to set the default document language)