.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Locale::Po4a::Po 3pm"
.TH Locale::Po4a::Po 3pm "2018-12-09" "Po4a Tools" "Po4a Tools"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "名前"
.IX Header "名前"
Locale::Po4a::Po \- \s-1PO\s0 file 操作モジュール
.SH "書式"
.IX Header "書式"
.Vb 2
\&    use Locale::Po4a::Po;
\&    my $pofile=Locale::Po4a::Po\->new();
\&
\&    # Read PO file
\&    $pofile\->read(\*(Aqfile.po\*(Aq);
\&
\&    # Add an entry
\&    $pofile\->push(\*(Aqmsgid\*(Aq => \*(AqHello\*(Aq, \*(Aqmsgstr\*(Aq => \*(Aqbonjour\*(Aq,
\&                  \*(Aqflags\*(Aq => "wrap", \*(Aqreference\*(Aq=>\*(Aqfile.c:46\*(Aq);
\&
\&    # Extract a translation
\&    $pofile\->gettext("Hello"); # returns \*(Aqbonjour\*(Aq
\&
\&    # Write back to a file
\&    $pofile\->write(\*(Aqotherfile.po\*(Aq);
.Ve
.SH "説明"
.IX Header "説明"
Locale::Po4a::Po はメッセージカタログを操作できるようにするモジュールです。ファイル (通常 \fIpo\fR という拡張子)
を読み書きし、新しいエントリをその場で作成したり、文字列の翻訳要求があったときに作成できます。
.PP
\&\s-1PO\s0 フォーマットのメッセージカタログやその使い方に関する完全な説明は、gettext プログラム (\*(L"`\s-1PO\s0 ファイル\*(R"' ノード)
のドキュメントを参照してください。
.PP
このモジュールは po4a プロジェクトの一部です。このプロジェクトは (元々プログラムのメッセージを簡単に訳せるように設計された) \s-1PO\s0
ファイルを用い、すべてを翻訳するのを目標にしています。すべてというのは、(man ページ、info マニュアルといった)
ドキュメント、パッケージの説明、debconf テンプレート、そしてこの恩恵を受けられるだろうすべてものです。
.SH "このモジュールで使用できるオプション"
.IX Header "このモジュールで使用できるオプション"
.IP "\fB\-\-porefs\fR \fItype\fR[,\fBwrap\fR|\fBnowrap\fR]" 4
.IX Item "--porefs type[,wrap|nowrap]"
Specify the reference format. Argument \fItype\fR can be one of \fBnever\fR to not
produce any reference, \fBfile\fR to only specify the file without the line
number, \fBcounter\fR to replace line number by an increasing counter, and
\&\fBfull\fR to include complete references (default: full).
.Sp
引数にはコンマを続けた後に \fBwrap\fR または \fBnowrap\fR キーワードのどちらかを付けられます。デフォルトでは、リファレンスは 1
行で書き出されます。\fBwrap\fR オプションは、\fBgettext\fR ツール (\fBxgettext\fR や \fBmsgmerge\fR)
のようにリファレンスを複数行に折り返します。こちらのオプションの方がより気が利いているため、将来のリリースでデフォルトとなります。元の挙動のままにしておきたいユーザは、\fBnowrap\fR
オプションを使用できます。
.IP "\fB\-\-msgid\-bugs\-address\fR \fIemail@address\fR" 4
.IX Item "--msgid-bugs-address email@address"
msgid のバグレポートを送るアドレスをセットします。デフォルトでは、生成した \s-1POT\s0 ファイルに Report-Msgid-Bugs-To
フィールドはありません。
.IP "\fB\-\-copyright\-holder\fR \fIstring\fR" 4
.IX Item "--copyright-holder string"
\&\s-1POT\s0 ヘッダの著作権者 (copyright holder) をセットします。デフォルト値は \*(L"Free Software Foundation,
Inc.\*(R" です。
.IP "\fB\-\-package\-name\fR \fIstring\fR" 4
.IX Item "--package-name string"
\&\s-1POT\s0 ヘッダのパッケージ名をセットします。デフォルト値は \*(L"\s-1PACKAGE\*(R"\s0 です。
.IP "\fB\-\-package\-version\fR \fIstring\fR" 4
.IX Item "--package-version string"
\&\s-1POT\s0 ヘッダのパッケージバージョンをセットします。デフォルト値は \*(L"\s-1VERSION\*(R"\s0 です。
.SH "メッセージカタログ全体に関わる関数"
.IX Header "メッセージカタログ全体に関わる関数"
.IP "\fBnew()\fR" 4
.IX Item "new()"
新規メッセージカタログを作成します。引数を指定した場合、読み込む \s-1PO\s0 ファイルの名前として扱います。
.IP "read($)" 4
.IX Item "read($)"
(引数で与えた) \s-1PO\s0 ファイルを読み込みます。すでに読み込んだ既存エントリは削除しません。新しいものはカタログの最後に追加します。
.IP "write($)" 4
.IX Item "write($)"
与えられたファイルに現在のカタログを書き込みます。
.IP "write_if_needed($$)" 4
.IX Item "write_if_needed($$)"
write と同様ですが、PO ファイルや \s-1POT\s0
ファイルがすでに存在している場合、オブジェクトを一時ファイルに書き出し、既存のファイルを比較して更新が必要かどうかチェックします (これにより、行参照や
POT-Creation-Date フィールドの更新しかない更新を防ぎます)。
.IP "gettextize($$)" 4
.IX Item "gettextize($$)"
この関数は、オリジナルと翻訳済みの二つのカタログから、一つの翻訳済みメッセージカタログを生成します。この処理は、\fBpo4a\fR\|(7) の
\&\fIgettext 化: どのように動作しますか?\fR 節で解説します。
.IP "filter($)" 4
.IX Item "filter($)"
この関数は、既存のものからカタログを抽出します。与えたファイルへの参照があるエントリのみが、結果のカタログに抽出されます。
.Sp
この関数は、引数をパースし、Perl の関数定義に変換し、この定義を評価し、この関数が true を返すフィールドのみをフィルタします。
.Sp
私はときどき Perl が好きです ;)
.IP "\fBto_utf8()\fR" 4
.IX Item "to_utf8()"
\&\s-1PO\s0 の msgstr を \s-1UTF\-8\s0 に再コード化します。PO ファイルで文字セット (\*(L"\s-1CHARSET\*(R"\s0 の値) が指定されていない場合、すでに
\&\s-1UTF\-8\s0 の場合、あるいは \s-1ASCII\s0 の場合には何もしません。
.SH "翻訳にメッセージカタログを使用する関数"
.IX Header "翻訳にメッセージカタログを使用する関数"
.IP "gettext($%)" 4
.IX Item "gettext($%)"
現在のカタログから、引数で与えた文字列の翻訳を取得します。文字列が見つからなかった場合、この関数はオリジナル (未翻訳) の文字列を返します。
.Sp
翻訳する文字列の後に、追加引数のハッシュを渡せます。以下のエントリが有効です:
.RS 4
.IP "\fBwrap\fR" 4
.IX Item "wrap"
文字列中の空白は重要でないとして扱うかどうかを示す真偽値です。yes ならば、この関数は、翻訳を探す前の文字列を納め、結果を折り返します。
.IP "\fBwrapcol\fR" 4
.IX Item "wrapcol"
改行を行う幅です (デフォルト: 76)。
.RE
.RS 4
.RE
.IP "\fBstats_get()\fR" 4
.IX Item "stats_get()"
前回 \fBstats_clear()\fR が呼ばれたときからの gettext のヒット率統計を返します。msgfmt \-\-statistic
が表示する統計とは、異なることにご注意ください。msgfmt はファイルの状態をレポートしますが、ここでは \s-1PO\s0
ファイルの最近の利用についての統計です。以下に使い方の例を示します:
.Sp
.Vb 1
\&    [翻訳する際の PO ファイルの使用例]
\&
\&    ($percent,$hit,$queries) = $pofile\->stats_get();
\&    print "So far, we found translations for $percent\e%  ($hit of $queries) of strings.\en";
.Ve
.IP "\fBstats_clear()\fR" 4
.IX Item "stats_clear()"
gettext のヒットに関する統計をクリアします。
.SH "メッセージカタログを生成する関数"
.IX Header "メッセージカタログを生成する関数"
.IP "push(%)" 4
.IX Item "push(%)"
現在のカタログの最後に新しいエントリを追加します。引数は、ハッシュテーブルの形である必要があります。有効なキーは以下の通りです:
.RS 4
.IP "\fBmsgid\fR" 4
.IX Item "msgid"
オリジナル言語の文字列。
.IP "\fBmsgstr\fR" 4
.IX Item "msgstr"
翻訳。
.IP "\fBreference\fR" 4
.IX Item "reference"
この文字列がどこにあったかを示します。例えば、file.c:46 ('file.c' の 46 行目)
といった具合です。複数ある場合は、空白区切りのリストとなります。
.IP "\fBcomment\fR" 4
.IX Item "comment"
手で (翻訳者が) 追加したコメントです。フォーマットは自由です。
.IP "\fBautomatic\fR" 4
.IX Item "automatic"
文字列抽出プログラムが自動的に追加したコメントです。詳細は、\fBxgettext\fR プログラムの \fB\-\-add\-comments\fR
オプションを参照してください。
.IP "\fBflags\fR" 4
.IX Item "flags"
このエントリで定義するフラグのスペース区切りリストです。
.Sp
有効なフラグは、\fBc\-text\fR, \fBpython-text\fR, \fBlisp-text\fR, \fBelisp-text\fR,
\&\fBlibrep-text\fR, \fBsmalltalk-text\fR, \fBjava-text\fR, \fBawk-text\fR,
\&\fBobject-pascal-text\fR, \fBycp-text\fR, \fBtcl-text\fR, \fBwrap\fR, \fBno-wrap\fR,
\&\fBfuzzy\fR です。
.Sp
それぞれの意味については gettext のドキュメントを参照してください。
.IP "\fBtype\fR" 4
.IX Item "type"
これはほとんど内部引数で、ドキュメントを gettext 化する際に使用します。ここでの考え方は、オリジナルと翻訳の両方を \s-1PO\s0
オブジェクトに入れるためパースし、片方の msgid を msgid に、もう一方の msgid を msgstr
としてマージする、というものです。確実にうまく処理するように、PO オブジェクトの各 msgid は、その構造 (DocBook では \*(L"chapt\*(R",
\&\*(L"sect1\*(R", \*(L"p\*(R" など) から type を与えられます。文字列の type
が一致しない場合、双方のファイルが同じ構造を共有していないことになり、プロセスはエラーを通知します。
.Sp
この情報は、文字列を翻訳する際に文脈情報を翻訳者に与えるため、PO ファイルの自動コメントに書き込まれます。
.IP "\fBwrap\fR" 4
.IX Item "wrap"
化粧をする再フォーマットによってホワイトスペースをめちゃめちゃにするかどうかを示す真偽値です。true ならば、文字列は使用前に正規化されます。
.Sp
この情報は、PO ファイルに \fBwrap\fR フラグや \fBno-wrap\fR フラグを用いて書き込まれます。
.IP "\fBwrapcol\fR" 4
.IX Item "wrapcol"
改行を行う幅です (デフォルト: 76)。
.Sp
この情報は \s-1PO\s0 ファイルに書き込まれません。
.RE
.RS 4
.RE
.SH "その他の関数"
.IX Header "その他の関数"
.IP "\fBcount_entries()\fR" 4
.IX Item "count_entries()"
カタログ内のエントリ数 (ヘッダ含まず) を返します。
.IP "\fBcount_entries_doc()\fR" 4
.IX Item "count_entries_doc()"
ドキュメント内のエントリ数を返します。ある文字列がドキュメント内に複数回現れる場合、複数回カウントします.
.IP "equals_msgid(po)" 4
.IX Item "equals_msgid(po)"
Returns ($uptodate, \f(CW$diagnostic\fR) with \f(CW$uptodate\fR indicating whether all msgid
of the current po file are also present in the one passed as parameter (all
other fields are ignored in the file comparison).  Informally, if \f(CW$uptodate\fR
returns false, then the po files would be changed when going through
\&\fBpo4a\-updatepo\fR.
.Sp
If \f(CW$uptodate\fR is false, then \f(CW$diagnostic\fR contains a diagnostic of why this is
so.
.IP "msgid($)" 4
.IX Item "msgid($)"
与えた数の msgid が返ります。
.IP "msgid_doc($)" 4
.IX Item "msgid_doc($)"
ドキュメント内の、与えられた位置の msgid を返します。
.IP "\fBget_charset()\fR" 4
.IX Item "get_charset()"
\&\s-1PO\s0 ヘッダで指定した 文字セットを返します。設定されていない場合、 \*(L"\s-1CHARSET\*(R"\s0 を返します。
.IP "set_charset($)" 4
.IX Item "set_charset($)"
\&\s-1PO\s0 ヘッダの文字セットに、第一引数に指定した値を設定します。この関数が呼ばれない場合
(かつ文字セットを指定したファイルが読み込まれない場合)、デフォルト値は \*(L"\s-1CHARSET\*(R"\s0
のままになります。この値は、このモジュールの振る舞いを変更せず、ヘッダのそのフィールドに設定するためだけに使用し、\fBget_charset()\fR
にその値を返します。
.SH "著者"
.IX Header "著者"
.Vb 2
\& Denis Barbier <barbier@linuxfr.org>
\& Martin Quinson (mquinson#debian.org)
.Ve
.SH "訳者"
.IX Header "訳者"
.Vb 2
\& 倉澤 望 <nabetaro@debian.or.jp>
\& Debian JP Documentation ML <debian\-doc@debian.or.jp>
.Ve