名前

       Locale::Po4a::Po - PO file 操作モジュール

書式

           use Locale::Po4a::Po;
           my $pofile=Locale::Po4a::Po->new();

           # POファイルを読みます
           $pofile->read('file.po');

           # 項目を加えます
           $pofile->push('msgid' => 'Hello', 'msgstr' => 'bonjour',
                         'flags' => "wrap", 'reference'=>'file.c:46');

           # 翻訳を抽出します
           $pofile->gettext("Hello"); # returns 'bonjour'

           # ファイルに書き戻します
           $pofile->write('otherfile.po');

説明

       Locale::Po4a::Po はメッセージカタログを操作できるようにするモジュールです。ファイル (通常
       po という拡張子) を読み書きし、新しいエントリをその場で作成したり、文字列の翻訳要求があっ
       たときに作成できます。

       PO フォーマットのメッセージカタログやその使い方に関する完全な説明は、gettext プログラム
       ("`PO ファイル"' ノード) のドキュメントを参照してください。

       このモジュールは po4a プロジェクトの一部です。このプロジェクトは (元々プログラムのメッセー
       ジを簡単に訳せるように設計された) PO ファイルを用い、すべてを翻訳するのを目標にしていま
       す。すべてというのは、(man ページ、info マニュアルといった) ドキュメント、パッケージの説
       明、debconf テンプレート、そしてこの恩恵を受けられるだろうすべてものです。

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

       --porefs type
           参照形式を指定します。引数 type は、いずれの参照も生成しない none、ファイルを指定する
           のみで行番号を指定しない noline、カウンタを増加させることで行番号を置き換える
           counter、完全な参照を含む full のいずれかを指定できます（既定値：full）。

       --wrap-po no|newlines|number（既定値：76）
           poファイルの行の折り返し方法を指定します。これにより、適切に折り返されているがgitの競
           合につながる可能性のあるファイルか、もしくは自動的に処理しやすいものの人間にとっては読
           みにくいファイルかのいずれかを選択できます。

           歴史的な理由から、gettextスイートは整形を理由にpoファイルを77行目で折り返すことで再整
           形します。このオプションはpo4aの振舞いを指定するものです。数値が指定された場合、po4aは
           この行中の位置以降にある内容中の改行箇所でpoファイルを折り返します。newlinesが指定され
           た場合、po4aは内容中の改行箇所でのみmsgidとmsgstrを分割します。noが指定された場
           合、po4aはpoファイルをまったく折り返しません。参照コメントはpo4aが内部的に用い
           るgettextツールによって常に折り返されます。

           このオプションは、msgidとmsgstrの行の折り返し方法、すなわちこれらの文字列の内容に改行
           を追加する方法には影響しないことに注意してください。

       --msgid-bugs-address Eメール@アドレス
           msgid のバグレポートを送るアドレスをセットします。デフォルトでは、生成した POT ファイ
           ルに Report-Msgid-Bugs-To フィールドはありません。

       --copyright-holder 文字列
           POT ヘッダの著作権者 (copyright holder) を設定します。既定値は "Free Software
           Foundation, Inc." です。

       --package-name string
           POT ヘッダのパッケージ名をセットします。デフォルト値は "PACKAGE" です。

       --package-version string
           POT ヘッダのパッケージバージョンをセットします。デフォルト値は "VERSION" です。

メッセージカタログ全体に関わる関数

       new()
           新規メッセージカタログを作成します。引数を指定した場合、読み込む PO ファイルの名前とし
           て扱います。

       read($)
           (引数で与えた) PO ファイルを読み込みます。すでに読み込んだ既存エントリは削除しませ
           ん。新しいものはカタログの最後に追加します。

       write($)
           与えられたファイルに現在のカタログを書き込みます。

       write_if_needed($$)
           write と同様ですが、PO ファイルや POT ファイルがすでに存在している場合、オブジェクトを
           一時ファイルに書き出し、既存のファイルを比較して更新が必要かどうかチェックします (これ
           により、行参照や POT-Creation-Date フィールドの更新しかない更新を防ぎます)。

       filter($)
           この関数は、既存のものからカタログを抽出します。与えたファイルへの参照があるエントリの
           みが、結果のカタログに抽出されます。

           この関数は、引数をパースし、Perl の関数定義に変換し、この定義を評価し、この関数が true
           を返すフィールドのみをフィルタします。

           私はときどき Perl が好きです ;)

