
        *****************************************************
        *           GENERATED FILE, DO NOT EDIT             *
        * THIS IS NO SOURCE FILE, BUT RESULT OF COMPILATION *
        *****************************************************

This file was generated by po4a(7). Do not store it (in VCS, for example),
but store the PO file used as source file by po4a-translate.

In fact, consider this as a binary, and the PO file as a regular .c file:
If the PO get lost, keeping this translation up-to-date will be harder.

=encoding UTF-8

=head1 名前

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

=head1 書式

    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');

=head1 説明

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

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

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

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

=over 4

=item B<--porefs> I<type>

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

=item B<--wrap-po> B<no>|B<newlines>|I<number>（既定値：76）

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

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

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

=item B<--msgid-bugs-address> I<email@address>

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

=item B<--copyright-holder> I<string>

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

=item B<--package-name> I<string>

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

=item B<--package-version> I<string>

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

=back

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

=over 4

=item new()

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

=item read($)

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

=item write($)

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

=item write_if_needed($$)

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

=item filter($)

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

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

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

=item to_utf8()

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

=back

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

=over 4

=item gettext($%)

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

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

=over 

=item B<wrap>

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

=item B<wrapcol>

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

=back

=item 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";

=item stats_clear()

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

=back

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

=over 4

=item push(%)

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

=over 4

=item B<msgid>

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

=item B<msgstr>

翻訳。

=item B<reference>

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

=item B<comment>

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

=item B<automatic>

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

=item B<flags>

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

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

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

=item B<type>

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

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

=item B<wrap>

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

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

=item B<wrapcol>

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

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

=back

=back

=head1 その他の関数

=over 4

=item count_entries()

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

=item count_entries_doc()

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

=item msgid($)

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

=item msgid_doc($)

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

=item type_doc($)

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

=item get_charset()

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

=item set_charset($)

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

=back

=head1 著者

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


=head1 訳者

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

