2.2. doc-jp 翻訳作業の注意点とルール

この節では、doc-jp の翻訳作業の細かなルールについて説明しています。 文章は多少、分量がありますが、 文体のルールなどはきちんと守らなければなりません。 ひととおり頭に入れておいてください。

2.2.1. 翻訳する前にやるべきこと

2.2.1.1. それは本当に翻訳すべき文書?

まず、翻訳対象の文書が既に翻訳されていないかをチェックしてください。 例えば、doc-jp,man-jp ML のアーカイブ、各種サーチエンジンで WWW 上のリソースを調べるのも有効でしょう。 すでにあるなら、それを使うに越したことはない(はず)です。

次に、本当に自分の翻訳したいものかどうか、revision number などからチェックします。最新でなかったり、obsolete な文書を翻訳するのはあまり意味がありません。

2.2.1.2. 翻訳作業を始める前に、doc-jp ML へ報告する

同じ文書を複数の人が翻訳してしまうような事態を避けるために、 「…を訳します〜」と、一言、doc-jp ML に投げておきましょう。 翻訳に長期間かかる場合は特に必要なことです。

2.2.2. 文体のルール

FreeBSD doc-jp の基本的なルールは、次のように決められています。 文体統一のために必要ですので、かならずチェックするようにしてください。

2.2.3. 翻訳文書の扱いと注意点

2.2.3.1. FreeBSD 配布物に含まれる文書

2.2.3.1.1. ファイル名

日本語版の文書は英語版と異なるディレクトリに 格納されるため、ファイル名は英語版と同じにします。

2.2.3.1.2. signature をつける

翻訳する文書が SGML 文書の場合には、 FreeBSD Japanese Documentation Project の signature と、 原文書の RCS revision を次のように追加してください。

<!-- $Id$ -->

具体的には、上の文字列を、下のように書き換えます。

<!-- The FreeBSD Japanese Documentation Project -->
<!-- Original revision: x.xx -->
<!-- $Id$ -->
Note

$Id:...$ は $FreeBSD:...$ に変更されました。 RCS のキーワードは、$FreeBSD$ 以外展開されません。

Important

日本語版文書は、原文書とは独立した RCS revision で管理されますので、 Original revision には、元の RCS revision 番号を保存 します。

2.2.3.1.3. www の画像ファイル

http://www.FreeBSD.org/ の HTML 文書については、 画像ファイルを英語版と共用しているため、 ファイルパス指定を英語版から書き換える必要があります。

<IMG SRC="gifs/hoge.jpg">

具体的には、上のような指定を、下のように変更します。

<IMG SRC="../gifs/hoge.jpg">

これは、ディレクトリ構成が次のようになっているからです。

/      英語版ドキュメント
/gifs  英語版画像ファイル
/ja    日本語版ドキュメント

日本語版ドキュメントは、英語版ドキュメントのディレクトリの下にある gifs を指していなければなりませんので、相対指定で一つ上のディレクトリを 起点とします。

Note

このディレクトリ構造については、 [doc-jp 6806] を参照してください。

2.2.4. 翻訳するときの注意

翻訳作業はひたすら頑張りましょう。 わからないところは無駄に時間をかけて悩むより、 訳せる部分だけ訳して、査読の時に質問する方が良いと思います。

原文の typo は気づきにくいので、訳す前に ispell などのスペルチェッカを使って英文をチェックするのも一つの手です。 スペルミスした単語を見てもわかる人は類推できるのでしょうが、 佐藤はそのために意味がわからなかった文がいくつかあった経験から こういう方法を使うことにしています。

例えば、QWERTY 配列の押し間違えが原因でおこる or -> of のような typo は、 場合によって文法的におかしくない誤文ができてしまう場合があります。 これは訳していても typo だと気づきにくいので、 おかしいと思ったら疑ってみることも必要です。

原文書に明らかな誤りを発見したら、doc-jp ML へ報告する、 原文書の筆者に連絡をとるなど、可能な手段で確認をとった後、 必要ならば doc カテゴリで send-pr[3]してください。 もちろん、日本語訳は訂正したものに合わせます。 もし、誤りであるかどうかはっきりしなければ、 該当部分に訳注を追加しておくと良いでしょう。

