The Ja-Jakarta Project Jakarta Commons

翻訳の手引き 〜Commonsドキュメントローカル ルール〜 (案)
2004年02月09日 Strutsのローカルルールをもとに作成

ここでは、Commonsドキュメントを翻訳する際の固有のルールを示します(基本的にStritsの翻訳ルールと同様です)。 なお、ここに示した以外のルールについては、「翻訳スタイルガイド」及び「翻訳作業の手引き」に準じます。

共通事項

翻訳の手順

  • 基本的な作業の流れは「翻訳作業の手引き」に準じます。
  • 翻訳を開始する前に、翻訳分担表[マニュアル用,JavaDoc用]を見て、対象ドキュメントの翻訳が未着手であることを確認してください。
  • 翻訳を行うドキュメントは、Commonsディストリビューションからではなく、翻訳分担表からダウンロードしてください。
  • 翻訳の際は、直接HTMLドキュメントを訳すのではなく、提供されるXMLドキュメントまたはJavaソースを対象に作業してください。
  • 対象ドキュメントの以前のバージョンが翻訳されている場合には、うまく流用するように心がけてください。

訳語について

その他

  • 以前の翻訳を流用して翻訳を行う場合は、もとの文章の翻訳者の名前と今回の翻訳者の名前を併記してください。
    - 例:
    @transrator 日置 聡(もと文章の翻訳者)
    @transrator 芦沢 嘉典(今回の翻訳者)

    記述の順序は、翻訳作業者の判断に任せます。

Javadocの翻訳手順

  1. JavaDocコマンドおよびツールにて処理する関係上 Shift-JISで統一します。改行は DOSタイプ(CR+LF) を推奨します。
  2. まず、翻訳情報の追加を行います。
    • 翻訳の開始時にはタイプコメント中に翻訳者名を@translatorタグを使って、追加してください。
    • 校正の開始時にはタイプコメント中に校正者名を@editorタグを使って、追加してください。
    • タイプコメント中に翻訳状況を@statusタグを使って、追加してください。
      翻訳状況に関しては進捗の状況にあわせて以下から選択してください。
      @status unstarting訳者募集中
      @status underwork翻訳中
      @status firstdraft初稿
      @status underproof校正者校正中
      @status authordraft訳者校正中
      @status admindraft管理者校中
      @status completion校了
      @status interruption中断
      @status outside見送り
    • 翻訳の更新日を@updateタグを使って、追加してください。

  3. package.html、-overview のhtnl にも基本的には同じ方法で翻訳情報を追加しますが、ドキュメントの最初にこの記述を持ってくると上手くタグの終わりを検出できないようなので、ドキュメントの終わり(</html>の直前)に記述する事で統一します。
  4. コメントの原文をある程度まとまったブロック(<p>タグ、<pre>タグ等)ごとに{@primary }を使って囲ってください。
    <pre> が出てきた場合には注意が必要です。特にソースファイルが記述されていた場合などの'}'がタグレットの動作に影響してしまいます。 {@primary }で囲む中身に <pre> と '}' がある場合には '}' を } に変換してあげてください。
  5. {@primary }で囲った原文の前に訳文を追加してください。
  6. コンストラクタ、メソッドのコメント内の引数、返り値、例外のコメントも同様の方法で訳文を追加しますが、 引数の変数名、例外のクラス名は{@primary }の中に含める必要はありません。
  7. 翻訳が終了したら、javadocコマンド等を使って翻訳結果から正しくJavaDocが生成できることを確認してください。
  8. 確認が完了したら、翻訳されたソースコードをメーリングリストに投稿してください。

Javaソースの翻訳例
package org.apache.commons.fileupload;

import java.io.ByteArrayOutputStream;
import java.io.File;
import java.io.FileOutputStream;
import java.io.IOException;
import java.io.OutputStream;

