名前¶

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"); # 'bonjour' を返す
    # ファイルに書き戻す
    $pofile->write('otherfile.po');

説明¶

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

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

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

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

--porefs type

参照形式を指定します。引数 type は、いずれの参照も生成しない never かファイルを指定するのみで行番号を指定しない file かカウンタを増加させることで行番号を置き換える 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($%)

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

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

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(%)

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

その他の関数¶

count_entries()

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

count_entries_doc()

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

msgid($)

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

msgid_doc($)

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

type_doc($)

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

get_charset()

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

gettext_wrap_opts($)

A small utility function that returns a string with appropriate "--no-wrap"/"--width" gettext utilities' options corresponding to the given wrap-po value.

each_message

This method iterates over each message in the PO file and processes it. It takes a subroutine reference and executes it with two arguments: 1) the "msgid" and 2) a hash reference containing the message content, which includes fields such as "msgstr".

replant

This method takes two parameters: the current "msgid" and the new "msgid". It removes the entry with the current "msgid" from the PO instance and reinserts it under the new "msgid" value.

message_by_document_position

This method takes a document position and returns the matching message as a list containing three elements: the "msgid", the "msgctxt", and the message content (which includes fields such as "msgstr").

message_by_msgid

This method takes a "msgid" and an optional "msgctxt", and returns the first matching message content, which includes fields such as "msgstr". If no "msgctxt" is provided, an empty string value is used. If no message entry is found with the given context, the method falls back to searching for a message without context.

著者¶

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

訳者¶

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