訳として不安なところは、何らかのマークを付けておきましょう。 本文が長ければ長いほど、査読の負担も大きくなります。 こういったマークがあれば、 査読者もそこに注意を配ることができます。

2.2.5. 翻訳が終了したら

必ず文書の形式的正当性をチェックします。 具体的には、SGML(LinuxDoc, DocBook, HTML) DTD の文法に則しているかどうか、 というところが大事です。 これは、目で確認することも可能ですが、 以下の項で述べているようなツールを使うことで validation できます。 通常、翻訳時にその形式用のツールが必要になることはほとんどありません。

日本語文章の文字コード、形式もチェック対象です。 Mule などを使っていると漢字コードに問題をしばしば忘れがちですが、 作業中はともかく、成果物は必ず漢字コードをチェックしてください。 これを怠ると、漢字コードをまたがる差分 (例えば EUC-JP -> JIS) を生成してしまったりする可能性があります。 漢字コードのチェック、変換は、後述する coconkf を使うと簡単にできます。

細かな部分は 公式作業ガイドにまとまっています。ツールで機械的に置換すると弊害がありますので、 ツールは検出だけにとどめておいた方が良いでしょう。

2.2.6. 提出

翻訳の査読をお願いするため、成果物は基本的に doc-jp ML へ投げます。 新規翻訳であれば全文、既翻訳文書の更新であれば、 diff(1) を使って差分の形で提出します。

差分の形式は unified diff 形式[4]にします。 unified diff 形式の利点は、変更点がわかりやすい、 サイズが小さいなどがあり、チェック時に有利です。 全文を送付するとチェックする人の負担を増やしてしまいますので、 新規翻訳でないなら必ず差分を使うようにしてください。

Note

diff-c, -u の比較に関する議論は、[doc-jp 6100, 6257, 6258, 6267, 6273] を参照してください。

実際に doc-jp ML に提出する時は、プレインテキストとして、 もしくは MIME マルチパート(添付ファイル)として、 という二種類の方法があります。

プレインテキストとして本文に含める場合は、 本文ではなく email の規則に則ってください。 サイズが大きければ gzip + uuencode を使うとベターです。

複数のファイルをプレインテキストとして提出すると混乱しますので、 その場合は一文書・一メイルとする方が良いと思います。 また、subject, もしくは本文に必ず次の要素を明記してください。

2.2.7. 査読と修正のプロセス

査読してもらったら、反映して initial version からの差分をつくり、 doc-jp ML へフィードバックします。 誰の、どの文書に対する意見を反映したのか、 また、どれからの diff なのかをわかりやすく書いてください。

何度も改訂すると、diff がたくさんできてしまいますが、 パッチを当てた文書に対する diff をつくると、 最終的な文書を得るために何度もパッチを当てなければならず、 作業が繁雑になります。diff 元の文書はなるべく固定しておいて、 diff は毎回、それから生成した方が良いでしょう。

2.2.8. 翻訳文書のメインテナンス

自分で翻訳した文書は、なるべく自分が保守するようにしましょう。

Notes

[1]

本来、文字符号化規則(CES)と文字集合は 別の概念なので、これは正確な表現ではありません。

[2]

UNIX 系の OS に多い形式です。 DOS/Windows 系は CR+LF, MacOS は CR を採用しているため、変換が必要になる場合があります。

[3]

send-pr とは、FreeBSD 開発者のコミュニティに対して 問題点や提案(PR; Problem Report)を送ることを指します。 FreeBSD の標準コマンド send-pr(1) や、email, web ベースのインターフェイスなど、 さまざまな方法で報告することが可能です。

[4]

diff(1) コマンドの生成する差分には、 いくつか種類があります。 GNU fileutils の diff(1) で unified diff 形式を出力するには、 -u オプションを付加する必要があります。 詳しくは、マニュアルページを参照してください。

Solaris の diff では unified diff の出力ができないようなのですが、 やりかたを知っている方がいらっしゃったら教えてください。