Locale::Po4a::Po(3pm)

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

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

    # Read PO file
    $pofile->read('file.po');

    # Add an entry
    $pofile->push('msgid' => 'Hello', 'msgstr' => 'bonjour',
                  'flags' => "wrap", 'reference'=>'file.c:46');

    # Extract a translation
    $pofile->gettext("Hello"); # returns 'bonjour'

    # Write back to a file
    $pofile->write('otherfile.po');

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

For a more complete description of message catalogs in the PO format and their use, please refer to the info documentation of the gettext program (node "`PO Files"').

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

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

--porefs type[,wrap|nowrap]
    リファレンスフォーマットを指定します。引数 type には、いずれのリファレンスも提供しない none、行番号を明示しない noline (正確に言うと行番号は 1 に置換されます)、行番号をカウントアップする counter、完全なリファレンスを含む full のどれか一つを指定できます。

    引数にはコンマで続けて、wrap か nowrap というキーワードを後に付けられます。デフォルトでは、リファレンスを 1 行で書き出します。wrap オプションは、gettext ツール (xgettext や msgmerge) のように、リファレンスを複数行に折り返します。このオプションは、より気が利いているため、将来のリリースでデフォルトとなります。元の挙動のままにしておきたいユーザは、nowrap オプションを使用できます。

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

--copyright-holder string
    POT ヘッダの著作権者 (copyright holder) をセットします。デフォルト値は "Free Software Foundation, Inc." です。

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

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

Functions concerning entire message catalogs

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

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

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

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

gettextize($$)
    この関数は、オリジナルと翻訳済みの二つのカタログから、一つの翻訳済みメッセージカタログを生成します。この処理は、po4a(7) の gettext 化: どのように動作しますか? セクションで解説します。

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

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

    私は Perl が大好きです ;)

to_utf8()
    PO の msgstr を UTF-8 に再コード化します。PO ファイルで文字セットが指定されていない場合 ("CHARSET" の値) や、すでに UTF-8 か ASCII の場合は何もしません。

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

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

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

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

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

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

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

        ($percent,$hit,$queries) = $pofile->stats_get();
        print "So far, we found translations for $percent\%  ($hit of $queries) of strings.\n";

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

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

push(%)
    現在のカタログの最後に、新しいエントリを 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
        見栄えに関する再整形を行い、空白をごちゃごちゃにしてもいいかどうかの真偽値です。使用してよい場合、使用する前の文字列を納めます。

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

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

        この情報は PO ファイルに書き込まれません。

その他の関数

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

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

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

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

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

set_charset($)
    POヘッダの文字セットに、第一引数に指定した値を設定します。この関数が呼ばれない場合 (かつ文字セットを指定したファイルが読み込まれない場合)、デフォルト値は "CHARSET" のままになります。この値は、このモジュールの振る舞いを変更せず、ヘッダのそのフィールドに設定するためだけに使用し、get_charset() にその値を返します。

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

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