Provided by: po4a_0.67-2_all 
名前
po4a - PO ファイルと翻訳済みドキュメントの両方を一括更新
書式
po4a [options] config_file
説明
po4a (PO for anything) は従来のgettextツールを使った文書翻訳の保守作業を容易にしま
す。po4aの主な特徴は内容の翻訳を文書構造から切り離すところにあります。このプロジェクトのや
さしい導入についてはページpo4a(7)を参照してください。
po4aプログラムは、設定ファイルと翻訳する文書（マスター文書と呼びます）だけを用意して初めて
実行すると、POTファイル（翻訳テンプレートとも呼びます）が作成されます。POTファイルは文書内
の全ての翻訳可能な文字列を含むため、翻訳者の作業が容易になります。
これらのPOTファイルは、GNOME Translation Editor、KDEのLokalizeのような特定のエディタで翻訳
したり、<weblate>やpootleのようなオンラインローカライゼーションプラットフォームに統合した
りできます。翻訳結果は言語ごとに1つのPOファイルの集合になります。
マスター文書とPOファイルの両方を使用してpo4aプログラムを実行すると、内容の翻訳（POファイル
にあります）を元のマスター文書の構造に注入することにより、翻訳文書が生成されます。
しばらくしてマスター文書が変更された場合、po4aはそれに応じてPOファイルとPOTファイルを更新
します。そのため翻訳者は簡単に変更点を見つけて更新作業を行うことができます。設定に応じ
て、po4a は部分的に翻訳された文書を破棄するか、英語（新規または変更された段落の場合）と対
象言語（翻訳が既に PO ファイルにある段落の場合）を混在させた文書を生成します。
既定では、翻訳文書は内容の少なくとも80%が翻訳された時点で生成されます（後述の--keepオプ
ションを参照）。 翻訳が100%でないからといって問答無用で翻訳を無視する挙動は翻訳者の意欲を
そぐことになります。一方であまりにも不完全な「翻訳」を表示すると、エンドユーザーが困ってし
まうかもしれません。
概要図
master documents ---+---->-------->---------+
(doc authoring) | |
V (po4a executions) >-----+--> translations
| | |
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: 補遺
マスター文書は文書執筆者によって作成されます。変更は全てpo4aによって自動的にPOファイルに反
映され、そのPOファイルは翻訳者によって更新されます。POファイルに対する（手動またはpo4aによ
る）全ての変更は、自動的に翻訳文書に反映されます。po4a-updatepo(1) と po4a-translate(1) ス
クリプトを使ってMakefileを書けばこの動作を真似ることもできますが、すぐに面倒な作業の繰り返
しになります（po4a(7) を参照してください）。ビルドの際には、po4aプログラムを使用することを
強くお勧めします。
オプション
-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
書式プラグインに渡す追加オプションです。有効なオプションやその意味の詳細は、各プラグイ
ンの説明書を参照してください。例えば、AsciiDocパーサーには '-o tablecells' を、テキス
トパーサーには '-o tabs=split' を渡すことができます。
-f, --force
生成の必要はないと po4a が判断した場合でも、常に POT ファイルと PO ファイルを生成しま
す。
デフォルトの動作 (--force を指定しない場合) は以下のようになります:
POT ファイルが存在する場合、マスター文書や設定ファイルの方が新しければ
（--no-updateが指定されている場合を除き）再生成を実行します。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
POT、POのファイルは変更せず、翻訳のみを更新することができます。
--keep-translations
翻訳が --keep で指定された閾値を満たしていない場合でも、既存の翻訳ファイルを保持しま
す。 このオプションでは、内容の乏しい新しい翻訳ファイルは作成されませんが、マスター
ファイルへの変更のために陳腐化した既存の翻訳が保存されます。
警告：このフラグは po4a の動作をかなり大幅に変更します。というのは、翻訳が改善されるま
で、あなたの翻訳したファイルはまったく更新されないからです。正確な未翻訳の文書より、古
びた翻訳文書のほうを世に出したい場合にのみ、このフラグを使用してください。
--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 設定ファイルで指定されたすべての入力文書に対する基底ディレクトリを指定します。
l<destdir>とl<srcdir>の両方が指定された場合、入力ファイルはl<destdir>、現在のディレク
トリ、l<srcdir>の順番で探索します。出力ファイルは、指定されていればl<destdir>に、そう
でなければ現在のディレクトリに書き出されます。
--destdir DESTDIR
po4aの設定ファイルで指定されたすべての出力文書の基底ディレクトリを設定します（前述
の--srcdirを参照）。
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 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 以
降が必要で、デフォルトで有効です。
設定ファイル
po4a は引数として設定ファイルを必要とします。このファイルには、次の要素が含まれている必要
があります。
• POファイルのパスおよびプロジェクトに存在する言語のリスト、
• オプションとして、いくつかの大域オプションと、個々のマスターファイルを設定するためのテ
ンプレートとして使用される、いわゆる設定エイリアス、
• 翻訳する各マスターファイルとそれぞれに指定する引数の一覧。
各行は角括弧で囲まれた命令とその後に続く引数で構成されています。 コメントは文字 '#' で始ま
り行末まで続きます。行末をエスケープすることで複数行にわたる命令を書けます。
このページでは、いくつかの完全な例を紹介していますが、他の例はソース配布物の"t/cfg"ディレ
クトリにあります。
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
With this line, po4a will produce separate POT and PO files for each document to
translate. For example, if you have 3 documents and 5 languages, this will result in 3
POT files and 15 PO files. These files are named as specified on the "po4a_paths"
template, with $master substituted to the basename of each document to translate. In case
of name conflict, you can specify the POT file to use as follows, with the "pot="
parameter. This feature can also be used to group several translated files into the same
POT file.
[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-gui
[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 ファイルで自動的に使用され
ます。
翻訳するドキュメントの指定
You must also list the documents that should be translated. For each master file, you must
specify the format parser to use, the location of the translated document to produce, and
optionally some configuration. Here is an example:
[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
But again, these complex lines are difficult to read and modify, e.g. when adding a new
language. It is much simpler to reorganize things using the $lang template as follows:
[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
オプションの指定
There is two types of options: po4a options are default values to the po4a command line
options while format options are used to change the behavior of the format parsers. As a
po4a options, you could for example specify in your configuration file that the default
value of the --keep command line parameter is 50% instead of 80%. Format options are
documented on the specific page of each parsing module, e.g. Locale::Po4a::Xml(3pm). You
could for example pass nostrip to the XML parser to not strip the spaces around the
extracted strings.
You can pass these options for a specific master file, or even for a specific translation
of that file, using "opt:" and "opt_XX:" for the "XX" language. In the following example,
the nostrip option is passed to the XML parser (for all languages), while the threshold
will be reduced to 0% for the French translation (that is thus always kept).
[type:xml] toto.xml $lang:toto.$lang.xml opt:"-o nostrip" opt_fr:"--keep 0"
In any case, these configuration chunks must be located at the end of the line. The
declaration of files must come first, then the addendum if any (see below), and then only
the options. The grouping of configuration chunks is not very important, since elements
are internally concatenated as strings. The following examples are all equivalent:
[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
Note that language specific options are not used when building the POT file. It is for
example impossible to pass nostrip to the parser only when building the French
translation, because the same POT file is used to update every languages. So the only
options that can be language-specific are the ones that are used when producing the
translation, as the "--keep" option.
設定ファイルのエイリアス
To pass the same options to several files, the best is to define a type alias as follows.
In the next example, "--keep 0" is passed to every Italian translation using this "test"
type, that is an extension of the "man" type.
[po4a_alias:test] man opt_it:"--keep 0"
[type: test] man/page.1 $lang:man/$lang/page.1
You can also extend an existing type reusing the same name for the alias as follows. This
is not interpreted as as an erroneous recursive definition.
[po4a_alias:man] man opt_it:"--keep 0"
[type: man] man/page.1 $lang:man/$lang/page.1
Global default options
You can also use "[options]" lines to define options that must be used for all files,
regardless of their type.
[options] --keep 20 --option nostrip
As with the command line options, you can abbreviate the parameters passed in the
configuration file:
[options] -k 20 -o nostrip
Option priorities
The options of every sources are concatenated, ensuring that the default values can easily
be overridden by more specific options. The order is as follows:
• "[options]" lines provide default values that can be overridden by any other source.
• Type aliases are then used. Language specific settings override the ones applicable to
all languages.
• Settings that are specific to a given master file override both the default ones and
the ones coming from the type alias. In this case also, language specific settings
override the global ones.
• Finally, parameters provided on the po4a command line override any settings from the
configuration file.
Example
Here is an example showing how to quote the spaces and quotes:
[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
補遺：翻訳に追記する
If you want to add an extra section to the translation, for example to give credit to the
translator, then you need to define an addendum to the line defining your master file.
Please refer to the page po4a(7) for more details on the syntax of addendum files.
[type: pod] script fr:doc/fr/script.1 \
add_fr:doc/l10n/script.fr.add
You can also use language templates as follow:
[type: pod] script $lang:doc/$lang/script.1 \
add_$lang:doc/l10n/script.$lang.add
If an addendum fails to apply, the translation is discarded.
Modifiers for the addendum declaration
Addendum modifiers can simplify the configuration file in the case where not all languages
provide an addendum, or when the list of addenda changes from one language to the other.
The modifier is a single char located before the file name.
? ファイルが存在する場合 addendum_path を含めます。なければ何もしません。
@ addendum_path は通常の追加内容ファイルではなく、追加内容ファイルのリスト (1 行 1 ファイ
ル) です。各追加内容ファイルの前に修飾子を追加できます。
! addendum_path は読み込まれません。また、その他の追加内容で読み込まれるように指定してあっ
ても読み込まれません。
The following includes an addendum in any language, but if only it exists. No error is
reported if the addendum does not exist.
[type: pod] script $lang:doc/$lang/script.1 add_$lang:?doc/l10n/script.$lang.add
The following includes a list of addendum for every language:
[type: pod] script $lang:doc/$lang/script.1 add_$lang:@doc/l10n/script.$lang.add
翻訳する文字列の選別
Sometimes, you want to hide some strings from the translation process. To that extend, you
can give a "pot_in" parameter to your master file to specify the name of the file to use
instead of the real master when building the POT file. Here is an example:
[type:docbook] book.xml \
pot_in:book-filtered.xml \
$lang:book.$lang.xml
With this setting, the strings to translate will be extracted from the book-filtered.xml
(that must be produced before calling po4a) while the translated files will be built from
book.xml. As a result, any string that is part of book.xml but not in book-filtered.xml
will not be included in the PO files, preventing the translators from providing a
translation for them. So these strings will be left unmodified when producing the
translated documents. This naturally decreases the level of translation, so you may need
the "--keep" option to ensure that the document is produced anyway.
設定例
TODO: Is this section really useful?
あなたは 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-gettextize(1), po4a-normalize(1), po4a-translate(1), po4a-updatepo(1), po4a(7).
著者
Denis Barbier <barbier@linuxfr.org>
Nicolas Francois <nicolas.francois@centraliens.net>
Martin Quinson (mquinson#debian.org)
訳者
倉澤 望 <nabetaro@debian.or.jp>
Debian JP Documentation ML <debian-doc@debian.or.jp>
著作権とライセンス
Copyright 2002-2020 by SPI, inc.
本プログラムはフリーソフトウェアです。GPL の条項に基づき再頒布と変更を行うことができます
(COPYING ファイルを参照してください)。