翻訳の作法

Perlのドキュメントを翻訳する上での留意事項を書いています。翻訳したい方は、一度目を通していただけると良いかと思います。
特にプロジェクトに特化した内容ではありませんが、Japanized Perl Resources Project(通称JPRP)をベースにしています。また、Pod::L10N 対応フォーマット仕様も参考にしています。

ディレクトリ構成

コアドキュメント

docs/perl/バージョン/ファイル名.pod

モジュール

docs/modules/モジュール名-バージョン/

以下に、モジュールの tar.gz を展開し、各.pm を .pod に変更します。

その他

pod / html / md いずれでも構いません。以下のように配置してください。
docs/articles/perl/名前.pod
docs/articles/ドメイン/パス/ファイル名.html
docs/articles/ドメイン/パス/ファイル名.md

具体的には、以下のようになります。

/docs/articles/perl/perlunicook.pod
/docs/articles/perl.com/pub/2012/06/perlunicook-further-resources.html

podの抽出方法

% perldoc -u Test::More
% perldoc -u Test/More.pm

のようにすることで、pod を抽出することができます。

文字コード

やむをえない事情がない限りは 文字コードはutf-8にしてください。
pod ファイルの先頭で、以下のように、encoding を指定します。

=encoding utf8

翻訳文の行数

英語の文章の順番と日本語の文章の順番は違いますが、行数はある程度合わせた方が良いです。
英語が数行にわたって書かれている場合、日本語訳も数行に分けて書いたほうが良いです。

Similar to C<%+>, this variable allows access to the named capture buffers
in the last successful match in the currently active dynamic scope. To
each capture buffer name found in the regular expression, it associates a
reference to an array containing the list of values captured by all
buffers with that name (should there be several of them), in the order
where they appear.

原文が上記のようであれば、(行数が違いますが)以下のように複数行で書きます。

C<%+> と同様、この変数は現在アクティブな動的スコープで最後に成功した
マッチングの名前付き捕捉バッファへのアクセスを可能にします。
正規表現中に捕捉バッファ名が現れるごとに、その名前のバッファ全てで
(複数あるでしょう)捕捉されている値のリストを出現順で含む配列への
リファレンスと関連付けられます。

翻訳文をバージョンアップした際に、diff を見てチェックする場合などがありますが、その際に一行にまとめていると diff が見辛くなります。

原文の残し方

ファイル内に原文を残す場合は、
=begin original 原文... =end original

のように、=begin original 〜 =end original で囲みます。

HTMLの場合は、原文がかこまれているタグのクラス名を original としてください。

<h1 class="original">Title</h1>
<h1>タイトル</h1>
<div class="original"> 原文 </div>
<div> 翻訳文 </div>

ただし、=head を訳す場合は、=head の次に( )で翻訳文を入れてください。
※ =head NAME は、そのままにしてください。

=head Version Ranges

(バージョンの範囲)

コード部分の翻訳

コード部分は訳さずそのまま残しておいた方が良いです。
下記の赤色の部分はコード部分ですが、これらは、originalには含みません。
※ただし、コード部分のコメントを翻訳し、原文を残したい場合は、originalブロックに含めても構いません(が、コメント部分くらいであれば、オリジナルを残さなくても良いかと思います)。
=head1 SYNOPSIS
=begin original The following is example of usage of Hoge. Example1: =end original
Hogeの使い方の例です。 例1:
$hoge = Hoge->new; $hoge->foo;
=begin original Example2: =end original
例2:
$result = $hoge->bar print $result->to_string;
=head1 DESCRIPTION

=headの翻訳

NAME, SYNOPSYS, DESCRIPTION などですが、代表的なものは、perldoc.jpでは、自動的に翻訳されて表示されます。
翻訳される場合原文をそのままにして、下に()で書いてください。
perldoc.jp では、表示時に()部分を=headの英文と置き換えています。 ※ただし、=head1 NAMEはPODのパーサーに取って重要なものとなりますので、こちらのみ訳さずにそのままにして、()も書かないでください。

=head1 NAME

=begin original

GreatModule - great module

=end original

GreatModule - 偉大なモジュール

=head1 STRUCTURE

(構造)

=head2 OPTIONAL FIELDS

(オプションのフィールド)

=head

以下の代表的なものは、perldoc.jpでは日本語に置換されて表示されます。

NAME名前
SYNOPSIS概要
DESCRIPTION説明
OPTIONSオプション
METDODSメソッド
FUNCTIONS関数
EXAMPLE
AUTDOR作者
COPYRIGHT & LICENSEコピーライト & ライセンス
BUGSバグ
CAUTION警告
ACKNOWLEDGEMENTS謝辞
SUPPORTサポート

L<...>の翻訳

