.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" 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
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    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 1"
.TH LOCALE::PO4A::PO.3PM 1 2024-06-26 "perl v5.38.2" "User Contributed Perl Documentation"
.\" 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 \- PO file 操作モジュール
.SH 書式
.IX Header "書式"
.Vb 2
\&    use Locale::Po4a::Po;
\&    my $pofile=Locale::Po4a::Po\->new();
\&
\&    # POファイルを読みます
\&    $pofile\->read(\*(Aqfile.po\*(Aq);
\&
\&    # 項目を加えます
\&    $pofile\->push(\*(Aqmsgid\*(Aq => \*(AqHello\*(Aq, \*(Aqmsgstr\*(Aq => \*(Aqbonjour\*(Aq,
\&                  \*(Aqflags\*(Aq => "wrap", \*(Aqreference\*(Aq=>\*(Aqfile.c:46\*(Aq);
\&
\&    # 翻訳を抽出します
\&    $pofile\->gettext("Hello"); # returns \*(Aqbonjour\*(Aq
\&
\&    # ファイルに書き戻します
\&    $pofile\->write(\*(Aqotherfile.po\*(Aq);
.Ve
.SH 説明
.IX Header "説明"
Locale::Po4a::Po はメッセージカタログを操作できるようにするモジュールです。ファイル (通常 \fIpo\fR という拡張子) を読み書きし、新しいエントリをその場で作成したり、文字列の翻訳要求があったときに作成できます。
.PP
PO フォーマットのメッセージカタログやその使い方に関する完全な説明は、gettext プログラム ("`PO ファイル"' ノード) のドキュメントを参照してください。
.PP
このモジュールは po4a プロジェクトの一部です。このプロジェクトは (元々プログラムのメッセージを簡単に訳せるように設計された) PO ファイルを用い、すべてを翻訳するのを目標にしています。すべてというのは、(man ページ、info マニュアルといった) ドキュメント、パッケージの説明、debconf テンプレート、そしてこの恩恵を受けられるだろうすべてものです。
.SH このモジュールで使用できるオプション
.IX Header "このモジュールで使用できるオプション"
.IP "\fB\-\-porefs\fR \fItype\fR" 4
.IX Item "--porefs type"
参照形式を指定します。引数 \fItype\fR は、いずれの参照も生成しない \fBnone\fR、ファイルを指定するのみで行番号を指定しない \fBnoline\fR、カウンタを増加させることで行番号を置き換える \fBcounter\fR、完全な参照を含む \fBfull\fR のいずれかを指定できます（既定値：full）。
.IP "\fB\-\-wrap\-po\fR \fBno\fR|\fBnewlines\fR|\fInumber\fR（既定値：76）" 4
.IX Item "--wrap-po no|newlines|number（既定値：76）"
poファイルの行の折り返し方法を指定します。これにより、適切に折り返されているがgitの競合につながる可能性のあるファイルか、もしくは自動的に処理しやすいものの人間にとっては読みにくいファイルかのいずれかを選択できます。
.Sp
歴史的な理由から、gettextスイートは整形を理由にpoファイルを77行目で折り返すことで再整形します。このオプションはpo4aの振舞いを指定するものです。数値が指定された場合、po4aはこの行中の位置以降にある内容中の改行箇所でpoファイルを折り返します。\fBnewlines\fRが指定された場合、po4aは内容中の改行箇所でのみmsgidとmsgstrを分割します。\fBno\fRが指定された場合、po4aはpoファイルをまったく折り返しません。参照コメントはpo4aが内部的に用いるgettextツールによって常に折り返されます。
.Sp
このオプションは、msgidとmsgstrの行の折り返し方法、すなわちこれらの文字列の内容に改行を追加する方法には影響しないことに注意してください。
.IP "\fB\-\-msgid\-bugs\-address\fR \fIEメール@アドレス\fR" 4
.IX Item "--msgid-bugs-address Eメール@アドレス"
msgid のバグレポートを送るアドレスをセットします。デフォルトでは、生成した POT ファイルに Report-Msgid-Bugs-To フィールドはありません。
.IP "\fB\-\-copyright\-holder\fR \fI文字列\fR" 4
.IX Item "--copyright-holder 文字列"
POT ヘッダの著作権者 (copyright holder) を設定します。既定値は "Free Software Foundation, Inc." です。
.IP "\fB\-\-package\-name\fR \fIstring\fR" 4
.IX Item "--package-name string"
POT ヘッダのパッケージ名をセットします。デフォルト値は "PACKAGE" です。
.IP "\fB\-\-package\-version\fR \fIstring\fR" 4
.IX Item "--package-version string"
POT ヘッダのパッケージバージョンをセットします。デフォルト値は "VERSION" です。
.SH メッセージカタログ全体に関わる関数
.IX Header "メッセージカタログ全体に関わる関数"
.IP \fBnew()\fR 4
.IX Item "new()"
新規メッセージカタログを作成します。引数を指定した場合、読み込む PO ファイルの名前として扱います。
.IP read($) 4
.IX Item "read($)"
(引数で与えた) PO ファイルを読み込みます。すでに読み込んだ既存エントリは削除しません。新しいものはカタログの最後に追加します。
.IP write($) 4
.IX Item "write($)"
与えられたファイルに現在のカタログを書き込みます。
.IP write_if_needed($$) 4
.IX Item "write_if_needed($$)"
write と同様ですが、PO ファイルや POT ファイルがすでに存在している場合、オブジェクトを一時ファイルに書き出し、既存のファイルを比較して更新が必要かどうかチェックします (これにより、行参照や POT-Creation-Date フィールドの更新しかない更新を防ぎます)。
.IP filter($) 4
.IX Item "filter($)"
この関数は、既存のものからカタログを抽出します。与えたファイルへの参照があるエントリのみが、結果のカタログに抽出されます。
.Sp
この関数は、引数をパースし、Perl の関数定義に変換し、この定義を評価し、この関数が true を返すフィールドのみをフィルタします。
.Sp
私はときどき Perl が好きです ;)
.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 はファイルの状態をレポートしますが、ここでは PO ファイルの最近の利用についての統計です。以下に使い方の例を示します:
.Sp
.Vb 1
\&    [翻訳する際の PO ファイルの使用例]
\&
\&    ($percent,$hit,$queries) = $pofile\->stats_get();
\&    print "ここまでで$percent\e%（$queries中$hit）の文字列が翻訳されています。\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 化する際に使用します。ここでの考え方は、オリジナルと翻訳の両方を PO オブジェクトに入れるためパースし、片方の msgid を msgid に、もう一方の msgid を msgstr としてマージする、というものです。確実にうまく処理するように、PO オブジェクトの各 msgid は、その構造 (DocBook では "chapt", "sect1", "p" など) から 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"
無視されます。キーは後方互換性のため維持されます。
.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 msgid($) 4
.IX Item "msgid($)"
与えた数の msgid が返ります。
.IP msgid_doc($) 4
.IX Item "msgid_doc($)"
ドキュメント内の、与えられた位置の msgid を返します。
.IP type_doc($) 4
.IX Item "type_doc($)"
文書中の与えられた位置にあるmsgidの型を返します。これは恐らくgettextizationで唯一役に立つものでしょう。またその型は{$msgid}{'type'}から別れて保管されます。なぜなら後者の場所はマスター文書で$msgidが重複したときに別の型によって上書きされかねないからです。
.IP \fBget_charset()\fR 4
.IX Item "get_charset()"
PO ヘッダで指定した 文字セットを返します。設定されていない場合、 "UTF\-8" を返します。
.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