早分かり入門¶

foo という名前のプログラムを保守していて、そのプログラムには英語（ほとんどのオープンソースプロジェクトでの橋渡しとなる言語ですが、 po4a はどの言語からでも、またどの言語へでも使えます）で書かれた man ページ man/foo.1 があるとしましょう。いつだったか、誰かが man/foo.de.1 という名前のドイツ語の翻訳を提供したなり立ち消えになったことがありました。ここで問題になっているのは、たった今文書にすべての言語で修正しなければならないような重大な誤解を招く情報が含まれているというバグ報告を受けましたが、ドイツ語を話せないので、翻訳ではなく元の文書を修正するしかないということです。そして今、別の貢献者がこれまた修得していない言語である日本語への翻訳を提供したいと言っています。

文書の保守の悪夢を解決するために、文書をpo4aに変換する時が来ました。必要なときに文書を更新したい、仲間の翻訳者達の作業を楽にしたい、そして、利用者が古くて誤解を招くような文書を目にすることがないようにしたい、そう思っていますよね。

変換には2つの工程が含まれます。po4aインフラの立ち上げと、以前のドイツ語翻訳を引き揚げるための変換です。この後者の部分は、以下のようにpo4a-gettextizeを使用して行われます。po4a-gettextize(1) のドキュメントに詳述されているように、この過程が完全に自動化されることは稀ですが、一度完了すればドイツ語翻訳を含む de.po ファイルを po4a の作業工程に統合することができます。

  po4a-gettextize --format man --master foo.1 --localized foo.de.1 --po de.po

それではpo4aを設定しましょう。適切なファイル配置を使うと設定ファイルはこのように単純になります。

 [po_directory] man/po4a/
 [type: man] man/foo.1 $lang:man/translated/foo.$lang.1

これは、すべての（翻訳者の作業内容を含む）PO ファイルが man/po4a/ ディレクトリにあり、マスターファイルは man/foo.1 の 1 つだけであることを指定するものです。もし、複数のマスターファイルがあれば、2行目のような行がいくつもあることになります。このような行はそれぞれ、対応する翻訳ファイルをどこに書き込むかも指定します。ここでは、man/foo.1 のドイツ語訳は man/translated/foo.de.1 にあります。

po4aの設定を完了するために最後に必要なものは、新しい翻訳を開始するために使用されるべきテンプレート材料を含むPOTファイルです。指定されたpo_directoryの中にに拡張子.potの空のファイルを作成するだけです（例：man/po4a/foo.pot）。そしてpo4aはその中に期待される内容を詰め込みます。

この立ち上げでのファイルについておさらいすると次のようになります。

  ├── man/
  │   ├── foo.1        <- 英語で書かれた元のmanページ
  │   ├── po4a/
  │   │   ├── de.po    <- gettextizationによるドイツ語訳のPO
  │   │   └── foo.pot  <- 将来の翻訳に向けたPOTテンプレート（最初は空）
  │   └── translated/  <- 翻訳が作られるディレクトリ
  └── po4a.cfg         <-設定ファイル

一度立ち上げれば、po4aを実行すると、文書を解析し、POTテンプレートファイルを更新し、それを使ってPO翻訳ファイルを更新し、それを使って文書の翻訳ファイルを更新します。すべて1つのコマンドで。

        po4a --verbose po4a.cfg

以上です。po4aは完璧に構成されました。man/foo.1の誤りを修正したら、ドイツ語翻訳の問題のある段落は、修正後の英語のテキストに置き換えられるでしょう。言語が混ざることは理想的ではありませんが、自分で理解が及ばない翻訳の誤りを取り除き、利用者に提示する内容が決して誤解を招くものにならないようにするためには、これが唯一の方法なのです。対応するPOファイル中のドイツ語の翻訳を更新するのも遥かに簡単なので、言語の混在は長くは続かないでしょう。最後に、新しく翻訳に貢献したい日本語の翻訳者が現れた場合は、翻訳者がfoo.potを複製してja.poにファイルを変更し、翻訳を完成させます。このファイルを受け取ったらman/po4a/po/の中に置くだけです。改めて po4a を実行すると、（充分に内容が翻訳されていれば）翻訳されたページが man/translated/foo.ja.1 として現れます。

