PO4A(1p)

名前
po4a - PO ファイルと翻訳済みドキュメントの両方を一括更新

書式
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 ファイルの変更を (手での修正でも前述のステップでも) 翻訳済みドキュメントに反映します。

Normal case without specifying pot_in:

 <- source files ->|<--------- build results --------------->

 addendum ----------------------------------+
                                            |
 master document --+---------------------+  |
                   V                     +--+--> translations
 old PO files -----+--> updated PO files +
      ^                      |
      |                      V
      +<.....................+
    (the updated PO files are manually
     copied to the source of the next
     release while manually updating
     the translation contents)

Special case with specifying pot_in:

 <- source files ->|<--------- build results ----------------->

 master document --+--------------------------+
                   :                          |
 external          :    filtered              |
 filtering ========X..> master                |
 program                document              |
                        |                     |
                        V                     +--> translations
 old PO files ----------+--> updated PO files +
      ^                           |
      |                           V
      +<..........................+
    (the updated PO files are manually
     copied to the source of the next
     release while manually updating
     the translation contents)

The dataflow cannot be reversed in this tool, and changes in translations are overwritten by the content of the PO files. As a matter of fact, this tool cannot be used to convert existing translations to the po4a system. For that task, please refer to 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
 [type: docbook] doc/script.xml fr:doc/fr/script.xml \
             de:doc/de/script.xml \
             pot_in:doc/script.filtered.xml

これもまたかなり自己説明的だと思います。二番目のケースでは、doc/l10n/script.fr.add は、このドキュメントのフランス語版に追加する追加内容です。追加内容についての詳細情報は po4a(7) を参照してください。

もっと形式張って言うと、フォーマットは以下のようになります:

 [type: <format>] <master_doc> (<lang>:<localized_doc>)* \
                  (pot_in:<filtered_master_doc>)? \
                  (add_<lang>:<modifier>*<addendum_path>)*

If pot_in is specified, filtered_master_doc is used to create POT file instead of master_doc. This feature allows user to create flexible ways to avoid contents which shouldn't be included in the PO files. Tools such as C preprocessor (cpp) or XSL Transformation utility (e.g., xsltproc) can be used to create the external filtering program and call it before invoking po4a.

修飾子がない場合、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 スイッチにより指定されます。

If you need a specific option for one of the documents you want to translate, you can also specify it in the configuration file. Options are introduced by the opt keyword. The argument of the opt keyword must be quoted with double quotes if it contains a space (e.g. if you specify multiple options, or an option with an argument). You can also specify options that will only apply to a specific language by using the opt_lang keyword.

例を示します:
 [type:man] t-05-config/test02_man.1 $lang:tmp/test02_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 モジュールを元にした test というモジュールエイリアスを定義し、全言語に -k 21 を適用し、スペイン語の翻訳には -o debug=splitargs を適用します。

This module alias can then be used like a regular module:

 [type:test] t-05-config/test02_man.1 $lang:tmp/test02_man.$lang.1 \
            opt_it:"-L UTF-8" opt_fr:-v

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

  分割モード
[po4a_paths] 行に $master を使うと分割モードになります。

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

二つの 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

オプション

-k, --keep
    Minimal threshold for translation percentage to keep (i.e. write) the resulting file (default: 80). I.e. by default, files have to be translated at least at 80% to get written.

-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 にスタンプファイルを作成するように指示します。このスタンプファイルは翻訳済みドキュメントが期待する名前に .po4a-stamp 拡張子をつけた名前となります。

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

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

--no-update
    Do not change the POT and PO files, only the translation may be updated.

--keep-translations
    Keeps the existing translation files even if the translation doesn't meet the threshold specified by --keep. This option does not create new translation files with few content, but it will save existing translations which decay because of changes to the master files.

    WARNING: This flag changes the po4a behavior in a rather drastic way: your translated files will not get updated at all until the translation improves. Only use this flag if you prefer shipping an outdated translated documentation rather than only shipping an accurate untranslated documentation.

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

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

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

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

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

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

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

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

--porefs type[,wrap|nowrap]
    Specify the reference format. Argument type can be one of never to not produce any reference, file to only specify the file without the line number, counter to replace line number by an increasing counter, and full to include complete references (default: full).

    引数にはコンマを続けた後に wrap または nowrap キーワードのどちらかを付けられます。デフォルトでは、リファレンスは 1 行で書き出されます。wrap オプションは、gettext ツール (xgettext や msgmerge) のようにリファレンスを複数行に折り返します。こちらのオプションの方がより気が利いているため、将来のリリースでデフォルトとなります。元の挙動のままにしておきたいユーザは、nowrap オプションを使用できます。

--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" です。

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

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

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

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

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

  例
あなたは 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

Once this is set up you don't need to touch the Makefile when a new translation arrives, i.e. if the French team sends you fr.po and fr.add then you simply drop them respectively in man/po4a/po/ and man/po4a/add_fr/ and the next time the program is built the French translation is automatically build as well in man/translated/fr/.

英語のマニュアルページと翻訳されたマニュアルページを同時にインストールするために、適切なターゲットが必要なことに注意してください。

最後に、生成したファイルをバージョン管理システムに格納したくなければ、 clean ターゲットに以下のような行が必要になるでしょう:
        -rm -rf man/translated

欠点

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

パッチを歓迎します ;)

関連項目
po4a-gettextize(1), po4a-normalize(1), po4a-translate(1), po4a-updatepo(1), po4a(7)

著者
 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>

著作権とライセンス
Copyright 2002-2012 by SPI, inc.

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