po4a プログラムは、翻訳対象が複数だったり、フォーマットが異なったり、ドキュメントごとに異なるオプションを指定する必要がある場合に、po4a-gettextize(1), po4a-updatepo(1), po4a-translate(1) を複雑な Makefile で呼ばなくてすむようになります。
翻訳者入力ファイルのパス指定
パスや言語の自動検出
翻訳するドキュメントの指定
モジュールオプションの指定
エイリアスの指定
また、異なるフォーマットが混在したドキュメントを同じ POT ファイルにでき、プロジェクトごとにひとつのファイルで管理できます。
こういったことは、po4a スイートの他のツールを (例えば Makefile とともに) 用いても同様にできますが、少々難しくなります。po4a を使用しているプロジェクトごとに、そのような複雑な Makefile を、何度も作成するのは大変です。
以下にデータフローをまとめました。マスタードキュメントの変更を PO ファイルに反映し、PO ファイルの変更を、(手での修正でも前述のステップでも) 翻訳済みドキュメントに反映します。
マスタードキュメント --> PO ファイル --> 翻訳
このツールでは、データフローを逆にはできません。また、翻訳ファイルに対して変更しても、PO ファイルの内容で上書かれます。つまり、実のところ、このツールでは既存の翻訳を po4a システムに変換できないのです。このような用途には、po4a-gettextize(1) を参照してください。
このファイルでは、'#' に続けてコメントを記述でき、行末までをすべてコメントにします。行末をエスケープして、行をつなげることもできます。空行でない行は [] コマンドで始め、引数が続かなければなりません (こういうと難しく聞こえますが、思ったより簡単だと思います ;) )。
これは、設定ファイル全体を単純にし、より柔軟にするオプションコマンドです。ドキュメントを翻訳したい言語のリストを指定しなければなりません。単純に以下のようになります。
[po4a_langs] fr de
これ以降の設定ファイル内で、$lang を指定した言語に展開するようになります。
まず、翻訳者入力ファイル (翻訳者が自分の作業に使用するファイル) の位置を指定する必要があります。以下のような行で行います。
[po4a_paths] doc/l10n/project.doc.pot \
fr:doc/l10n/fr.po de:doc/l10n/de.po
コマンドは上記より [po4a_paths] です。第一引数は、使用する POT ファイルのパスです。続くすべての引数は、次のように一目瞭然な形をしています。
<言語>:<この言語の PO ファイルへのパス>
テンプレート言語を定義している場合、上記の行は以下のように書き換えられます。
[po4a_paths] doc/l10n/project.doc.pot $lang:doc/l10n/$lang.po
ドキュメントのファイル名を参照するのに $master も使用できます。この場合、po4a は分割モードとなります。これは po4a の設定ファイルで指定した各ドキュメントについて、POT ファイルと (言語ごとの) PO ファイルを一つずつ作成します。分割モード セクションをご覧ください。
[po4a_paths] doc/$master/$master.pot $lang:doc/$master/$lang.po
このコマンドは、[po4a_langs] コマンドや [po4a_paths] コマンドと同時に使用するべきではありません。
このコマンドを使用する際、POT ファイルの名前を知らせるため、po4a の初回起動時に空の POT ファイルを作る必要があります。
[po_directory] po4a/po/
[type: sgml] doc/my_stuff.sgml fr:doc/fr/mon_truc.sgml \
de:doc/de/mein_kram.sgml
[type: pod] script fr:doc/fr/script.1 de:doc/de/script.1 \
add_fr:doc/l10n/script.fr.add
これもまたかなり自己説明的だと思います。2 番目のケースでは、doc/l10n/script.fr.add は、このドキュメントのフランス語版に追加する追加内容です。追加内容についての詳細情報は po4a(7) を参照してください。
もっと形式張って言うとフォーマットは以下のようになります。
[type: <format>] <master_doc> (<lang>:<localized_doc>)* \
(add_<lang>:<modifier>*<addendum_path>)*
修飾子がない場合、addendum_path は追加内容へのパスになります。修飾子は以下になります。
テンプレート言語を定義している場合、上記の行は以下のように書き換えられます。
[type: pod] script $lang:doc/$lang/script.1 \
add_fr:doc/l10n/script.fr.add
すべての言語が、似たようなパスで追加内容を持つ場合は、以下のようにも書けます。
[type: pod] script $lang:doc/$lang/script.1 \
add_$lang:doc/l10n/script.$lang.add
翻訳したいドキュメントの一つに、特定のオプションが必要な場合、設定ファイルで指定することもできます。オプションは opt キーワードで表します。opt キーワードの引数は、空白を含む場合 (複数のオプションを指定する場合や、引数を取るオプションの場合など)、ダブルクォートで囲まなければなりません。opt_lang キーワードを使用して、特定の言語だけにオプションを指定することもできます。
以下はサンプルです。
[type:man] data-05/test2_man.1 $lang:tmp/test2_man.$lang.1 \
opt:``-k 75'' opt_it:``-L UTF-8'' opt_fr:-v
シングルクォートかエスケープしたダブルクォートで、以下のように引数に空白を含められます。
[po4a_alias:man] man opt:``-o \''mdoc=NAME,SEE ALSO\`` -k 20''
たくさんのドキュメントで同じオプションを指定したい場合は、エイリアスを利用できます (以下の エイリアスの指定 セクションをご覧ください)。
設定ファイルの中で、すべてのドキュメントに対するオプションの指定もできます。
[options] opt:``...'' opt_fr:``...''
[po4a_alias:test] man opt:"-k 21" opt_es:"-o debug=splitargs"
これは、man モジュールを元にして全言語に -k 21を適用し、スペイン語の翻訳には -o debug=splitargs を適用する、test というモジュールエイリアスを定義します。
このモジュールエイリアスは、以下のようにして通常のモジュールと同様に使用できます。
[type:test] data-05/test2_man.1 $lang:tmp/test2_man.$lang.1 \
opt_it:"-L UTF-8" opt_fr:-v
ファイルごとの追加オプションも指定できることに注意してください。
分割モードを使用する際、一時的に大きな POT ファイルと大きな PO ファイルを使用します。これにより、すべての PO 間で翻訳を共有できます。
2 つの PO で、同じ文字列に対して異なる翻訳がされている場合、po4a はその文字列を fuzzy としてマークし、その文字列を持つすべての PO に、両方の訳を出力します。その場合、翻訳者は訳を更新し、ひとつの PO から fuzzy タグを取り除くと、この文字列の訳は、すべての PO で自動的に更新されます。
複数のファイルで名前が同じで、名前に競合がある場合、次のように "master:file="name オプションを追加して、マスターファイル名を指定できます。
[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 master:file=foo-gui [type: xml] bar/gui.xml $lang:bar/gui.$lang.xml master:file=bar-gui
デフォルトの動作 (--force を指定しない場合) は以下のようになります。
また、マスタードキュメント、PO ファイル、追加内容のどれか、設定ファイルのいずれかが翻訳より新しい場合にのみ、翻訳を再生成します。閾値テスト (--keep 参照) に合格しない翻訳を再生成しないように、.po4a-stamp 拡張子を持つファイルを作成します (--stamp 参照)。
マスタードキュメントにファイルをインクルードする場合、インクルードするファイルの更新時間は考慮に入らないため、--force フラグを使用するべきです。
PO ファイルは、常に POT を元に msgmerge -U で再生成されます。
注意: これは .po4a-stamp ファイルの作成を行うだけです。stamp ファイルがある場合は常に使用され、--rm-translations を指定した場合や、最終的にファイルの翻訳が完了した場合に削除されます。
引数にはコンマで続けて、wrap か nowrap というキーワードを後に付けられます。デフォルトでは、リファレンスを 1 行で書き出します。wrap オプションは、gettext ツール (xgettext や msgmerge) のように、リファレンスを複数行に折り返します。このオプションは、より気が利いているため、将来のリリースでデフォルトとなります。元の挙動のままにしておきたいユーザは、nowrap オプションを使用できます。
注意: $lang は現在の言語へ展開されます。
この場合、以下のように実行します。
cd man && po4a-gettextize -f man -m foo.1 -p foo.pot
次にこのファイルを、適切な言語のメーリングリストに送るか、ダウンロードできるようウェブサイトのどこかに用意することになります。
ここで、次のリリースまでの間に、de.po (追加内容 de.add を含む), sv.po, pt.po の三つの翻訳を受け取ったとしましょう。新しい翻訳が届いたからといって、Makefile を変更したくはありません。この場合、適切な設定ファイルを用意した po4a を、Makefile 内で利用できます。これを po4a.cfg と呼びましょう。先ほどの例は、以下のようになります。
[po_directory] man/po4a/po/
[type: man] man/foo.1 $lang:man/translated/$lang/foo.1 \
add_$lang:?man/po4a/add_$lang/$lang.add opt:"-k 80"
この例では、生成した man ページ (とすべての PO ファイルと追加内容ファイル) は、カレントディレクトリ以下の man/translated/$lang/ (それぞれ man/po4a/po/ と man/po4a/add_$lang/) に格納するとします。この例では、man/po4a/po/ に de.po, pt.po, sv.po があり、man/po4a/add_de/ ディレクトリに de.add があります。
追加内容を添付されたドイツ語翻訳 (de.po) でのみ、修飾子 ? の使用に注意が必要です。
その後、実際に翻訳済み man ページを構築するため、適切な Makefile の構築ターゲットに以下の行を (一度だけ!) 追加します。
po4a po4a.cfg
一度この設定をしておけば、新しい翻訳が届いても Makefile に触れる必要はありません。言い換えると、フランス語チームが fr.po と fr.add を送って来た時に、それぞれ man/po4a/po/ と man/po4a/add_fr/ へ、単に置くだけだということです。次回プログラム構築時に、フランス語翻訳が man/translated/fr/ に自動的に構築されます。
英語のマニュアルページと翻訳されたマニュアルページを同時にインストールするために、適切なターゲットが必要なことに注意してください。
最後に、生成したファイルをバージョン管理システムに格納したくなければ、
clean ターゲットに以下のような行が必要になるでしょう。
-rm -rf man/translated
Denis Barbier <barbier@linuxfr.org> Nicolas François <nicolas.francois@centraliens.net> Martin Quinson (mquinson#debian.org)
倉澤 望 <nabetaro@debian.or.jp> Debian JP Documentation ML <debian-doc@debian.or.jp>
本プログラムはフリーソフトウェアです。GPL の条項に基づき再頒布と変更を行うことができます (COPYING ファイルをご覧ください)。