plucky (3) Locale::Po4a::Po.3pm.gz
名前
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>