書式

po4a [options] config_file

説明

po4a (PO for anything) プロジェクトは、gettext ツールが想定していないドキュメントのような領域で翻訳をしやすくすること (またより興味深いのは、翻訳文の保守がしやすくなること) を目標にしています。

po4a プログラムは、翻訳対象が複数だったり、フォーマットが異なったり、ドキュメントごとに異なるオプションを指定する必要がある場合に、po4a-gettextize(1), po4a-updatepo(1), po4a-translate(1) を複雑な Makefile で呼ばなくてすむようになります。

目次

このドキュメントは以下のような構成となっています。

説明

概要

設定ファイルの書式

テンプレート言語の指定

翻訳者入力ファイルのパス指定

パスや言語の自動検出

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

モジュールオプションの指定

エイリアスの指定

分割モード

オプション

例

欠点

著者

著作権・ライセンス

概要

po4a プログラムは、(オリジナルドキュメントと同期を取る) PO ファイルと (PO ファイルと同期を取る) 翻訳済みドキュメントの双方の更新を担当しています。主な目的は、コマンドラインオプションを覚えておかなくても、簡単に po4a を使用できるようにすることです。

また、異なるフォーマットが混在したドキュメントを同じ POT ファイルにでき、プロジェクトごとにひとつのファイルで管理できます。

こういったことは、po4a スイートの他のツールを (例えば Makefile とともに) 用いても同様にできますが、少々難しくなります。po4a を使用しているプロジェクトごとに、そのような複雑な Makefile を、何度も作成するのは大変です。

以下にデータフローをまとめました。マスタードキュメントの変更を PO ファイルに反映し、PO ファイルの変更を、(手での修正でも前述のステップでも) 翻訳済みドキュメントに反映します。

 マスタードキュメント --> PO ファイル --> 翻訳

このツールでは、データフローを逆にはできません。また、翻訳ファイルに対して変更しても、PO ファイルの内容で上書かれます。つまり、実のところ、このツールでは既存の翻訳を po4a システムに変換できないのです。このような用途には、po4a-gettextize(1) を参照してください。

設定ファイルの書式

(必須の) 引数は、使用する設定ファイルのパスです。この文法は単純であることを目指しており、intl-tools プロジェクトで使う設定ファイルに似ています。

このファイルでは、'#' に続けてコメントを記述でき、行末までをすべてコメントにします。行末をエスケープして、行をつなげることもできます。空行でない行は [] コマンドで始め、引数が続かなければなりません (こういうと難しく聞こえますが、思ったより簡単だと思います ;) )。

テンプレート言語の指定

注意: [po4a_langs] と [po4a_paths] よりも [po_directory] の使用をお勧めします。後述する パスや言語の自動検出 をご覧ください。

これは、設定ファイル全体を単純にし、より柔軟にするオプションコマンドです。ドキュメントを翻訳したい言語のリストを指定しなければなりません。単純に以下のようになります。

 [po4a_langs] fr de

これ以降の設定ファイル内で、$lang を指定した言語に展開するようになります。

翻訳者入力ファイルのパス指定

注意: [po4a_langs] と [po4a_paths] よりも [po_directory] の使用をお勧めします。後述する パスや言語の自動検出 をご覧ください。

