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 という拡張子)
を読み書きし、新しいエントリをその場で作成したり、文字列の翻訳要求があったときに作成できます。
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 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" です。
- new()
- 新規メッセージカタログを作成します。引数を指定した場合、読み込む
PO
ファイルの名前として扱います。
- read($)
- (引数で与えた) PO
ファイルを読み込みます。すでに読み込んだ既存エントリは削除しません。新しいものはカタログの最後に追加します。
- write($)
- 与えられたファイルに現在のカタログを書き込みます。
- write_if_needed($$)
- write
と同様ですが、PO
ファイルや POT
ファイルがすでに存在している場合、オブジェクトを一時ファイルに書き出し、既存のファイルを比較して更新が必要かどうかチェックします
(これにより、行参照や
POT-Creation-Date
フィールドの更新しかない更新を防ぎます)。
- filter($)
- この関数は、既存のものからカタログを抽出します。与えたファイルへの参照があるエントリのみが、結果のカタログに抽出されます。
この関数は、引数をパースし、Perl
の関数定義に変換し、この定義を評価し、この関数が
true
を返すフィールドのみをフィルタします。
私はときどき Perl
が好きです ;)
- to_utf8()
- PO の msgstr を UTF-8
に再コード化します。PO
ファイルで文字セット
("CHARSET" の値)
が指定されていない場合、すでに
UTF-8 の場合、あるいは
ASCII
の場合には何もしません。
- gettext($%)
- 現在のカタログから、引数で与えた文字列の翻訳を取得します。文字列が見つからなかった場合、この関数はオリジナル
(未翻訳)
の文字列を返します。
翻訳する文字列の後に、追加引数のハッシュを渡せます。以下のエントリが有効です:
- wrap
- 文字列中の空白は重要でないとして扱うかどうかを示す真偽値です。yes
ならば、この関数は、翻訳を探す前の文字列を納め、結果を折り返します。
- 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(%)
- 現在のカタログの最後に新しいエントリを追加します。引数は、ハッシュテーブルの形である必要があります。有効なキーは以下の通りです:
- 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
- 改行を行う幅です
(デフォルト: 76)。
この情報は PO
ファイルに書き込まれません。
- count_entries()
- カタログ内のエントリ数
(ヘッダ含まず)
を返します。
- count_entries_doc()
- ドキュメント内のエントリ数を返します。ある文字列がドキュメント内に複数回現れる場合、複数回カウントします.
- msgid($)
- 与えた数の msgid
が返ります。
- msgid_doc($)
- ドキュメント内の、与えられた位置の
msgid を返します。
- type_doc($)
- 文書中の与えられた位置にあるmsgidの型を返します。これは恐らくgettextizationで唯一役に立つものでしょう。またその型は{$msgid}{'type'}から別れて保管されます。なぜなら後者の場所はマスター文書で$msgidが重複したときに別の型によって上書きされかねないからです。
- get_charset()
- PO
ヘッダで指定した
文字セットを返します。設定されていない場合、
"UTF-8" を返します。
- set_charset($)
- PO
ヘッダの文字セットに、第一引数に指定した値を設定します。この関数が呼ばれない場合
(かつ文字セットを指定したファイルが読み込まれない場合)、デフォルト値は
"UTF-8"
のままになります。この値は、このモジュールの振る舞いを変更せず、ヘッダのそのフィールドに設定するためだけに使用し、
get_charset()
にその値を返します。
Denis Barbier <[email protected]>
Martin Quinson (mquinson#debian.org)
倉澤 望 <[email protected]>
Debian JP Documentation ML <[email protected]>