plucky (3) Locale::Po4a::Xml.3pm.gz

Provided by: po4a_0.73-2ubuntu1_all bug

名前

       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>) ことができます。

           タグは、breakinlineplaceholdercustomtag 設定文字列のうち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>) ことができます。

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

           w   翻訳し、内容を再改行するタグです。

           W   翻訳を行うが改行を行うべきでない内容のコンマ区切りリストです。

           i   インラインで訳されるべきタグです。

           p   プレースホルダとして翻訳されるべきタグです。

           内部的にはXML解析器はwWipの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ないしWwrapオプションによって設定される点に注意してください。

       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ファイルを参
       照)。