POTヘッダーを変更するオプション¶

--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の行の折り返し方法、すなわちこれらの文字列の内容に改行を追加する方法には影響しないことに注意してください。

--master-language

翻訳文書を含むソースファイルの言語。すべてのマスター文書が同じ言語を使用する必要があることに注意してください。

--msgid-bugs-address Eメール@アドレス

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

--copyright-holder 文字列

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

--package-name string

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

--package-version string

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

PO ファイルを変更するオプション¶

--msgmerge-opt オプション

msgmerge(1) 用の追加オプションです。

注意: $lang は現在の言語へ展開されます。

--no-previous

このオプションは、msgmerge に渡すオプションから --previous を削除します。これは0.16より前のgettextのサポートに不可欠なものです。

--previous

このオプションは、msgmerge に渡すオプションに --previous を追加します。gettext 0.16 以降が必要で、デフォルトで有効です。

POファイルとPOTファイルの探索¶

最も簡単な方法は、以下のようにPOTとPOのファイルへのパスを明示的に指定することです。

 [po4a_paths] man/po/project.pot de:man/po/de.po fr:man/po/fr.po

ここではまずPOTファイルへのパスを指定し、次にドイツ語とフランス語のPOファイルへのパスを指定しています。

同じ意味ですが、コピーアンドペーストでのミスを軽減するために、以下のように書くこともできます。

 [po4a_langs] fr de
 [po4a_paths] man/po/project.pot $lang:man/po/$lang.po

$lang 構成要素は、与えられた言語一覧から自動的に展開されるため、新しい言語を追加する際のコピーアンドペーストでのミスの発生を軽減できます。

以下のように、翻訳プロジェクトを含むディレクトリへのパスを提供するだけで、同じ情報をさらに簡潔にすることができます。

 [po_directory] man/po/

与えられたディレクトリには、いくつかのPOファイルが含まれていなければなりません。それぞれのファイル名はXX.poで、"XX"はこのファイルで使用されている言語のISO 639-1形式にしたがったものです。また、ディレクトリには、".pot"という拡張子を持つPOTファイルが1つ含まれていなければなりません。初回実行時には、このファイルは中身が空でも構いませんが、必ず存在しなければなりません（po4aは拡張子の前の部分を推測することはできません）。

"po_directory" と "po4a_paths" のどちらか一方だけを選択する必要があることに注意してください。前者（"po_directory"）は、より簡素で、コピー＆ペーストエラーの危険を低減しますが、規定通りのプロジェクト構造とファイル名を使用する必要があります。後者("po4a_paths")はより明示的で、おそらくより読みやすいので、最初にpo4aでプロジェクトを立ち上げるときはこちらをお勧めします。

POファイルは一元化すべきか、もしくは分割すべきか？

既定では、po4aは翻訳プロジェクトの全内容を含む、対象言語ごとに1つのPOファイルを生成します。プロジェクトが大きくなると、これらのファイルの大きさが問題になることがあります。Weblateを使用する場合、各翻訳区分（つまりmsgid）に優先順位を指定し、重要なものから順に翻訳することが可能です。それでも、翻訳チームは内容をいくつかのファイルに分割することを好むことがあります。

マスターファイルごとに1つのPOファイルがあるようにするには、以下のように、"[po4a_paths]" 行でPOファイルの名前に文字列 $master を使うだけです。

 [po4a_paths] doc/$master/$master.pot $lang:doc/$master/$lang.po

この行によってpo4aは翻訳する文書ごとにそれぞれPOTファイルとPOファイルを作成します。例えば3つの文書と5つの言語がある場合、3つのPOTファイルと15のPOファイルになります。これらのファイルは "po4a_paths" テンプレートで指定された名前になり、 $master は翻訳するそれぞれの文書の基幹名に置き換えられます。名前が衝突した場合はPOTファイルで以下のように "pot=" 引数を使って指定できます。