翻訳にメッセージカタログを使用する関数

       gettext($%)
           現在のカタログから、引数で与えた文字列の翻訳を取得します。文字列が見つからなかった場
           合、この関数はオリジナル (未翻訳) の文字列を返します。

           翻訳する文字列の後に、追加引数のハッシュを渡せます。以下のエントリが有効です:

           wrap
               文字列中の空白は重要でないとして扱うかどうかを示す真偽値です。yes ならば、この関数
               は、翻訳を探す前の文字列を納め、結果を折り返します。

           wrapcol
               改行を行う幅です (デフォルト: 76)。

       stats_get()
           前回 stats_clear() が呼ばれたときからの gettext のヒット率統計を返します。msgfmt
           --statistic が表示する統計とは、異なることにご注意ください。msgfmt はファイルの状態を
           レポートしますが、ここでは PO ファイルの最近の利用についての統計です。以下に使い方の例
           を示します:

               [翻訳する際の PO ファイルの使用例]

               ($percent,$hit,$queries) = $pofile->stats_get();
               print "ここまでで$percent\%（$queries中$hit）の文字列が翻訳されています。\n";

       stats_clear()
           gettext のヒットに関する統計をクリアします。

メッセージカタログを生成する関数

       push(%)
           現在のカタログの最後に新しいエントリを追加します。引数は、ハッシュテーブルの形である必
           要があります。有効なキーは以下の通りです:

           msgid
               オリジナル言語の文字列。

           msgstr
               翻訳。

           reference
               この文字列がどこにあったかを示します。例えば、file.c:46 ('file.c' の 46 行目) と
               いった具合です。複数ある場合は、空白区切りのリストとなります。

           comment
               手で (翻訳者が) 追加したコメントです。フォーマットは自由です。

           automatic
               文字列抽出プログラムが自動的に追加したコメントです。詳細は、xgettext プログラムの
               --add-comments オプションを参照してください。

           flags
               このエントリで定義するフラグのスペース区切りリストです。

               有効なフラグは、c-text, python-text, lisp-text, elisp-text, librep-text,
               smalltalk-text, java-text, awk-text, object-pascal-text, ycp-text, tcl-text, wrap,
               no-wrap, fuzzy です。

               それぞれの意味については gettext のドキュメントを参照してください。

           type
               これはほとんど内部引数で、ドキュメントを gettext 化する際に使用します。ここでの考
               え方は、オリジナルと翻訳の両方を PO オブジェクトに入れるためパースし、片方の msgid
               を msgid に、もう一方の msgid を msgstr としてマージする、というものです。確実にう
               まく処理するように、PO オブジェクトの各 msgid は、その構造 (DocBook では "chapt",
               "sect1", "p" など) から type を与えられます。文字列の type が一致しない場合、双方
               のファイルが同じ構造を共有していないことになり、プロセスはエラーを通知します。

               この情報は、文字列を翻訳する際に文脈情報を翻訳者に与えるため、PO ファイルの自動コ
               メントに書き込まれます。

           wrap
               化粧をする再フォーマットによってホワイトスペースをめちゃめちゃにするかどうかを示す
               真偽値です。true ならば、文字列は使用前に正規化されます。

               この情報は、PO ファイルに wrap フラグや no-wrap フラグを用いて書き込まれます。

           wrapcol
               無視されます。キーは後方互換性のため維持されます。

その他の関数

       count_entries()
           カタログ内のエントリ数 (ヘッダ含まず) を返します。

       count_entries_doc()
           ドキュメント内のエントリ数を返します。ある文字列がドキュメント内に複数回現れる場合、複
           数回カウントします.

       msgid($)
           与えた数の msgid が返ります。

       msgid_doc($)
           ドキュメント内の、与えられた位置の msgid を返します。

       type_doc($)
           文書中の与えられた位置にあるmsgidの型を返します。これは恐らくgettextizationで唯一役に
           立つものでしょう。またその型は{$msgid}{'type'}から別れて保管されます。なぜなら後者の場
           所はマスター文書で$msgidが重複したときに別の型によって上書きされかねないからです。

       get_charset()
           PO ヘッダで指定した 文字セットを返します。設定されていない場合、 "UTF-8" を返します。

著者

        Denis Barbier <barbier@linuxfr.org>
        Martin Quinson (mquinson#debian.org)

訳者

        倉澤 望 <nabetaro@debian.or.jp>
        Debian JP Documentation ML <debian-doc@debian.or.jp>