/**
 * <p>指定された閾値に達するまではデータをメモリ上に保持し、
 * 閾値に達した場合にはディスク上に出力する出力ストリームです。
 * もし閾値に達することなくクローズされた場合には、データはディスクに全く書き込まれません。 ・・・・・・5
 * {@primary An output stream which will retain data in memory until a specified
 * threshold is reached, and only then commit it to disk. If the stream is
 * closed before the threshold is reached, the data will not be written to
 * disk at all.}         ・・・・・・・・・・・・・・・・・・・・・・・・・・4
 * </p>  *
 * @author <a href="mailto:martinc@apache.org">Martin Cooper</a>
 * @translator 蛇華流汰 故紋図
 * @proofreader
 * @status firstdraft
 * @update 2003/07/12 ・・・・・・・・・・・・・・・・・・・・・・・・・・2
 *
 * @version $Id: commonsTrans.xml,v 1.1 2004/03/09 12:33:21 hioki Exp $
 */
public class DeferredFileOutputStream
    extends ThresholdingOutputStream
{

    // ----------------------------------------------------------- Data members


    /**
     * 閾値に達するまでデータが書き込まれる出力ストリーム。 ・・・・・・・・・・・・・・・・・・・・5
     * {@primary The output stream to which data will be written prior to the theshold
     * being reached.} ・・・・・・・・・・・・・・・・・・・・・・・・・・4
     */
    private ByteArrayOutputStream memoryOutputStream;

  ・
  ・

    // ----------------------------------------------------------- Constructors


    /**
     * イベントのトリガーとなる閾値の値と、それを超えた場合にデータをセーブするファイルを指定して
     * クラスのインスタンスを生成します。 ・・・・・・・・・・・・・・・・・・・・・・・・・・5
     * {@primary Constructs an instance of this class which will trigger an event at the
     * specified threshold, and save data to a file beyond that point.} ・・・・・・・・・・・・・・・・・・4
     *
     * @param threshold イベントのトリガーとなるバイトの値。
     * {@primary The number of bytes at which to trigger an event.}
     * @param outputFile 閾値を超えた場合にデータを保存するファイル。
     * {@primary The file to which data is saved beyond the threshold.} ・・・・・・・・・・・・・・・6
     */
    public DeferredFileOutputStream(int threshold, File outputFile)
    {
        super(threshold);
        this.outputFile = outputFile;

        memoryOutputStream = new ByteArrayOutputStream(threshold);
        currentOutputStream = memoryOutputStream;
    }


    // --------------------------------------- ThresholdingOutputStream methods


    /**
     * 現在使われている出力ストリーム。
     * これは閾値との状態によってメモリが対象のものかディスクが対象のものになります。 ・・・・・・5
     * {@primary Returns the current output stream. This may be memory based or disk
     * based, depending on the current state with respect to the threshold.} ・・・・・・・・・・・・・・・4
     *
     * @return 現在使われている出力ストリーム。
     * {@primary The underlying output stream.}
     *
     * @exception IOException エラーが発生した場合。
     * {@primary if an error occurs.} ・・・・・・・・・・・・・・・・・・・・・・・・6
     */
    protected OutputStream getStream() throws IOException
    {
        return currentOutputStream;
    }

  ・
  ・

package.htmlの翻訳例
  ・
  ・
<pre>

    public void doPost(HttpServletRequest req, HttpServletResponse res)
    {
        DiskFileUpload fu = new DiskFileUpload();
        // 超えた場合に FileUploadException が投げられる(データの)最大サイズ
        fu.setSizeMax(1000000);
        // メモリに保持できる(データの)最大サイズ
        fu.setSizeThreshold(4096);
        // getSizeThreshold() の値より大きなデータを保存する場所
        fu.setRepositoryPath("/tmp");

        List fileItems = fu.parseRequest(req);
        // 2つのファイルが(アップロードされてされて)くると仮定します。
        // 1つ目のファイルは小さなテキストファイルです。
        // 2つ目のファイルの詳細は不明で、サーバ上のファイルに書き出されます。
        Iterator i = fileItems.iterator();
        String comment = ((FileItem)i.next()).getString();
        FileItem fi = (FileItem)i.next();
        //クライアントでのファイル名
        String fileName = fi.getName();
        // コメントとファイル名をデータベースに保存
        ...
        // ファイルに書き込み
        fi.write("/www/uploads/" + fileName);
    }
  ・・・・・・・・・・・・・・・・・・・・・・・・・・・・・・・・・・・・・5
</pre>
{@primary
<pre>
    public void doPost(HttpServletRequest req, HttpServletResponse res)
    {
        DiskFileUpload fu = new DiskFileUpload();
        // maximum size before a FileUploadException will be thrown
        fu.setSizeMax(1000000);
        // maximum size that will be stored in memory
        fu.setSizeThreshold(4096);
        // the location for saving data that is larger than getSizeThreshold()
        fu.setRepositoryPath("/tmp");

        List fileItems = fu.parseRequest(req);
        // assume we know there are two files. The first file is a small
        // text file, the second is unknown and is written to a file on
        // the server
        Iterator i = fileItems.iterator();
        String comment = ((FileItem)i.next()).getString();
        FileItem fi = (FileItem)i.next();
        // filename on the client
        String fileName = fi.getName();
        // save comment and filename to database
        ...
        // write the file
        fi.write("/www/uploads/" + fileName);
    &#125;
</pre>
}
  ・・・・・・・・・・・・・・・・・・・・・・・・・・・・・・・・・・・・・4
      <p>
         上記の例では最初のファイルは <code>String</code> でメモリ上に展開されます。
         getString メソッドがコールされた後、データはメモリまたはディスクをそのサイズ分だけ占有します。
         メモリに保持するにはサイズが明らかに大きすぎると仮定される2番目のファイルは、
         もし4096バイト以下であれば メモリに保持された後に(指定された)最終位置に書き出されます。
         最終位置に書き出す際に、もしデータが閾値(threshold)より大きい場合には、
         一時ファイルを指定された場所に移動する事を試みます。
         それができなかった場合には、新たな位置に書き出しを行います。
・・・・・・・・・・・・・・・・・・・・・・・・・・5

         {@primary In the example above the first file is loaded into memory as a
         <code>String</code>. Before calling the getString method, the data
         may have been in memory or on disk depending on its size.  The second
         file we assume it will be large and therefore never explicitly load
         it into memory, though if it is less than 4096 bytes it will be
         in memory before it is written to its final location.  When writing to
         the final location, if the data is larger than the
         threshold, an attempt is made to rename the temporary file to
         the given location.  If it cannot be renamed, it is streamed to the
         new location.}
  ・・・・・・・・・・・・・・・・・・・・・・・・・・4

      @translator 素取 楽徒
      @status firstdraft
      @update 2003/07/10
・・・・・・・・・・・・・・・・・・・・・・・・・・3
   </body>
</html>

オプション

翻訳の際の情報を出力するために以下のインラインタグをJavadocコメント内およびpackage.html内にて使用することができます。
これらのタグの利用は必須ではありませんが、翻訳作業の効率化、翻訳されたドキュメントの価値の向上のためにも積極的に活用ください。
  • {@annotation } インラインタグ(訳注)
    このタグは翻訳を行っている際に原文の内容に対して(日本語にしてしまうと原文のニュアンスが伝わらない等で)注釈または補足説明を行いたい場合に使用することが出来ます。
    このタグ内に記述された内容は、Javadocを生成する際に以下のように変換されます。

    変換前(java){@annotation 訳注です}
    変換後(Javadoc)<div style="color:#666666; font-size:smaller;">[訳注: 訳注です]</div>

    この内容は校了後の原文を削除したドキュメントにも残されます。

  • {@note } インラインタグ(訳者コメント)
    このタグは翻訳を行っている際に英文の解釈または記述内容に不明点があった場合に使用することができます。 翻訳時の問題などを記述しておき、校正者に対してコメントを残す(逆もあると思います)ことで翻訳作業を効率化することが出来ます。
    このタグ内に記述された内容は、Javadocを生成する際に以下のように変換されます。

  • 変換前(xml)<note>コメントです</note>
    変換後(Javadoc)<div style="color:#666666; font-size:smaller;">[訳者コメント: コメントです]</div>


    この内容は校了後の原文を削除したドキュメントには残りません。

Copyright © 1999-2004, The Ja-Jakarta Project