| PO4A(7) | Po4a Tools | PO4A(7) |
po4a - ドキュメントやその他の素材の翻訳フレームワーク
po4a (PO for anything) プロジェクトは、gettext ツールが想定していないドキュメントのような領域で翻訳をしやすくすること (またより興味深いのは、翻訳文の保守がしやすくなること) を目標にしています。
このドキュメントは以下のような構成となっています:
この節は実際には本ドキュメント本来の部分ではなく、各モジュールのドキュメントにあります。これにより、ドキュメントとコードを共に保守し、確実に情報が最新となるのを助けます。
誰でもソフトウェアやそのソースコードにアクセスできるようにするオープンソースの考え方が私は好きです。しかしフランス人であり、ソフトウェアのオープン度がライセンスのみでないことをよく意識しています。翻訳されていないフリーソフトウェアは、非英語圏の人々には役に立たないのです。ですから本当に誰でも利用できるように、まだ作業を行っています。
オープンソース活動家のこの状況の認知度は、最近劇的に向上しました。翻訳者として最初の戦いに勝利し、翻訳の重要性を周知できました。しかし残念ながら、これはまだ簡単な部類でした。今度は、すべてを翻訳するよう作業しなければなりません。
実際には、オープンソースソフトウェア自身は、すばらしい gettext ツール群のおかげでかなりきちんと翻訳の恩恵にあずかっています。これはプログラムから翻訳する文字列を抽出し、翻訳者に決まった形で提供し、実行時には、作業の成果である翻訳済みのメッセージをユーザに表示できます。
しかし、ドキュメントに関しては状況が大きく異なります。あまりにも頻繁に、翻訳されたドキュメントが十分見えるようになっていない (プログラムの一部として配布されない)、一部しか訳されていない、更新されていないといったことが起きています。最後の状況はあり得る中で最悪なものです。古い翻訳がもはや使われなくなった古い動作を説明しているため、まったく翻訳されていない状況よりもひどい結果になります。
ドキュメントの翻訳は、本来そんなに難しくありません。テキストはプログラムのメッセージよりもずっと長く、訳了するのに時間がかかりますが、技術スキルが本当に必要というわけではないのです。難しい部分は成果物を保守しようとしたときに現れます。変更箇所や更新すべき箇所を探し出すのは非常に難しく、誤りやすく、苦痛をともなう作業です。世の中にこんなにも時代遅れなドキュメントが存在しているのは、これが原因だと考えています。
そこで、po4a の核心は、ドキュメントの翻訳を保守できるようにすることです。そのアイデアは、この新しい分野に gettext の方法論を再利用することです。gettext のように、翻訳者に一様なフォーマットで提示するために、テキストはそのオリジナルの場所から抽出されます。オリジナルの新しいリリースが出てきた時に、古典的な gettext ツールは翻訳者が翻訳を更新するのを手助けします。しかし、古典的な gettext モデルとは異なり、翻訳はオリジナルドキュメントの構造に再度注入され、翻訳は英語バージョンと同じように処理や配布をすることができます。
このおかげで、ドキュメントのどこが変更され、修正する必要があるかを見つけるのが、非常に簡単になりました。ほかの長所としては、オリジナルドキュメントの構造が根本的に再編成されて、章が移動、結合、分割されたとしても、ほとんどすべての作業をツールが行うということもあります。翻訳用にドキュメント構造からテキストを抽出することで複雑なテキストフォーマットに触らずに済み、ドキュメントを壊してしまう可能性を (完全になくすというわけには行きませんが) 低くできます。
このアプローチの利点と欠点のより詳しい一覧は、このドキュメントの後ろの FAQ を参照してください。
現在、このアプローチで実装に成功しているのは、以下のテキスト整形フォーマットです:
man
たくさんのプログラムで使われている、古き良きマニュアルページのフォーマットです。このフォーマットはいくらか難しく、初心者には本当に易しくないので po4a のサポートは非常に歓迎されています。Locale::Po4a::Man(3pm) モジュールは、BSD man ページ (Linux でも本当に一般的) で使用されている mdoc フォーマットもサポートしています。
pod
Perl のオンラインドキュメントフォーマットです。言語や拡張機能自体が、既存の Perl スクリプトと同じように記述されています。同じファイルに組み込んで、実際のコードのそばにドキュメントを記述し保守しやすくしています。プログラマーの生活は楽になりますが、残念ながら翻訳者の生活は楽にはなりません。
sgml
最近はいくらか XML に取って代わられましたが、このフォーマットは数画面以上の長いドキュメントでまだかなり頻繁に使用されます。これで完全な本を作ることができます。あまりにもドキュメントが長いため、翻訳を更新するのはまさしく悪夢といえます。また、オリジナルドキュメントを更新すると、インデントが再構成されるため、diff もあまり役に立ちません。幸い、po4a はこの処理でも助けになります。
現在、DebianDoc と DocBook DTD のみサポートしていますが、新しくサポートするものを追加するのは、本当に簡単です。また、コマンドラインに必要な情報を与え、コードを変更せずに未知の SGML DTD を po4a で使用することもできます。詳細は Locale::Po4a::Sgml(3pm) を参照してください。
TeX / LaTeX
LaTeX フォーマットはフリーソフトウェア界や出版界で使われている有名なフォーマットです。Locale::Po4a::LaTeX(3pm) モジュールは Python のドキュメントや書籍、各種発表でテストされています。
texinfo
GNU のドキュメントはすべてこのフォーマットで書かれています (公式 GNU プロジェクトになる必要条件の一つです)。po4a のLocale::Po4a::Texinfo(3pm) サポートは始まったばかりです。バグ報告や機能のリクエストをお願いします。
xml
XML フォーマットは多くのドキュメントフォーマットの基礎になっています。
現在、po4a では DocBook の DTD をサポートしています。詳細は、Locale::Po4a::Docbook(3pm) を参照してください。
その他
Po4a can also handle some more rare or specialized formats, such as the documentation of compilation options for the 2.4+ Linux kernels or the diagrams produced by the dia tool. Adding a new one is often very easy and the main task is to come up with a parser of your target format. See Locale::Po4a::TransTractor(3pm) for more information about this.
残念ながら、po4a はいくつかのドキュメントフォーマットのサポートを欠いています。
ドキュメントだけではなく、po4a でサポートしたいほかのフォーマットがたくさんあります。まさしく私たちは、古典的な gettext ツールが残した「市場の穴」を埋めるのを目標としています。そこには、パッケージの説明 (deb や rpm) や、パッケージのインストールスクリプトの質問、パッケージの changelog、ゲームのシナリオや wine リソースファイルといったプログラムが使用するすべての特殊ファイルが含まれます。
この章は、処理全体を理解していただけるようにユーザの質問に答える形のリファレンスマニュアルの一種です。po4a をどのように使用するかを紹介し、特定のツールのドキュメントへの導入として役立ちます。
以下の図は po4a を用いたドキュメント翻訳過程の概要です。複雑になってしまいましたが、おじけづかないでください。処理の 全体 を表そうとして、このようになってしまいました。いったんプロジェクトを po4a に変換すると図の右の部分のみが関係します。
Note that master.doc is taken as an example for the documentation to be translated and translation.doc is the corresponding translated text. The suffix could be .pod, .xml, or .sgml depending on its format. Each part of the picture will be detailed in the next sections.
master.doc
|
V
+<-----<----+<-----<-----<--------+------->-------->-------+
: | | :
{translation} | { update of master.doc } :
: | | :
XX.doc | V V
(optional) | master.doc ->-------->------>+
: | (new) |
V V | |
[po4a-gettextize] doc.XX.po -->+ | |
| (old) | | |
| ^ V V |
| | [po4a-updatepo] |
V | | V
translation.pot ^ V |
| | doc.XX.po |
| | (fuzzy) |
{ translation } | | |
| ^ V V
| | {manual editing} |
| | | |
V | V V
doc.XX.po --->---->+<---<-- doc.XX.po addendum master.doc
(initial) (up-to-date) (optional) (up-to-date)
: | | |
: V | |
+----->----->----->------> + | |
| | |
V V V
+------>-----+------<------+
|
V
[po4a-translate]
|
V
XX.doc
(up-to-date)
On the left part, the conversion of a translation not using po4a to this system is shown. On the top of the right part, the action of the original author is depicted (updating the documentation). The middle of the right part is where the automatic actions of po4a are depicted. The new material are extracted, and compared against the exiting translation. Parts which didn't change are found, and previous translation is used. Parts which were partially modified are also connected to the previous translation, but with a specific marker indicating that the translation must be updated. The bottom of the figure shows how a formatted document is built.
Actually, as a translator, the only manual operation you have to do is the part marked {manual editing}. Yeah, I'm sorry, but po4a helps you translate. It does not translate anything for you…
この節では、po4a で新しく翻訳を始めるのに必要な手順を説明します。既存プロジェクトをこのシステムに変換する方法は、関連する節で詳しく取り扱います。
po4a を用いて新しく翻訳を始めるには、以下の手順を行う必要があります:
$ po4a-gettextize -f <format> -m <master.doc> -p <translation.pot>
<format> は、当然 master.doc ドキュメントで使用されるフォーマットです。予想されたように、出力は translation.pot になります。既存のオプションの詳細は po4a-gettextize(1) を参照してください。
実際の翻訳には、Emacs や Vi の PO mode、Lokalize (KDE ベース)、Gtranslator (GNOME ベース)、その他 (例えば Virtaal) より、あなたが作業しやすいものを使うことができます。
翻訳作業について詳しく学びたい場合は、間違いなく gettext-doc パッケージにある gettext のドキュメントを参照する必要があります。
翻訳を完了したら、翻訳されたドキュメントを取得し、オリジナルのものと一緒にユーザに提供したいと思います。そのために、以下のように po4a-translate(1) プログラムを使用してください (XX の箇所は言語コードです):
$ po4a-translate -f <format> -m <master.doc> -p <doc.XX.po> -l <XX.doc>
先ほどと同様に、<format> は master.doc ドキュメントで使用しているフォーマットです。しかし今度は、-p フラグで指定する PO ファイルが入力部にあります。これはあなたが翻訳したものです。XX.doc に出力します。
詳細は po4a-translate(1) を参照してください。
オリジナルの master.doc ファイルが変更された時に翻訳を更新するには、po4a-updatepo(1) を以下のように使用します:
$ po4a-updatepo -f <format> -m <new_master.doc> -p <old_doc.XX.po>
(詳細は po4a-updatepo(1) を参照してください)
当然のことながら、この操作でドキュメントの新しい段落が魔法のように PO ファイルで翻訳されているということはありません。PO ファイルを手で更新する必要があります。さらに、少し変更された段落のために翻訳を手直しする必要があります。変更された段落を見逃さないように、処理中に "fuzzy" マーカが付けられるので、po4a-translate でその翻訳を処理する前に、のマーカを消さなければなりません。最初の翻訳と同様に、作業しやすい PO エディタを使うのがベストです。
未訳部や fuzzy な部分を取り除いて PO ファイルを再度最新にしたら、前節で説明したように翻訳済みドキュメントファイルを生成できます。
オリジナルの master.doc ドキュメントが大きく再編成されるまでは、手で翻訳するのに不満はなかったでしょう。diff のようなツールがうまくいかなくなったから po4a に乗り換えようとしているのだと思います。もちろん、この処理で既存の翻訳を失いたくはありません。ご心配なく。この場合も po4a では扱えます。これを gettext 化と呼びます。
ここで重要なのは、翻訳とオリジナルが同一の構造になっていることで、ツールがそれぞれの内容を対応付けられることです。
あなたがツイていれば (つまり両方のドキュメントの構造が完全に一致するとか)、シームレスに一瞬で完了します。そうでなければ、この手順になぜこんなひどい名前が付いているのか理解するでしょう。とはいえこんなひどい作業でも準備しておくに越したことはありません。いずれにしろ、po4a で後々楽になるために支払う価値があると思ってください。ありがたいことに一回だけやればいいのです。
改めて強調します。処理を容易にするために、翻訳を行うために使用された正確なバージョンを見つけることはとても重要です。翻訳に使った VCS のリビジョンを記録していて、さらに翻訳の過程でそれを変更していないならばベストな状況です。そうなら、そのリビジョンを使うことができます。
更新されたオリジナルテキストを古い翻訳と一緒に使用するのはうまくいきません。そういったこともできますが、本当に大変で、できれば避けた方がいいでしょう。事実上、もう一度オリジナルテキストを見つけられないなら、一番いいのはあなたのために gettext 化してくれる人を見つけることでしょう。(あ、いや、私じゃないですよ ;)
おそらくドラマチックすぎるでしょうが、何か問題があるとしても、すべてをもう一度翻訳し直すよりは速いと思います。既存の Perl ドキュメントフランス語訳を gettext 化するのに、問題も ありました が 1 日でできました。これは 2MB のテキストで、新規に翻訳するには数ヶ月を要したでしょう。
ではまず、手順の基本を説明します。それから何か問題があれば戻ってきてヒントを示したいと思います。理解しやすいように、もう一度上記の例を使用しましょう。
翻訳した XX.doc に対応する古い master.doc を用意できたら、translation.pot ファイルを手で訳さなくても PO ファイル doc.XX.po を直接 gettext 化できます:
$ po4a-gettextize -f <format> -m <old_master.doc> -l <XX.doc> -p <doc.XX.po>
ツイているならこれで完了です。古い翻訳を po4a に変換し、すぐに更新タスクを行えます。数節前に説明した、最新のオリジナルドキュメントと PO ファイルの同期を取る手順に従い、翻訳を更新してください。
うまくいっているように見えても、この処理に誤りの入り込む余地があることに注意してください。ポイントは、po4a がオリジナルと翻訳が一致しているかどうかを理解できないということです。この処理の結果、すべての文字列に "fuzzy" マークが付いてしまうのはこういうわけです。マーカを削除する前に、注意してチェックする必要があります。
しばしば、ドキュメント構造が完全には一致せず、po4a-gettextize が正常に機能しません。この時点で、ゲームはその腐った構造をすりあわせていく作業がすべてになります。
後にある gettext 化: どのように動作しますか? 節を読むと参考になると思います。内部処理を理解することは、この作業の助けになります。po4a-gettextize の利点は、何か問題が発生すると、詳しく教えてくれることです。まず、ドキュメントに構造上の食い違いがある場合、その箇所を指摘します。これで一致しない文字列や、テキスト中の箇所、それらの型が分かります。さらに、そこまでで生成した PO ファイルは gettextization.failed.po に書き出してあります。
同様に、POD では、分割行に空白が入っていたり、=item 行と item の内容の間に空行がない場合、二つの段落を一つにまとめてしまいます。
この不幸な状況は、同じ段落がドキュメント中で繰り返されているときに起こります。この場合、PO ファイルに新しいエントリは追加されませんが、既存のエントリに参照が追加されます。
So, when the same paragraph appears twice in the original but both are not translated in the exact same way each time, you will get the feeling that a paragraph of the original disappeared. Just kill the new translation. If you prefer to kill the first translation instead when the second one was actually better, replace the first one with the second.
反対に、二つの似て非なる段落が全く同じように翻訳されていると、翻訳した段落が消えてしまったように感じることでしょう。その場合は、無駄な文字列をオリジナルの段落に追加すると解決します ("I'm different" など)。これは同期の際に消えますが、気にしないでください。追加したテキストが十分短ければ、gettext はその翻訳と既存のテキストをマッチします。(fuzzy にしますが、gettext 化した後は、すべての文字列が fuzzy になるので気にすることはありません)
うまくいけば、以上の小技は gettext 化作業を助け、貴重な PO ファイルが得られるでしょう。ファイルの同期や、翻訳を始める準備ができています。大きなテキストの場合、最初の同期に時間がかかる場合があることに注意してください。
例えば、初めてフランス語版 Perl ドキュメント (5.5 MB の PO ファイル) に po4a-updatepo を実行したとき、1GHz G5 コンピュータでまるまる 2 日かかりました。ええ、48 時間です。しかしその後は、私の古いノートパソコンで十数秒しかかかりません。これは初回の実行で、PO ファイルのほとんどの msgid が POT ファイルのものと一致しなかったからです。このため gettext は、もっとも近いものを探すのに、実行コストの高い文字列近接アルゴリズムを使わなくてはなりません。
gettext アプローチのため、po4a でのテキストの追加は単にオリジナルのものにそって新しいファイルを編集するよりも難しくなっています。しかし、いわゆる 追加内容 のおかげで追加できます。
追加内容を、処理後のローカライズしたドキュメントに適用するパッチの類として見なすとわかりやすいでしょう。通常のパッチとはかなり異なっています (1 行だけの文章、Perl の正規表現を埋め込み、削除できず新しいテキストの追加のみ) が、実用上は同じです。
目的は、オリジナルドキュメントにない内容を翻訳済みドキュメントに追加できるようにすることです。よくある使用法は、翻訳自体に関する節や、貢献者リスト、翻訳についてのバグレポートのしかたを追加することです。
追加内容は別個のファイルで提供されなければなりません。最初の行では、生成したドキュメントのどこに配置するかのヘッダを記述します。追加内容ファイルの残りは、結果のドキュメントの決まった場所にそのまま追加されます。
The header line which specify context has a pretty rigid syntax: It must begin with the string PO4A-HEADER:, followed by a semi-colon (;) separated list of key=value fields. White spaces ARE important. Note that you cannot use the semi-colon char (;) in the value, and that quoting it doesn't help. Optionally, spaces ( ) may be inserted before key for readability.
Although this context search may be considered to operate roughly on each line of the translated document, it actually operates on the internal data string of the translated document. This internal data string may be a text spanning a paragraph containing multiple lines or may be a XML tag itself alone. The exact insertion point of the addendum must be before or after the internal data string and can not be within the internal data string.
The actual internal data string of the translated document can be visualized by executing po4a in debug mode.
また恐ろしげに聞こえますが、以下の例は、必要なヘッダ行の記述法を見つける手助けになるでしょう。議論の前提として、"About this document" 節の後に "About this translation" 節を追加することとします。
以下に有効なヘッダキーを挙げます:
If mode=before, the insertion point is determined by one step regex match specified by the position argument regex. The insertion point is immediately before the uniquely matched internal data string of the translated document.
If mode=after, the insertion point is determined by two step regex matches specified by the position argument regex; and by the beginboundary or endboundary argument regex.
Since there may be multiple sections for the assumed case, let's use 2 step approach.
mode=after
If more than one internal data strings match this expression (or none), the search for the insertion point and addition of the addendum will fail. It is indeed better to report an error than inserting the addendum at the wrong location.
If mode=before, the insertion point is specified to be immediately before the internal data string uniquely matching the position argument regex.
If mode=after, the search for the insertion point is narrowed down to the data after the internal data string uniquely matching the position argument regex. The exact insertion point is further specified by the beginboundary or endboundary.
In our case, we need to skip several preceding sections by narrowing down search using the section title string.
position=About this document
(In reality, you need to use the translated section title string here, instead.)
この場合、以下のように追加して節の終わりに一致するように指定できます:
endboundary=</section>
また、以下のようにして次の節の直前を指定できます:
beginboundary=<section>
In both cases, our addendum will be placed after the </section> and before the <section>. The first one is better since it will work even if the document gets reorganized.
どちらの形態もあるのは、異なるドキュメントフォーマットがあるからです。その中には (使用したばかりの </section> のような) 節の終わりを示すもの、(man のような) 節の終わりを明確に示さないものがあります。前者では、boundary が節の最後にマッチするので、追加位置はその後になります。後者では、boundary が次節の先頭にマッチするので、追加位置はその前になります。
これは分かりにくいですが、次の例でよく分かると思います。
PO4A-HEADER: mode=after; position=About this document; endboundary=</section>
PO4A-HEADER: mode=after; position=About this document; beginboundary=<section>
.SH "AUTHORS"
You should select two step approach by setting mode=after. Then you should narrow down search to the line after AUTHORS with the position argument regex. Then, you should match the beginning of the next section (i.e., ^\.SH) with the beginboundary argument regex. That is to say:
PO4A-HEADER:mode=after;position=AUTHORS;beginboundary=\.SH
PO4A-HEADER:mode=after;position=Copyright Big Dude, 2004;beginboundary=^
PO4A-HEADER:mode=after;position=About this document;beginboundary=FakePo4aBoundary
いずれの場合にも、正規表現であることを忘れないでください。例えば、次の行で終わっている nroff 節の最後にマッチしたい場合を考えます。
.fi
endboundary として .fi を使用しないでください。明らかに想定していない "the[ fi]le" にもマッチしてしまいます。この場合の正しい endboundary は ^\.fi$ です。
追加内容が想定通りにうまく動作しない場合、-vv 引数をツールに渡してみてください。追加内容を配置する際の挙動を表示してくれます。
もっと詳細な例
オリジナルドキュメント (POD フォーマット):
|=head1 NAME | |dummy - a dummy program | |=head1 AUTHOR | |me
そして、以下の追加内容は、(フランス語で)「翻訳者について」節をファイルの最後に追加します。(フランス語の "TRADUCTEUR" は "TRANSLATOR"、"moi" は "me" の意味です)
|PO4A-HEADER:mode=after;position=AUTEUR;beginboundary=^=head | |=head1 TRADUCTEUR | |moi |
AUTHOR の前に追加内容を追加するには、以下のヘッダを使用してください:
PO4A-HEADER:mode=after;position=NOM;beginboundary=^=head1
This works because the next line matching the beginboundary /^=head1/ after the section "NAME" (translated to "NOM" in French), is the one declaring the authors. So, the addendum will be put between both sections. Note that if another section is added between NAME and AUTHOR sections later, po4a will wrongfully put the addenda before the new section.
To avoid this you may accomplish the same using mode=before:
PO4A-HEADER:mode=before;position=^=head1 AUTEUR
po4a を使うことは、それぞれ 3 つ以上の引数が必要な二つの異なるプログラムをユーザが正しい順番 (po4a-updatepo のあとに po4a-translate) で実行しなければならないということで、少々誤る傾向にあるということがわかりました。その上、複数のフォーマットが使われているすべてのドキュメントを一つだけの PO ファイルにするのは、このシステムでは難しいことでした。
この難しさを解消するために po4a(1) プログラムは設計されました。一度このシステムに移行してしまえば、簡単な設定ファイルに翻訳用ファイル (po と pot) の位置、原版の位置や形式、翻訳版の位置を記述するシンプルな設定ファイルを書くことになります。
それから、このファイルで po4a(1) を呼ぶことで、PO ファイルがオリジナルドキュメントに対して同期が取れており、翻訳済みドキュメントが適切に生成されることを保証できます。もちろん、このプログラムを二度呼んでもかまいません。一度目は編集前に PO ファイルを更新するために、二度目はその後で、完璧に更新された翻訳済みドキュメントを得るために。しかし、覚えておく必要があるのはただ一つのコマンドラインだけです。
po4a モジュールには、モジュールの挙動を変更するオプション (-o オプションで指定) があります。
You can also edit the source code of the existing modules or even write your own modules. To make them visible to po4a, copy your modules into a path called "/bli/blah/blu/lib/Locale/Po4a/" and then adding the path "/bli/blah/blu" in the "PERLIB" or "PERL5LIB" environment variable. For example:
PERLLIB=$PWD/lib po4a --previous po4a/po4a.cfg
注: lib ディレクトリの実際の名前は重要ではありません。
この章では、保守改良を自信を持って助けていただけるよう po4a 内部の概要を説明します。また、なぜ思ったように動作しないか、どのように問題を解決すればいいかを理解する助けになるかもしれません。
po4a のアーキテクチャはオブジェクト指向です (Perl で。イケてる?)。すべてのパーサクラス共通の派生元は、TransTractor と呼ばれています。このヘンな名前は、ドキュメントの翻訳と文字列の抽出を同時に行うところから付けられています。
もっと形式張っていうと、入力として翻訳するドキュメントと翻訳が入っている PO ファイルを取り、結果を以下の二つに分けて出力します。別の PO ファイル (入力ドキュメントから翻訳可能な文字列を抽出した結果) と、翻訳済みドキュメント (入力したファイルと同じ構造ですが、翻訳可能な文字列は入力 PO ファイルの内容で置換されているファイル) です。以下に図示します:
入力ドキュメント-\ /---> 出力ドキュメント
\ TransTractor:: / (翻訳済み)
+-->-- parse() --------+
/ \
入力 PO ---------/ \---> 出力 PO
(抽出済み)
This little bone is the core of all the po4a architecture. If you omit the input PO and the output document, you get po4a-gettextize. If you provide both input and disregard the output PO, you get po4a-translate. The po4a calls TransTractor twice and calls msgmerge -U between these TransTractor invocations to provide one-stop solution with a single configuration file.
TransTractor::parse() は各モジュールで実装されている仮想関数です。どのように動作するかを説明するのに、簡単なサンプルがあります。これは、先頭に <p> が付いた段落のリストをパースします。
1 sub parse {
2 PARAGRAPH: while (1) {
3 $my ($paragraph,$pararef,$line,$lref)=("","","","");
4 $my $first=1;
5 while (($line,$lref)=$document->shiftline() && defined($line)) {
6 if ($line =~ m/<p>/ && !$first--; ) {
7 $document->unshiftline($line,$lref);
8
9 $paragraph =~ s/^<p>//s;
10 $document->pushline("<p>".$document->translate($paragraph,$pararef));
11
12 next PARAGRAPH;
13 } else {
14 $paragraph .= $line;
15 $pararef = $lref unless(length($pararef));
16 }
17 }
18 return; # Did not got a defined line? End of input file.
19 }
20 }
On line 6 and 7, we encounter "shiftline()" and "unshiftline()". These help you to read and unread the head of internal input data stream of master document into the line string and its reference. Here, the reference is provided by a string "$filename:$linenum". Please remember Perl only has one dimensional array data structure. So codes handling the internal input data stream line are a bit cryptic.
6 行目で、2 度目の <p> に遭遇します。それは次の段落のシグナルです。そこで、得られた行をオリジナルドキュメントに戻し (7 行目)、これまでに生成された段落を出力に押し出します。9 行目でそれの先頭の <p> を削除した後、このタグと段落の残りの翻訳を連結して押し出します。
translate() 関数はとてもクールです。引数を出力 PO ファイルに渡して (抽出)、入力 PO ファイルで見つかった翻訳を返します (翻訳)。pushline() の引数の一部で使用するため、この翻訳が出力ドキュメントに定着します。
Isn't that cool? It is possible to build a complete po4a module in less than 20 lines when the format is simple enough…
Locale::Po4a::TransTractor(3pm) で、これについてもっと知ることができます。
ここでの考え方は、オリジナルドキュメントとその翻訳を取り、翻訳から抽出した N 番目の文字列は、オリジナルから抽出した N 番目の文字列の翻訳であるということです。動作するには、双方のファイルの構造がまったく同じでなければなりません。例えば、ファイルが以下の構造を持つ場合、残念ながら翻訳の 4 番目の文字列 (型が「章」) は、オリジナルの 4 番目の文字列 (型が「段落」) の翻訳だということはまずあり得ません。
オリジナル 翻訳
章 章
段落 段落
段落 段落
段落 章
章 段落
段落 段落
そのため、ファイルを抽出する際、オリジナルファイルからの場合も翻訳ファイルからの場合も po4a のパーサを使い、二つ目から抽出した文字列を一つ目から抽出した文字列の翻訳として第三の PO ファイルを構成します。出力した文字列が実際にそれぞれの翻訳となっているかをチェックするために、po4a のドキュメントパーサは、ドキュメントから抽出した文字列の構文タイプ情報を出力すべきです (既存のものはすべてそうしますし、あなたのものもそうするべきです)。さらにその情報を、双方のドキュメントが同じ構文であるかどうかを確認するのに使用します。先の例では、4 番目の文字列は片方では段落ですが、もう一方では章見出しであることを検出し、問題を報告できます。
理論上、問題を検出した後でファイルを (ちょうど diff がするように) 再同期することは可能です。しかし、非同期の前にある、再同期するべき文字列は明確ではなく、何度もまずい結果に終わるでしょう。以上が、何かまずい場合、現在の実装では再同期を行わず、失敗について詳しく出力する理由です。問題の修正にはファイルの手修正が必要です。
これだけ用心していても、この部分は非常に間違いやすいです。そのため、このように推測された翻訳すべてを fuzzy とマークし、翻訳者によりレビューと確認を行うようにしています。
さて、これはかなり簡単です。すべての追加内容が適用されるまで、翻訳済みドキュメントは、直接ディスクに書かれていませんが、メモリに保管されています。ここに関わるアルゴリズムはかなり率直です。position 正規表現にマッチする行を探し、mode=before の場合はその前に追加内容を挿入します。そうでなければ、boundary にマッチする次の行を探し、それが endboundary の場合はその行の後に、beginboundary の場合はその行の前に追加内容を挿入します。
This chapter groups the Frequently Asked Questions. In fact, most of the questions for now could be formulated that way: "Why is it designed this way, and not that one?" If you think po4a isn't the right answer to documentation translation, you should consider reading this section. If it does not answer your question, please contact us on the <devel@lists.po4a.org> mailing list. We love feedback.
はい、po4a は段落ごとに区切って翻訳しています (実際、その決定は各モジュールで行っていますが、既存のモジュールは全てそうなっています。また、自作モジュールでも通常はそのようにすべきでしょう)。この方法には二つの主な利点があります:
以上の利点をもってしても、段落ごとに区切って翻訳するというアイディアが気に入らない人はいます。彼らが恐れていることに対して、以下のように、いくつか回答を用意しています:
プロ仕様の翻訳ツールは、ドキュメントを文レベルで分割し、以前の翻訳を最大限再利用し、作業のスピードアップを図るものがあります。これは、同じ文が文脈によっては異なる翻訳になる場合に問題になります。
段落は、その定義上、文よりも長いです。これにより、二つのドキュメントの同じ段落は、それぞれの文脈に関係なく、同じ意味 (と翻訳) になることが、おそらく保証できるでしょう。
文よりも小さい単位で分割するのは、非常にまずいでしょう。なぜまずいのかは、ここで説明するには少々長いので、興味のある方は、例えば Locale::Maketext::TPJ13(3pm) の man ページ (Perl のドキュメントに同梱) を参照してください。短くするにしろ、各言語は特定の構文規則を持ち、既存の全言語で (話者の多い 10 言語のうち 5 言語やそれ以下でも) 機能するように文の一部を集めて文を組み立てる方法はありません。
一見したところ、gettext はすべての種類の翻訳に適合できるようには見えません。例えば、debconf (すべての Debian パッケージが使用する、インストール時の対話インターフェース) には適合できるようには見えませんでした。この場合、翻訳するテキストはかなり短く (パッケージごとに 1 ダース)、パッケージのインストール前に使用可能でなければならないため、特殊なファイルに翻訳を翻訳を置くことは困難でした。
これが debconf の開発者が翻訳を元と同じファイルに配置する別のソリューションの実装を決めた理由です。これはかなり魅力的です。例えば、XML のためにこうしたいと思う人さえいます。次のようになります:
<section> <title lang="en">My title</title> <title lang="fr">Mon titre</title> <para> <text lang="en">My text.</text> <text lang="fr">Mon texte.</text> </para> </section>
しかしこれには問題があるため、現在は PO ベースのアプローチを採用しています。ファイルではオリジナルしか編集できず、翻訳はマスターテンプレートから抽出した PO ファイルに置かなければなりません (そしてパッケージコンパイル時に配置します)。この古いシステムは以下のいくつかの理由で非推奨です:
複数の翻訳者が同時にパッチを提供した場合、それらをマージするのは大変です。
翻訳を適用する必要のある、オリジナルからの変更をどのように検出したらよいでしょう? diff を使用するには、どの版を元にして翻訳を行ったか記しておかねばなりません。言い換えると、あなたのファイルには PO ファイルが必要です ;)
この解は、ヨーロッパの言語だけが関わる場合には有効ですが、韓国語、ロシア語、アラビア語 (訳注: もちろん日本語も) の導入は、本当に構図を複雑にします。UTF は解になり得ますが、まだ問題があります。
さらに、この問題を検出するのが難しいのです (言い換えると、「ロシア語の翻訳者のせいで」韓国語のエンコードが壊れていることを検出するのは、韓国人の読者のみです)。
gettext はこの問題をすべて解決します。
そうですね。しかし現在のところ他にもっといい方法がないのです。唯一の代替手段が手動翻訳であり、それには保守の問題があります。
知る限りでは、以下の二つしかありません:
これは XML のみ、さらに特定の DTD のみを扱えます。リストが一つの大きな msgid になってしまうため、私はリストの扱いにかなり不満があります。リストが大きくなると、ひとかたまりの構造をつかみにくくなります。
以上に対する po4a の主な利点は、簡単に内容を追加できること (欠点かもしれませんが) と、gettext 化が簡単なことです。
ドキュメントやプログラムの翻訳を行う際、3 つの問題に行き当たります。言語について (皆が二つの言語で話せるわけではありません)、技術について (po4a が存在する理由です)、人との連携についてです。すべての開発者が、翻訳の必要性について理解しているわけではありません。立派な意志があったとしても、翻訳者が作業しやすいやり方を無視する可能性もあります。これを補助するのに、po4a は参照可能なたくさんのドキュメントを用意しています。
その他の重要な点として、このファイルが何で、どのように使用するのか、を示す短いコメントで、各翻訳済みファイルが始まるということがあります。これは、話すのも困難な言語の洪水におぼれている哀れな開発者を助け、ファイルを正しく扱う助けとなるはずです。
In the po4a project, translated documents are not source files anymore, in the sense that these files are not the preferred form of the work for making modifications to it. Since this is rather unconventional, that's a source of easy mistakes. That's why all files present this header:
| ***************************************************** | * GENERATED FILE, DO NOT EDIT * | * THIS IS NO SOURCE FILE, BUT RESULT OF COMPILATION * | ***************************************************** | | This file was generated by po4a-translate(1). Do not store it (in VCS, | for example), but store the PO file used as source file by po4a-translate. | | In fact, consider this as a binary, and the PO file as a regular source file: | If the PO gets lost, keeping this translation up-to-date will be harder ;)
同様に、gettext の通常の PO ファイルは、po/ ディレクトリにコピーされる必要があるだけです。しかし、これは po4a によって操作されたものに当てはまりません。ここには、開発者が、ドキュメントの翻訳が存在する場合に、プログラム側の翻訳を削除してしまうという、大きな危険があります (双方を同じ PO ファイルに納めることはできません。これは、ドキュメントはコンパイル時にのみ翻訳が必要であるのに対して、プログラムは翻訳を mo ファイルとしてインストールしなければならないからです)。以上が、po-debiandoc モジュールが以下のヘッダをつけて PO ファイルを提供する理由です:
# # ADVISES TO DEVELOPERS: # - you do not need to manually edit POT or PO files. # - this file contains the translation of your debconf templates. # Do not replace the translation of your program with this !! # (or your translators will get very upset) # # ADVISES TO TRANSLATORS: # If you are not familiar with the PO format, gettext documentation # is worth reading, especially sections dedicated to this format. # For example, run: # info -n '(gettext)PO Files' # info -n '(gettext)Header Entry' # # Some information specific to po-debconf are available at # /usr/share/doc/po-debconf/README-trans # or http://www.debian.org/intl/l10n/po-debconf/README-trans #
- https://docs.kde.org/stable5/en/kdesdk/lokalize/project-view.html
- http://www.debian.org/intl/l10n/
しかし、すべて問題ないわけではありません。このアプローチには対処するべき欠点もあります。
One of my dreams would be to integrate somehow po4a to Gtranslator or Lokalize. When a documentation file is opened, the strings are automatically extracted, and a translated file + po file can be written to disk. If we manage to do an MS Word (TM) module (or at least RTF) professional translators may even use it.
Denis Barbier <barbier,linuxfr.org> Martin Quinson (mquinson#debian.org)
倉澤 望 <nabetaro@debian.or.jp> Debian JP Documentation ML <debian-doc@debian.or.jp>
| 2018-12-09 | Po4a Tools |