この機能は、複数の翻訳ファイルを同じ POT ファイルにまとめることにも使用できます。次の例では、2つのPOTファイルだけが生成されます。l10n/po/foo.pot（foo/gui.xml由来の翻訳材料を含む）と l10n/po/bar.pot（bar/gui.xml と bar/cli.xml の両方の翻訳材料を含む）です。

 [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

分割モードでは、po4a は PO の更新中に一時的な大枠を構築し、すべての PO ファイル間で翻訳を共有します。2つのPOファイルが同じ文字列に対して異なる翻訳を持つ場合、po4aはこの文字列をファジーとして印を付け、この文字列を含むすべてのPOファイルにおいて両方の翻訳を提示します。翻訳者によってファジーが解除されると、その翻訳がすべての PO ファイルで自動的に使用されます。

翻訳するドキュメントの指定¶

また、翻訳すべき文書を一覧にする必要があります。それぞれのマスター文書について、使用する形式の構文解析器、翻訳された文書が生成される場所、そして任意で追加の構成を指定しなければいけません。ファイル名に空白が含まれている場合は引用符で囲むかエスケープしてください。以下に一例を示します。

 [type: sgml] "doc/my stuff.sgml"  "fr:doc/fr/mon truc.sgml"  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 \
             de:doc/de/script.xml

しかし繰り返しになりますが、これらの複雑な行は読んだり変更したりするのが難しいです。例えば新しい言語を追加するときなどです。そこで $lang テンプレートを使って以下のようにまとめ直すとより簡素になります。

 [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

オプションの指定¶

オプションには2種類あります。po4aオプションはpo4aコマンドラインオプションの既定値であり、形式オプションは形式の構文解析器の動作を変更するために使用されます。po4a オプション として、例えば、--keep コマンドラインパラメータの既定値を 80% ではなく 50% にすることを設定ファイルに指定することができます。形式オプションは各構文解析モジュールの個別のページ、例えばLocale::Po4a::Xml(3pm)に記載されています。例えば、nostripをXMLパーサーに渡すと、抽出された文字列の周りのスペースを取り除かないようにすることができます。

これらのオプションは特定のマスターファイルに対して、あるいはそのファイルの特定の翻訳に対して、"opt:" と "opt_XX:" を使って "XX" 言語に渡すことができます。次の例では、nostripオプションが（すべての言語に対して）XML構文解析器に渡される一方で、フランス語翻訳に対しては閾値が0％に減じられています（したがって、翻訳は常に維持されます）。

 [type:xml] toto.xml $lang:toto.$lang.xml opt:"-o nostrip" opt_fr:"--keep 0"

いずれにせよ、これらの設定の各区切りは行末に配置しなければなりません。ファイルの宣言が最初に来て、次に補遺があればそれを（後述）、そしてオプションだけが来るようにしなければなりません。設定の各区切りの集合化は、内部的には文字列として連結されるためあまり重要ではありません。以下の例はすべて等価です。

  [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

言語固有のオプションは、POT ファイルを構築するときには使用されないことに注意してください。例えば、フランス語の翻訳を構築するときだけ構文解析器に nostrip を渡すことは不可能です。なぜなら、同じ POT ファイルがすべての言語を更新するために使われるからです。したがって言語固有のオプションは、"--keep"オプションのように、翻訳を作成するときに使用されるものだけです。

設定ファイルのエイリアス

同じオプションを複数のファイルに渡すには、次のように型の別名を定義するのが一番です。次の例では、"--keep 0" が"man" 型の拡張であるこの "test" 型を使用するすべてのイタリア語翻訳に渡されています。

  [po4a_alias:test] man opt_it:"--keep 0"
  [type: test] man/page.1 $lang:man/$lang/page.1

また、以下のように既存の型を拡張し、別名に同じ名前を再利用することも可能です。これは、誤った再帰的定義として解釈されることはありません。

  [po4a_alias:man] man opt_it:"--keep 0"
  [type: man] man/page.1 $lang:man/$lang/page.1

大域的な既定のオプション

また、"[options]"行を使用し、ファイルの種類に関係なく、すべてのファイルに対して使用しなければならないオプションを定義することができます。

  [options] --keep 20 --option nostrip

コマンドラインオプションと同様に、設定ファイルに渡される引数を略すことができます。

  [options] -k 20 -o nostrip

オプションの優先順位

各ソースのオプションを連結し、既定値をより具体的なオプションで簡単に上書きできるようになっています。その順序は以下の通りです。

• "[options]"行は、他のソースで上書き可能な既定値を提供します。
• 種類の別名が使用されます。言語固有の設定は、すべての言語に適用される設定より優先されます。
• 特定のマスターファイルに固有の設定は、既定の設定と種類の別名に由来する設定の両方を上書きします。この場合、言語固有の設定は大域的な設定より優先されます。
• 最後に、po4aコマンドラインで提供される引数は、設定ファイルの設定を上書きします。

例

ここでは、空白と引用符の使い分けを示す例を示します。

 [po_directory] man/po/
 
 [options] --master-charset UTF-8
 
 [po4a_alias:man] man opt:"-o \"mdoc=NAME,SEE ALSO\""
 [type:man] t-05-config/test02_man.1 $lang:tmp/test02_man.$lang.1 \
            opt:"-k 75" opt_it:"-L UTF-8" opt_fr:--verbose

補遺：翻訳に追記する¶

もし、翻訳者の著作情報を加えるなど、翻訳に追加の節を追加したい場合は、マスターファイルで定まる行に補遺ファイルを定義する必要があります。補遺ファイルの構文についてより詳しくは、po4a(7) ページを参照してください。

 [type: pod] script fr:doc/fr/script.1 \
             add_fr:doc/l10n/script.fr.add

また、以下のように言語テンプレートを使用することも可能です。

 [type: pod] script $lang:doc/$lang/script.1 \
             add_$lang:doc/l10n/script.$lang.add

補遺の適用に失敗したら、その翻訳は無視されます。

補遺の宣言用の修飾子

補遺修飾子は、すべての言語では補遺を提供していない場合や、補遺の一覧がある言語と別の言語とで変わってくる場合に、構成ファイルを単純化できます。修飾子は、ファイル名の前にある単一の文字です。

?

ファイルが存在する場合 addendum_path を含めます。なければ何もしません。

@

addendum_path は通常の追加内容ファイルではなく、追加内容ファイルのリスト (1 行 1 ファイル) です。各追加内容ファイルの前に修飾子を追加できます。

!

addendum_path は読み込まれません。また、その他の追加内容で読み込まれるように指定してあっても読み込まれません。

以下では存在する場合にのみいかなる言語においても補遺を含みます。補遺が存在しない場合、エラーは報告されません。

 [type: pod] script $lang:doc/$lang/script.1  add_$lang:?doc/l10n/script.$lang.add

以下には各言語向けの補遺の一覧が含まれます。

 [type: pod] script $lang:doc/$lang/script.1  add_$lang:@doc/l10n/script.$lang.add

翻訳する文字列の選別¶

時には、翻訳過程でいくつかの文字列を隠したいことがあります。そのために、マスターファイルに"pot_in"引数を与えて、POTファイルを構築するときに本当のマスターの代わりに使用するファイルの名前を指定することができます。以下はその例です。

  [type:docbook] book.xml          \
          pot_in:book-filtered.xml \
          $lang:book.$lang.xml

この設定により、翻訳される文字列はbook-filtered.xml（po4aを呼び出す前に生成されなければなりません）から抽出され、翻訳ファイルはbook.xmlから構築されることになります。その結果、book.xml には含まれるが book-filtered.xml には含まれない文字列は PO ファイルに含まれず、翻訳者が翻訳を提供することができなくなります。そのため、これらの文字列は翻訳文書を作成する際に変更されずに残されることになります。これは当然ながら翻訳水準を低下させるので、とにかく文書を確実に作成するために"--keep"オプションが必要になるかもしれません。