まず、翻訳者入力ファイル (翻訳者が自分の作業に使用するファイル) の位置を指定する必要があります。以下のような行で行います。

 [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

パスや言語の自動検出

PO ファイルや POT ファイルの場所を、ディレクトリ名で指定するのに使用する、別のコマンドがあります。これを使用する場合、po4a は、指定したディレクトリにある *.pot ファイルのみを POT ファイルとして検出します。また po4a は、*.po ファイルのリストを、言語のリストとして (拡張子を除いて) 定義します。この言語は、続く設定ファイル内で $lang 変数を置換するのに使用されます。

このコマンドは、[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 は追加内容へのパスになります。修飾子は以下になります。

?

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

@

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

!

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

モジュールオプションの指定

po4a はモジュールに渡すオプションを受け付けます。このオプションはモジュール固有で、 -o スイッチにより指定されます。

翻訳したいドキュメントの一つに、特定のオプションが必要な場合、設定ファイルで指定することもできます。オプションは 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

ファイルごとの追加オプションも指定できることに注意してください。

分割モード

分割モードは、[po4a_paths] に $master を使うことで使用できます。

分割モードを使用する際、一時的に大きな POT ファイルと大きな PO ファイルを使用します。これにより、すべての PO 間で翻訳を共有できます。

2 つの PO で、同じ文字列に対して異なる翻訳がされている場合、po4a はその文字列を fuzzy としてマークし、その文字列を持つすべての PO に、両方の訳を出力します。その場合、翻訳者は訳を更新し、ひとつの PO から fuzzy タグを取り除くと、この文字列の訳は、すべての PO で自動的に更新されます。

オプション

-k, --keep

生成したファイルで維持する (つまり書き出す) 最低限の翻訳率 (デフォルト: 80) です。言い換えると、デフォルトでは、書き出されるために少なくとも 80％ は、翻訳されていなければならないということです。

-h, --help

短いヘルプメッセージを表示します。

-M, --master-charset

翻訳するドキュメントを含むファイルの文字セットです。すべてのマスタードキュメントが、同じ文字セットを使用していなければならないことに注意してください。これは既知の制限で、これを解消しようと作業をしています。

-L, --localized-charset

地域化したドキュメントを含むファイルの文字セットです。すべての翻訳済みドキュメントが、同じ文字セットを使用することに注意してください。これは既知の制限で、これを解消しようと作業をしています。

-A, --addendum-charset

追加内容の文字セット。追加内容では、すべて同じ文字セットを使用することに注意してください。

-V, --version

スクリプトのバージョンを表示し、終了します。

-v, --verbose

プログラムの冗長度を上げます。

-q, --quiet

プログラムの冗長度を下げます。

-d, --debug

デバッグ情報を出力します。

-o, --option

フォーマットプラグインに渡す追加オプションです。各オプションは、'name=value' のフォーマットで指定してください。有効なオプションやその意味の詳細は、各プラグインのドキュメントをご覧ください。

-f, --force

po4a が必要ないと見なしても、常に POT ファイルと PO ファイルを生成します。

デフォルトの動作 (--force を指定しない場合) は以下のようになります。

POT ファイルが存在する場合、マスターのドキュメントや設定ファイルの方が新しければ、再生成します。POT ファイルが一時ドキュメントに書き出され、変更が本当に必要かどうか po4a が検証も行います。

また、マスタードキュメント、PO ファイル、追加内容のどれか、設定ファイルのいずれかが翻訳より新しい場合にのみ、翻訳を再生成します。閾値テスト (--keep 参照) に合格しない翻訳を再生成しないように、.po4a-stamp 拡張子を持つファイルを作成します (--stamp 参照)。

マスタードキュメントにファイルをインクルードする場合、インクルードするファイルの更新時間は考慮に入らないため、--force フラグを使用するべきです。

PO ファイルは、常に POT を元に msgmerge -U で再生成されます。

--stamp

翻訳が閾値に到達せず生成されないとき、po4a に stamp ファイルを作成するように指示します。この stamp ファイルは翻訳済みドキュメントが期待する名前に .po4a-stamp 拡張子をつけた名前となります。

注意: これは .po4a-stamp ファイルの作成を行うだけです。stamp ファイルがある場合は常に使用され、--rm-translations を指定した場合や、最終的にファイルの翻訳が完了した場合に削除されます。

--no-translations

翻訳済みドキュメントを生成せず、POT ファイルや PO ファイルの更新のみ行います。

--rm-translations

翻訳済みファイルを削除します。(暗黙的に --no-translations)

--no-backups

このフラグは 0.41 から何もしなくなりました。また今後のリリースで削除される可能性があります。

--rm-backups

このフラグは 0.41 から何もしなくなりました。また今後のリリースで削除される可能性があります。

--translate-only translated-file

指定したファイルに対して、翻訳のみ行います。設定ファイル内にファイルがたくさん指定されている場合、処理の高速化に役立つことでしょう。このオプションは、PO ファイルと POT ファイルの更新を行わないことに注意してください。このオプションは複数回指定できます。

--variable var=value

po4a 設定ファイル内で展開する変数を定義します。現れるすべての $(var) は、value に置換されます。このオプションは複数回使用できます。

--msgid-bugs-address email@address

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

--copyright-holder string

POT ヘッダの著作権者 (copyright holder) をセットします。デフォルト値は ``Free Software Foundation, Inc.'' です。

--package-name string

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

--package-version string

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

--msgmerge-opt options

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

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

--no-previous

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

--previous

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

--srcdir SRCDIR

po4a 設定ファイルで指定した、すべての入力ドキュメントに対するベースディレクトリを指定します。

--destdir DESTDIR

po4a 設定ファイルで指定した、すべての出力ドキュメントに対するベースディレクトリを指定します。

例

あなたは foo というプログラムを保守しており、そのプログラムには、当然のように英語のみで書かれている、 man/foo.1 という man ページがあると仮定しましょう。今、上流ないし下流のメンテナとしてのあなたは、翻訳を作成し、保守したいと考えています。まず、po4a-gettextize(1) を使用して、翻訳者に送るために必要な POT ファイルを作成する必要があります。

この場合、以下のように実行します。

 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

欠点

• いくつかのコードは po4a-* プログラムと重複しています。

パッチを歓迎します。;)

著者

 Denis Barbier <[email protected]>
 Nicolas François <[email protected]>
 Martin Quinson (mquinson#debian.org)

著作権・ライセンス

Copyright 2002-2012 by SPI, inc.

本プログラムはフリーソフトウェアです。GPL の条項に基づき再頒布と変更を行うことができます (COPYING ファイルをご覧ください)。