.\" Automatically generated by Pod::Man 4.14 (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
..
.\" 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 "PO4A 1p"
.TH PO4A 1p "2023-01-03" "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 "名前"
po4a \- \s-1PO\s0 ファイルと翻訳済みドキュメントの両方を一括更新
.SH "書式"
.IX Header "書式"
\&\fBpo4a\fR [\fIoptions\fR] \fIconfig_file\fR
.SH "説明"
.IX Header "説明"
po4a (\s-1PO\s0 for anything) は従来のgettextツールを使った文書翻訳の保守作業を容易にします。po4aの主な特徴は内容の翻訳を文書構造から切り離すところにあります。このプロジェクトのやさしい導入についてはページ\fBpo4a\fR\|(7)を参照してください。
.PP
実行すると \fBpo4a\fRは設定ファイルで指定された全ての文書ファイルを解析します。（翻訳を含む）POファイルを更新して文書にあらゆる変更を反映し、元のマスター文書の構造に（POファイルで見付かった）内容の翻訳を注入することで翻訳文書を生成します。
.PP
最初、POファイルには、元の文書からの翻訳すべき文字列のみが含まれています。このファイル形式により、\fBpo4a\fRが抽出した各段落に対して、翻訳者が手作業で翻訳を与えることができます。翻訳後に文書が変更された場合、\fBpo4a\fRは対応する翻訳をPOファイル内で「fuzzy」として印を付け、翻訳者による手動のレビューを要求します。翻訳者はいわゆる「補遺」を与えることもできます。これは例えば、誰が翻訳を行ったか、どのように誤りを報告するかなどを記載した追加内容です。
.PP
.Vb 10
\& master documents \-\-\-+\-\-\-\->\-\-\-\-\-\-\-\->\-\-\-\-\-\-\-\-\-+
\&  (doc authoring)    |                       |
\&                     V   (po4a executions)   >\-\-\-\-\-+\-\-> translated
\&                     |                       |     |     documents
\& existing PO files \-\->\-\-> updated PO files >\-+     |
\&      ^                            |               |
\&      |                            V               |
\&      +\-\-\-\-\-\-\-\-\-\-<\-\-\-\-\-\-\-\-\-<\-\-\-\-\-\-\-+               ^
\&       (manual translation process)                |
\&                                                   |
\& addendum \-\->\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
\&master documents: マスター文書
\&doc authoring: 文書執筆
\&po4a executions: po4aの実行
\&translations: 翻訳
\&existing PO files: 既存のPOファイル
\&updated PO files: 更新されたPOファイル
\&manual translation process: 手動の翻訳過程
\&addendum: 補遺
.Ve
.PP
\&\fBpo4a\fRの作業工程は、オープンソースプロジェクトに相応しい非同期型です。文書の執筆者は自分のペースでマスター文書を作成します。翻訳者はPOファイルの翻訳をレビューし、更新します。保守者は必要に応じて\fBpo4a\fRを再実行し、元文書への変更をPOファイルに反映し、最新の文書構造に最新の翻訳を注入することによって、更新された文書の翻訳を生成します。
.PP
既定では、翻訳文書はその内容の少なくとも80％が翻訳されたときに作成されます。翻訳されていないテキストは元の言語のまま残されます。そのため翻訳が完全でない場合、作成された文書には言語が混在することになります。80% のしきい値は、後述の \fI\-\-keep\fR オプションで変更することができます。ただし、100%でないと直ちに翻訳が無視されるのは、ほとんど利用者に見られないようになるため翻訳者の意欲をそぐかもしれませんし、一方であまりにも不完全な「翻訳」を表示するのはエンドユーザーが困ってしまうかもしれませんので、注意してください。
.PP
翻訳された文書ファイルをバージョン管理システムに保存するのは、自動生成されるもののためおそらく悪い考えでしょう。貴重なファイルはPOファイルであり、そこにこそ仲間の翻訳者達の苦労が詰まっているのです。また、weblateなどのオンラインプラットフォームで翻訳者と交流するのが楽だという人もいますが、これは当然ながら完全に任意です。
.SS "早分かり入門"
.IX Subsection "早分かり入門"
\&\fBfoo\fR という名前のプログラムを保守していて、そのプログラムには英語（ほとんどのオープンソースプロジェクトでの橋渡しとなる言語ですが、 \fBpo4a\fR はどの言語からでも、またどの言語へでも使えます）で書かれた man ページ \fIman/foo.1\fR があるとしましょう。いつだったか、誰かが \fIman/foo.de.1\fR という名前のドイツ語の翻訳を提供したなり立ち消えになったことがありました。ここで問題になっているのは、たった今文書にすべての言語で修正しなければならないような重大な誤解を招く情報が含まれているというバグ報告を受けましたが、ドイツ語を話せないので、翻訳ではなく元の文書を修正するしかないということです。そして今、別の貢献者がこれまた修得していない言語である日本語への翻訳を提供したいと言っています。
.PP
文書の保守の悪夢を解決するために、文書を\fBpo4a\fRに変換する時が来ました。必要なときに文書を更新したい、仲間の翻訳者達の作業を楽にしたい、そして、利用者が古くて誤解を招くような文書を目にすることがないようにしたい、そう思っていますよね。
.PP
変換には2つの工程が含まれます。po4aインフラの立ち上げと、以前のドイツ語翻訳を引き揚げるための変換です。この後者の部分は、以下のようにpo4a\-gettextizeを使用して行われます。\fBpo4a\-gettextize\fR\|(1) のドキュメントに詳述されているように、この過程が完全に自動化されることは稀ですが、一度完了すればドイツ語翻訳を含む \fBde.po\fR ファイルを po4a の作業工程に統合することができます。
.PP
.Vb 1
\&  po4a\-gettextize \-\-format man \-\-master foo.1 \-\-localized foo.de.1 \-\-po de.po
.Ve
.PP
それではpo4aを設定しましょう。適切なファイル配置を使うと設定ファイルはこのように単純になります。
.PP
.Vb 1
\& [po_directory] man/po4a/
\&
\& [type: man] man/foo.1 $lang:man/translated/foo.$lang.1
.Ve
.PP
これは、すべての（翻訳者の作業内容を含む）PO ファイルが \fIman/po4a/\fR ディレクトリにあり、マスターファイルは \fIman/foo.1\fR の 1 つだけであることを指定するものです。もし、複数のマスターファイルがあれば、2行目のような行がいくつもあることになります。このような行はそれぞれ、対応する翻訳ファイルをどこに書き込むかも指定します。ここでは、\fIman/foo.1\fR のドイツ語訳は \fIman/translated/foo.de.1\fR にあります。
.PP
\&\fBpo4a\fRの設定を完了するために最後に必要なものは、新しい翻訳を開始するために使用されるべきテンプレート材料を含むPOTファイルです。指定されたpo_directoryの中にに拡張子.potの空のファイルを作成するだけです（例：\fIman/po4a/foo.pot\fR）。そして\fBpo4a\fRはその中に期待される内容を詰め込みます。
.PP
この立ち上げでのファイルについておさらいすると次のようになります。
.PP
.Vb 7
\&  ├── man/
\&  │   ├── foo.1        <\- 英語で書かれた元のmanページ
\&  │   ├── po4a/
\&  │   │   ├── de.po    <\- gettextizationによるドイツ語訳のPO
\&  │   │   └── foo.pot  <\- 将来の翻訳に向けたPOTテンプレート（最初は空）
\&  │   └── translated/  <\- 翻訳が作られるディレクトリ
\&  └── po4a.cfg         <\-設定ファイル
.Ve
.PP
一度立ち上げれば、\fBpo4a\fRを実行すると、文書を解析し、POTテンプレートファイルを更新し、それを使ってPO翻訳ファイルを更新し、それを使って文書の翻訳ファイルを更新します。すべて1つのコマンドで。
.PP
.Vb 1
\&        po4a \-\-verbose po4a.cfg
.Ve
.PP
以上です。\fBpo4a\fRは完璧に設定されました。\fIman/foo.1\fRの誤りを修正したら、ドイツ語翻訳の問題のある段落は、英語の修正されたテキストに置き換えられるでしょう。言語を混ぜることは最適ではありませんが、自分でも理解できない翻訳の誤りを取り除き、利用者に提示する内容が決して誤解を招くものにならないようにするためには、これが唯一の方法なのです。対応するPOファイル中のドイツ語の翻訳を更新するのも遥かに簡単なので、言語の混在は長くは続かないでしょう。最後に、日本語の翻訳者が jp.po の翻訳ファイルを渡してきたら、それを \fIman/po4a/po/\fR に置くだけでいいのです。改めて \fBpo4a\fR を実行すると、翻訳されたページが \fIman/translated/foo.jp.1\fR として現れます（充分に内容が翻訳されている場合に限ります）。
.SH "オプション"
.IX Header "オプション"
.IP "\fB\-k\fR, \fB\-\-keep\fR" 4
.IX Item "-k, --keep"
生成するファイルを維持する（つまり書き出す）翻訳率の下限値（既定値：80）。言い換えると、既定では書き出されるために少なくとも 80％ は翻訳されディスク上に保存されていなければなりません。
.IP "\fB\-h\fR, \fB\-\-help\fR" 4
.IX Item "-h, --help"
短いヘルプメッセージを表示します。
.IP "\fB\-M\fR, \fB\-\-master\-charset\fR" 4
.IX Item "-M, --master-charset"
翻訳文書を含むファイルで使われている文字セットです。すべてのマスター文書が、同じ文字セットを使用していなければならないことに注意してください。
.IP "\fB\-L\fR, \fB\-\-localized\-charset\fR" 4
.IX Item "-L, --localized-charset"
ローカライズされた文書を含む、ファイルで使われている文字セット。翻訳されたすべての文書は同じ文字セットを使用することに注意してください。
.IP "\fB\-A\fR, \fB\-\-addendum\-charset\fR" 4
.IX Item "-A, --addendum-charset"
追加内容の文字セットです。追加内容では、すべて同じ文字セットを使用することに注意してください。
.IP "\fB\-V\fR, \fB\-\-version\fR" 4
.IX Item "-V, --version"
スクリプトのバージョンを表示して終了します。
.IP "\fB\-v\fR, \fB\-\-verbose\fR" 4
.IX Item "-v, --verbose"
プログラムの冗長度を上げます。
.IP "\fB\-q\fR, \fB\-\-quiet\fR" 4
.IX Item "-q, --quiet"
プログラムの冗長度を下げます。
.IP "\fB\-d\fR, \fB\-\-debug\fR" 4
.IX Item "-d, --debug"
デバッグ情報を出力します。
.IP "\fB\-o\fR, \fB\-\-option\fR" 4
.IX Item "-o, --option"
書式プラグインに渡す追加オプションです。有効なオプションやその意味の詳細は、各プラグインの説明書を参照してください。例えば、AsciiDocパーサーには '\-o tablecells' を、テキストパーサーには '\-o tabs=split' を渡すことができます。
.IP "\fB\-f\fR, \fB\-\-force\fR" 4
.IX Item "-f, --force"
生成の必要はないと \fBpo4a\fR が判断した場合でも、常に \s-1POT\s0 ファイルと \s-1PO\s0 ファイルを生成します。
.Sp
デフォルトの動作 (\fB\-\-force\fR を指定しない場合) は以下のようになります:
.RS 4
.Sp
.RS 4
\&\s-1POT\s0 ファイルが存在する場合、マスター文書や設定ファイルの方が新しければ（\fB\-\-no\-update\fRが指定されている場合を除き）再生成を実行します。POT ファイルもまた一時文書に書き出され、変更が本当に必要かどうか \fBpo4a\fR が検証を行います。
.Sp
また、マスタードキュメント、PO ファイル、追加内容のどれか、設定ファイルのいずれかが翻訳より新しい場合にのみ、翻訳を再生成します。しきい値に達しない翻訳を再生成しないように (\fB\-\-keep\fR を参照)、\fI.po4a\-stamp\fR 拡張子を持つファイルを作成します (\fB\-\-stamp\fR を参照)。
.RE
.RE
.RS 4
.Sp
マスタードキュメントがファイルをインクルードする場合、インクルードするファイルの更新時刻は考慮されないため、\fB\-\-force\fR フラグを使用するべきです。
.Sp
\&\s-1PO\s0 ファイルは、常に \s-1POT\s0 を元に \fBmsgmerge \-U\fR で再生成されます。
.RE
.IP "\fB\-\-stamp\fR" 4
.IX Item "--stamp"
翻訳が閾値に到達せず生成されないとき、\fBpo4a\fR にスタンプファイルを作成するように指示します。このスタンプファイルは翻訳済みドキュメントが期待する名前に \fI.po4a\-stamp\fR 拡張子をつけた名前となります。
.Sp
注意: これは \fI.po4a\-stamp\fR ファイルの作成を行うだけです。スタンプファイルは存在すれば使用され、\fB\-\-rm\-translations\fR を指定した場合や、最終的にファイルの翻訳が完了した場合に削除されます。
.IP "\fB\-\-no\-translations\fR" 4
.IX Item "--no-translations"
翻訳済みドキュメントを生成せず、POT ファイルや \s-1PO\s0 ファイルの更新のみ行います。
.IP "\fB\-\-no\-update\fR" 4
.IX Item "--no-update"
POT、POのファイルは変更せず、翻訳のみを更新することができます。
.IP "\fB\-\-keep\-translations\fR" 4
.IX Item "--keep-translations"
翻訳が \fB\-\-keep\fR で指定された閾値を満たしていない場合でも、既存の翻訳ファイルを保持します。 このオプションでは、内容の乏しい新しい翻訳ファイルは作成されませんが、マスターファイルへの変更のために陳腐化した既存の翻訳が保存されます。
.Sp
警告：このフラグは po4a の動作をかなり大幅に変更します。というのは、翻訳が改善されるまで、あなたの翻訳したファイルはまったく更新されないからです。正確な未翻訳の文書より、古びた翻訳文書のほうを世に出したい場合にのみ、このフラグを使用してください。
.IP "\fB\-\-rm\-translations\fR" 4
.IX Item "--rm-translations"
翻訳済みファイルを削除します (\fB\-\-no\-translations\fR を暗に意味します)。
.IP "\fB\-\-no\-backups\fR" 4
.IX Item "--no-backups"
このフラグは 0.41 から何もしなくなりました。また今後のリリースで削除される可能性があります。
.IP "\fB\-\-rm\-backups\fR" 4
.IX Item "--rm-backups"
このフラグは 0.41 から何もしなくなりました。また今後のリリースで削除される可能性があります。
.IP "\fB\-\-translate\-only\fR \fItranslated-file\fR" 4
.IX Item "--translate-only translated-file"
指定したファイルに対する翻訳のみ行います。設定ファイル内にファイルがたくさん指定されている場合、処理の高速化に役立つことでしょう。このオプションは、PO ファイルと \s-1POT\s0 ファイルの更新を行わないことに注意してください。このオプションは複数回指定できます。
.IP "\fB\-\-variable\fR \fIvar\fR\fB=\fR\fIvalue\fR" 4
.IX Item "--variable var=value"
\&\fBpo4a\fR 設定ファイル内で展開する変数を定義します。現れるすべての \fI$(var)\fR は、\fIvalue\fR に置換されます。このオプションは複数回使用できます。
.IP "\fB\-\-srcdir\fR \fI\s-1SRCDIR\s0\fR" 4
.IX Item "--srcdir SRCDIR"
\&\fBpo4a\fR 設定ファイルで指定されたすべての入力文書に対する基底ディレクトリを指定します。
.Sp
l<destdir>とl<srcdir>の両方が指定された場合、入力ファイルはl<destdir>、現在のディレクトリ、l<srcdir>の順番で探索します。出力ファイルは、指定されていればl<destdir>に、そうでなければ現在のディレクトリに書き出されます。
.IP "\fB\-\-destdir\fR \fI\s-1DESTDIR\s0\fR" 4
.IX Item "--destdir DESTDIR"
\&\fBpo4a\fRの設定ファイルで指定されたすべての出力文書の基底ディレクトリを設定します（前述の\fB\-\-srcdir\fRを参照）。
.SS "POTヘッダーを変更するオプション"
.IX Subsection "POTヘッダーを変更するオプション"
.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\-\-master\-language\fR" 4
.IX Item "--master-language"
翻訳文書を含むソースファイルの言語。すべてのマスター文書が同じ言語を使用する必要があることに注意してください。
.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 です。
.SS "\s-1PO\s0 ファイルを変更するオプション"
.IX Subsection "PO ファイルを変更するオプション"
.IP "\fB\-\-msgmerge\-opt\fR \fIoptions\fR" 4
.IX Item "--msgmerge-opt options"
\&\fBmsgmerge\fR(1) 用の追加オプションです。
.Sp
注意: \fB\f(CB$lang\fB\fR は現在の言語へ展開されます。
.IP "\fB\-\-no\-previous\fR" 4
.IX Item "--no-previous"
このオプションは、\fBmsgmerge\fR に渡すオプションから \fB\-\-previous\fR を削除します。これは0.16より前の\fBgettext\fRのサポートに不可欠なものです。
.IP "\fB\-\-previous\fR" 4
.IX Item "--previous"
このオプションは、\fBmsgmerge\fR に渡すオプションに \fB\-\-previous\fR を追加します。\fBgettext\fR 0.16 以降が必要で、デフォルトで有効です。
.SH "設定ファイル"
.IX Header "設定ファイル"
po4a は引数として設定ファイルを必要とします。このファイルには、次の要素が含まれている必要があります。
.IP "\(bu" 4
POファイルのパスおよびプロジェクトに存在する言語のリスト、
.IP "\(bu" 4
オプションとして、いくつかの大域オプションと、個々のマスターファイルを設定するためのテンプレートとして使用される、いわゆる設定エイリアス、
.IP "\(bu" 4
翻訳する各マスターファイルとそれぞれに指定する引数の一覧。
.PP
各行は角括弧で囲まれた命令とその後に続く引数で構成されています。 コメントは文字 '#' で始まり行末まで続きます。行末をエスケープすることで複数行にわたる命令を書けます。
.PP
このページでは、いくつかの完全な例を紹介していますが、他の例はソース配布物の\f(CW\*(C`t/cfg\*(C'\fRディレクトリにあります。
.SS "POファイルとPOTファイルの探索"
.IX Subsection "POファイルとPOTファイルの探索"
最も簡単な方法は、以下のようにPOTとPOのファイルへのパスを明示的に指定することです。
.PP
.Vb 1
\& [po4a_paths] man/po/project.pot de:man/po/de.po fr:man/po/fr.po
.Ve
.PP
ここではまずPOTファイルへのパスを指定し、次にドイツ語とフランス語のPOファイルへのパスを指定しています。
.PP
同じ意味ですが、コピーアンドペーストでのミスを軽減するために、以下のように書くこともできます。
.PP
.Vb 2
\& [po4a_langs] fr de
\& [po4a_paths] man/po/project.pot $lang:man/po/$lang.po
.Ve
.PP
\&\f(CW$lang\fR 構成要素は、与えられた言語一覧から自動的に展開されるため、新しい言語を追加する際のコピーアンドペーストでのミスの発生を軽減できます。
.PP
以下のように、翻訳プロジェクトを含むディレクトリへのパスを提供するだけで、同じ情報をさらに簡潔にすることができます。
.PP
.Vb 1
\& [po_directory] man/po/
.Ve
.PP
与えられたディレクトリには、いくつかのPOファイルが含まれていなければなりません。それぞれのファイル名は\fI\s-1XX\s0.po\fRで、\f(CW\*(C`XX\*(C'\fRはこのファイルで使用されている言語のISO 639\-1形式にしたがったものです。また、ディレクトリには、\f(CW\*(C`.pot\*(C'\fRという拡張子を持つPOTファイルが1つ含まれていなければなりません。初回実行時には、このファイルは中身が空でも構いませんが、必ず存在しなければなりません（po4aは拡張子の前の部分を推測することはできません）。
.PP
\&\f(CW\*(C`po_directory\*(C'\fR と \f(CW\*(C`po4a_paths\*(C'\fR のどちらか一方だけを選択する必要があることに注意してください。前者（\f(CW\*(C`po_directory\*(C'\fR）は、より簡素で、コピー＆ペーストエラーの危険を低減しますが、規定通りのプロジェクト構造とファイル名を使用する必要があります。後者(\f(CW\*(C`po4a_paths\*(C'\fR)はより明示的で、おそらくより読みやすいので、最初にpo4aでプロジェクトを立ち上げるときはこちらをお勧めします。
.PP
\fIPOファイルは一元化すべきか、もしくは分割すべきか？\fR
.IX Subsection "POファイルは一元化すべきか、もしくは分割すべきか？"
.PP
既定では、po4aは翻訳プロジェクトの全内容を含む、対象言語ごとに1つのPOファイルを生成します。プロジェクトが大きくなると、これらのファイルの大きさが問題になることがあります。Weblateを使用する場合、各翻訳区分（つまりmsgid）に優先順位を指定し、重要なものから順に翻訳することが可能です。それでも、翻訳チームは内容をいくつかのファイルに分割することを好むことがあります。
.PP
マスターファイルごとに1つのPOファイルがあるようにするには、以下のように、\f(CW\*(C`[po4a_paths]\*(C'\fR 行でPOファイルの名前に文字列 \f(CW$master\fR を使うだけです。
.PP
.Vb 1
\& [po4a_paths] doc/$master/$master.pot $lang:doc/$master/$lang.po
.Ve
.PP
この行によってpo4aは翻訳する文書ごとにそれぞれPOTファイルとPOファイルを作成します。例えば3つの文書と5つの言語がある場合、3つのPOTファイルと15のPOファイルになります。これらのファイルは \f(CW\*(C`po4a_paths\*(C'\fR テンプレートで指定された名前になり、 \f(CW$master\fR は翻訳するそれぞれの文書の基幹名に置き換えられます。名前が衝突した場合はPOTファイルで以下のように \f(CW\*(C`pot=\*(C'\fR 引数を使って指定できます。
.PP
この機能は、複数の翻訳ファイルを同じ \s-1POT\s0 ファイルにまとめることにも使用できます。次の例では、2つのPOTファイルだけが生成されます。\fIl10n/po/foo.pot\fR（\fIfoo/gui.xml\fR由来の翻訳材料を含む）と \fIl10n/po/bar.pot\fR（\fIbar/gui.xml\fR と \fIbar/cli.xml\fR の両方の翻訳材料を含む）です。
.PP
.Vb 5
\& [po4a_langs] de fr ja
\& [po4a_paths] l10n/po/$master.pot $lang:l10n/po/$master.$lang.po
\& [type: xml] foo/gui.xml $lang:foo/gui.$lang.xml pot=foo
\& [type: xml] bar/gui.xml $lang:bar/gui.$lang.xml pot=bar
\& [type: xml] bar/cli.xml $lang:bar/cli.$lang.xml pot=bar
.Ve
.PP
分割モードでは、\fBpo4a\fR は \s-1PO\s0 の更新中に一時的な大枠を構築し、すべての \s-1PO\s0 ファイル間で翻訳を共有します。2つのPOファイルが同じ文字列に対して異なる翻訳を持つ場合、\fBpo4a\fRはこの文字列をファジーとして印を付け、この文字列を含むすべてのPOファイルにおいて両方の翻訳を提示します。翻訳者によってファジーが解除されると、その翻訳がすべての \s-1PO\s0 ファイルで自動的に使用されます。
.SS "翻訳するドキュメントの指定"
.IX Subsection "翻訳するドキュメントの指定"
また、翻訳すべき文書を一覧にする必要があります。それぞれのマスター文書について、使用する形式のパーサ、翻訳された文書を生成する場所、そして任意で追加の設定を指定しなければいけません。以下に一例を示します。
.PP
.Vb 5
\& [type: sgml] doc/my_stuff.sgml fr:doc/fr/mon_truc.sgml \e
\&              de:doc/de/mein_kram.sgml
\& [type: man] script fr:doc/fr/script.1 de:doc/de/script.1
\& [type: docbook] doc/script.xml fr:doc/fr/script.xml \e
\&             de:doc/de/script.xml
.Ve
.PP
しかし繰り返しになりますが、これらの複雑な行は読んだり変更したりするのが難しいです。例えば新しい言語を追加するときなどです。そこで \f(CW$lang\fR テンプレートを使って以下のようにまとめ直すとより簡素になります。
.PP
.Vb 3
\& [type: sgml]    doc/my_stuff.sgml $lang:doc/$lang/my_stuff.sgml
\& [type: man]     script.1          $lang:po/$lang/script.1
\& [type: docbook] doc/script.xml    $lang:doc/$lang/script.xml
.Ve
.SS "オプションの指定"
.IX Subsection "オプションの指定"
オプションには2種類あります。\fIpo4aオプション\fRはpo4aコマンドラインオプションの既定値であり、\fI形式オプション\fRは形式の構文解析器の動作を変更するために使用されます。\fIpo4a オプション\fR として、例えば、\fB\-\-keep\fR コマンドラインパラメータの既定値を 80% ではなく 50% にすることを設定ファイルに指定することができます。\fI形式オプション\fRは各構文解析モジュールの個別のページ、例えば\fBLocale::Po4a::Xml\fR\|(3pm)に記載されています。例えば、\fBnostrip\fRをXMLパーサーに渡すと、抽出された文字列の周りのスペースを取り除かないようにすることができます。
.PP
これらのオプションは特定のマスターファイルに対して、あるいはそのファイルの特定の翻訳に対して、\f(CW\*(C`opt:\*(C'\fR と \f(CW\*(C`opt_XX:\*(C'\fR を使って \f(CW\*(C`XX\*(C'\fR 言語に渡すことができます。次の例では、\fBnostrip\fRオプションが（すべての言語に対して）XML構文解析器に渡される一方で、フランス語翻訳に対しては閾値が0％に減じられています（したがって、翻訳は常に維持されます）。
.PP
.Vb 1
\& [type:xml] toto.xml $lang:toto.$lang.xml opt:"\-o nostrip" opt_fr:"\-\-keep 0"
.Ve
.PP
いずれにせよ、これらの設定の各区切りは行末に配置しなければなりません。ファイルの宣言が最初に来て、次に補遺があればそれを（後述）、そしてオプションだけが来るようにしなければなりません。設定の各区切りの集合化は、内部的には文字列として連結されるためあまり重要ではありません。以下の例はすべて等価です。
.PP
.Vb 3
\&  [type:xml] toto.xml $lang:toto.$lang.xml opt:"\-\-keep 20" opt:"\-o nostrip" opt_fr:"\-\-keep 0"
\&  [type:xml] toto.xml $lang:toto.$lang.xml opt:"\-\-keep 20 \-o nostrip" opt_fr:"\-\-keep 0"
\&  [type:xml] toto.xml $lang:toto.$lang.xml opt:\-\-keep opt:20 opt:\-o opt:nostrip opt_fr:\-\-keep opt_fr:0
.Ve
.PP
言語固有のオプションは、POT ファイルを構築するときには使用されないことに注意してください。例えば、フランス語の翻訳を構築するときだけ構文解析器に \fBnostrip\fR を渡すことは不可能です。なぜなら、同じ \s-1POT\s0 ファイルがすべての言語を更新するために使われるからです。したがって言語固有のオプションは、\f(CW\*(C`\-\-keep\*(C'\fRオプションのように、翻訳を作成するときに使用されるものだけです。
.PP
\fI設定ファイルのエイリアス\fR
.IX Subsection "設定ファイルのエイリアス"
.PP
同じオプションを複数のファイルに渡すには、次のように型の別名を定義するのが一番です。次の例では、\f(CW\*(C`\-\-keep 0\*(C'\fR が\f(CW\*(C`man\*(C'\fR 型の拡張であるこの \f(CW\*(C`test\*(C'\fR 型を使用するすべてのイタリア語翻訳に渡されています。
.PP
.Vb 2
\&  [po4a_alias:test] man opt_it:"\-\-keep 0"
\&  [type: test] man/page.1 $lang:man/$lang/page.1
.Ve
.PP
また、以下のように既存の型を拡張し、別名に同じ名前を再利用することも可能です。これは、誤った再帰的定義として解釈されることはありません。
.PP
.Vb 2
\&  [po4a_alias:man] man opt_it:"\-\-keep 0"
\&  [type: man] man/page.1 $lang:man/$lang/page.1
.Ve
.PP
\fI大域的な既定のオプション\fR
.IX Subsection "大域的な既定のオプション"
.PP
また、\f(CW\*(C`[options]\*(C'\fR行を使用し、ファイルの種類に関係なく、すべてのファイルに対して使用しなければならないオプションを定義することができます。
.PP
.Vb 1
\&  [options] \-\-keep 20 \-\-option nostrip
.Ve
.PP
コマンドラインオプションと同様に、設定ファイルに渡される引数を略すことができます。
.PP
.Vb 1
\&  [options] \-k 20 \-o nostrip
.Ve
.PP
\fIオプションの優先順位\fR
.IX Subsection "オプションの優先順位"
.PP
各ソースのオプションを連結し、既定値をより具体的なオプションで簡単に上書きできるようになっています。その順序は以下の通りです。
.IP "\(bu" 4
\&\f(CW\*(C`[options]\*(C'\fR行は、他のソースで上書き可能な既定値を提供します。
.IP "\(bu" 4
種類の別名が使用されます。言語固有の設定は、すべての言語に適用される設定より優先されます。
.IP "\(bu" 4
特定のマスターファイルに固有の設定は、既定の設定と種類の別名に由来する設定の両方を上書きします。この場合、言語固有の設定は大域的な設定より優先されます。
.IP "\(bu" 4
最後に、\fBpo4a\fRコマンドラインで提供される引数は、設定ファイルの設定を上書きします。
.PP
\fI例\fR
.IX Subsection "例"
.PP
ここでは、空白と引用符の使い分けを示す例を示します。
.PP
.Vb 1
\& [po_directory] man/po/
\& 
\& [options] \-\-master\-charset UTF\-8
\& 
\& [po4a_alias:man] man opt:"\-o \e"mdoc=NAME,SEE ALSO\e""
\& [type:man] t\-05\-config/test02_man.1 $lang:tmp/test02_man.$lang.1 \e
\&            opt:"\-k 75" opt_it:"\-L UTF\-8" opt_fr:\-\-verbose
.Ve
.SS "補遺：翻訳に追記する"
.IX Subsection "補遺：翻訳に追記する"
もし、翻訳者のクレジットを加えるなど、翻訳に追加の節を追加したい場合は、マスターファイルで定まる行に補遺ファイルを定義する必要があります。補遺ファイルの構文についてより詳しくは、\fBpo4a\fR\|(7) ページを参照してください。
.PP
.Vb 2
\& [type: pod] script fr:doc/fr/script.1 \e
\&             add_fr:doc/l10n/script.fr.add
.Ve
.PP
また、以下のように言語テンプレートを使用することも可能です。
.PP
.Vb 2
\& [type: pod] script $lang:doc/$lang/script.1 \e
\&             add_$lang:doc/l10n/script.$lang.add
.Ve
.PP
補遺の適用に失敗したら、その翻訳は無視されます。
.PP
\fI補遺の宣言用の修飾子\fR
.IX Subsection "補遺の宣言用の修飾子"
.PP
補遺修飾子は、すべての言語では補遺を提供していない場合や、補遺の一覧がある言語と別の言語とで変わってくる場合に、構成ファイルを単純化できます。修飾子は、ファイル名の前にある単一の文字です。
.IP "\fB?\fR" 2
.IX Item "?"
ファイルが存在する場合 \fIaddendum_path\fR を含めます。なければ何もしません。
.IP "\fB@\fR" 2
.IX Item "@"
\&\fIaddendum_path\fR は通常の追加内容ファイルではなく、追加内容ファイルのリスト (1 行 1 ファイル) です。各追加内容ファイルの前に修飾子を追加できます。
.IP "\fB!\fR" 2
.IX Item "!"
\&\fIaddendum_path\fR は読み込まれません。また、その他の追加内容で読み込まれるように指定してあっても読み込まれません。
.PP
以下では存在する場合にのみいかなる言語においても補遺を含みます。補遺が存在しない場合、エラーは報告されません。
.PP
.Vb 1
\& [type: pod] script $lang:doc/$lang/script.1  add_$lang:?doc/l10n/script.$lang.add
.Ve
.PP
以下には各言語向けの補遺の一覧が含まれます。
.PP
.Vb 1
\& [type: pod] script $lang:doc/$lang/script.1  add_$lang:@doc/l10n/script.$lang.add
.Ve
.SS "翻訳する文字列の選別"
.IX Subsection "翻訳する文字列の選別"
時には、翻訳過程でいくつかの文字列を隠したいことがあります。そのために、マスターファイルに\f(CW\*(C`pot_in\*(C'\fR引数を与えて、POTファイルを構築するときに本当のマスターの代わりに使用するファイルの名前を指定することができます。以下はその例です。
.PP
.Vb 3
\&  [type:docbook] book.xml          \e
\&          pot_in:book\-filtered.xml \e
\&          $lang:book.$lang.xml
.Ve
.PP
この設定により、翻訳される文字列は\fIbook\-filtered.xml\fR（\fBpo4a\fRを呼び出す前に生成されなければなりません）から抽出され、翻訳ファイルは\fIbook.xml\fRから構築されることになります。その結果、\fIbook.xml\fR には含まれるが \fIbook\-filtered.xml\fR には含まれない文字列は \s-1PO\s0 ファイルに含まれず、翻訳者が翻訳を提供することができなくなります。そのため、これらの文字列は翻訳文書を作成する際に変更されずに残されることになります。これは当然ながら翻訳水準を低下させるので、とにかく文書を確実に作成するために\f(CW\*(C`\-\-keep\*(C'\fRオプションが必要になるかもしれません。
.SH "関連項目"
.IX Header "関連項目"
\&\fBpo4a\-gettextize\fR\|(1)、\fBpo4a\fR\|(7)。
.SH "著者"
.IX Header "著者"
.Vb 3
\& Denis Barbier <barbier@linuxfr.org>
\& Nicolas François <nicolas.francois@centraliens.net>
\& 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
.SH "著作権とライセンス"
.IX Header "著作権とライセンス"
Copyright 2002\-2022 by \s-1SPI,\s0 inc.
.PP
本プログラムはフリーソフトウェアです。GPL の条項に基づき再頒布と変更を行うことができます (\s-1COPYING\s0 ファイルを参照してください)。