L</STRUCTURE> のような POD内リンクについては、perldoc.jp では英語のままでも、英語を翻訳しても、いずれでも正しい場所へリンクされます。
ただし、L<CPAN::Meta::Spec/optional_features> のような同じ文書内に含まれないリンクに関しては翻訳されると正しい場所にリンクできなくなります。
※他のPOD表示ツールで日本語に翻訳されたリンクが正しく動くかはわかりません(たぶん、動きません)。

=itemの翻訳

=item を =begin original 〜 =end original で囲むと、PODのパースに失敗する場合があります。以下のように回避できます。

(a) =item の下に ()で訳文を入れる

=head1と同様に、()で訳文を入れる方法です。

=over 8

=item test

(テスト)
=begin original original sentence. =end original
翻訳文章

(b) =item を訳文にして、その下に原文を書く

もしくは、原文→訳文の順番が逆になりますが、=item を訳文にして、その下に、=begin original 〜 =end original で原文を( )で囲んでも良いかも知れません。 ただし、モジュールがアップデートされた時のことを考えるとあまりいい方法ではありません。

=over 8

=item テスト

=begin original

(test)

=end original

=begin original original sentence. =end original
翻訳文章

(c) =over 〜 =back までをすべて =begin original 〜 =end original で囲ってしまう

=over 〜 =back までの量が少ないのであれば、 =begin original 〜 =end original で全体を囲ってしまっても良いでしょう。

=begin original =over 8 =item test original sentence. =item test2 original sentence. =back =end original
=over 8 =item テスト 翻訳文章 =item テスト2 翻訳文章 =back

HTML形式の翻訳についての特別な処理

perldoc.jpでは、HTML形式の翻訳の場合、以下の処理を行っています。

タイトル/概要の抜き出し

タイトルは、titleタグから、タイトルタグがない場合は、最初のh1タグから取得します。
概要は、meta タグで description が指定されてあれば、そちらを使用します。

JavaScript, stlye、class の削除

JavaScript, style, classは削除されます。以下の class については、残されます。

  • original ... 原文用のブロックに使います。このclassのついたブロックは非表示になります
  • prettyprint ... コード部分のブロックで使うとコードがハイライトされるようになります

特殊なコメント <!-- linkto: http://... -->

原著者のポリシーなどで、perldoc.jp 上にホスト出来ず、原著者のサイトでホストしたいといった要望がある場合に、使ってください。
翻訳文を表示する代わりに、指定のURLへリダイレクトします。

Markdown形式の翻訳についての特別な処理

perldoc.jpでは、Markdown形式の翻訳の場合、以下の処理を行っています。

タイトル/概要の抜き出し

タイトルは、最初の見出しから、概要は「翻訳」という文字のある最初の見出しがあれば、それに続く文章を概要とします。 または、「○○の翻訳」という見出しが最初にあれば、「○○」の部分をタイトルとして、それに続く文章を概要とします。 「翻訳」という文字が含まれる見出しがない場合は、最初の見出しに続く文章を概要とします。 もし、最初の見出しに「翻訳」という文字が含まれていた場合は、タイトルはその次の見出しのものを取得します。

オリジナルの文章の残し方

以下のようにコメントで囲むことで残せますが、フォーマッタがうまく処理できない場合があります。

<!-- original
original sentence
-->

連絡先の記述

連絡先を書く場合は、翻訳文の最後に以下のように付記すると良いでしょう(特に決まりはありません)。

=head1 翻訳について

翻訳者:名前 (account@example.com)

翻訳リポジトリの場所や、翻訳プロジェクトの名前やURL、誤訳の報告先などを書き足しても良いかと思います。

決まっていないこと

以下の点は、特に決まっていませんが、各項目、前者の方が多いと思います。

  • 句読点の形式 ...「、。」 or 「,.」
  • 英語と日本語の間のスペース ... 「ある word の翻訳」or 「あるwordの翻訳」
  • 口語体 or 文語体 ... 「です、ます」 or 「である」

翻訳することについての著者への報告

ほとんどのモジュールが改変と再配布が許可されているライセンスなので、元々のドキュメントの著者に翻訳の報告をする必要はありません。
ライセンスが不明な場合や、改変と再配布が許可されていないライセンスの場合には、著者に連絡を取ってください。
以下のような文章で聞くと良いかと思います。

Dear ***

I'm *** ***.
I read your document about *** at http://***.
I want to introduce it to other Japanese Perl programmers.
Now I'm translating it into Japanese.

Can I distribute the translated document
under the same terms as Perl itself?

翻訳したことの報告

JPRPの場合、RFCメールをMLに送るという方法を取っています。
JPRP、gitリポジトリで翻訳された場合は、当サイトのRSSフィードで配信されます。

JPRPの参考文書

JPRPに関する個別の決め事などは、以下を参照してください。