Translate lombok-support.rst

Author: nakamura-to

docs/lombok-support.rst

@@ -1,51 +1,43 @@
-==================
-Lombok サポート
-==================
+==============
+Lombok support
+==============
 
-.. contents:: 目次
+.. contents::
    :depth: 3
 
-Doma は `Lombok <https://projectlombok.org/>`_ のバージョン 1.16.12 以上をサポートしています。
+Doma supports `Lombok <https://projectlombok.org/>`_ 1.16.12 or above.
 
 .. note::
 
-  IDE として Eclipse を利用する場合はバージョン 4.5 以上を使ってください。
-  4.5 未満ではアノテーションプロッサで取得されるクラスに定義されたフィールドなどの並びがソースコードに記載されている順序と異なり、
-  正しく動作しないためです。
+  If you intend to use Eclipse, use version 4.5 or above.
 
-Lombok サポートの概要
-================================
+Overview
+========
 
-Lombok と Doma は共に JSR 269 で規定されたアノテーションプロセッサを提供していますが、
-Lombok と Doma を同時に利用する場合はアノテーションプロセッサの処理順序が問題になることがあります。
-例えば、 Lombok のアノテーションプロセッサがコンストラクタを生成し、
-Doma のアノテーションプロセッサがそのコンストラクタを読み取る場合などです。
-仮に、Doma のアノテーションプロセッサが先に実行されると単にコンストラクタが定義されていないものとして動作し、
-コンパイルに失敗します。
+Both Lombok and Doma provide their own annotation processors.
+Because the execution order of annotation processors is not determined in Java,
+the Doma's annotation processors are not always aware of the class modifications made by
+the Lombok annotation processors.
 
-アノテーションプロセッサの処理順序を指定できればこの問題は解決するのですが、
-残念ながら処理順序が保証されないことが仕様に記載されており、実際に問題解決の仕組みは提供されていません。
+To resolve the issue, the Doma's annotation processors recognise several Lombok's annotations
+and change their own behavior.
+For example, if the Doma's annotation processors find a class annotated with ``@lombok.Value``,
+they supposes that the class has a constructor whose arguments covers all instance fields.
 
-Doma では、この問題に対応するために、Lombok のアノテーションの有無を認識して処理順序に依存にしない振る舞いをするようにしています。
-先ほどの例で言えば、 ``@lombok.Value`` などコンストラクタを生成するLombokのアノテーションが存在する場合は
-実際にはコンストラクタを読み取らなくてもコンストラクタが存在するものとして動作するということです。
+Best practices
+==============
 
-Lombok 利用のベストプラクティス
-================================
+We show you recommended ways to define classes with Lombok annotations.
 
-Lombok のアノテーションを用いたクラスの定義について推奨する方法を記載します。
+Entity class definition
+-----------------------
 
-エンティティクラス
--------------------
+immutable entity classes
+~~~~~~~~~~~~~~~~~~~~~~~~
 
-immutable（イミュータブル）
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-イミュータブルなエンティティクラスを定義する場合は下記の点に注意します。
-
-* ``@Entity`` の ``immutable`` 要素に ``true`` を設定する
-* ``@lombok.Value`` もしくは ``@lombok.AllArgsConstructor`` を注釈する
-* ``@lombok.AllArgsConstructor`` を選んだ場合、getterを生成するためには ``@lombok.Getter`` を注釈する
+* Specify ``true`` to the ``immutable`` element of ``@Entity``
+* Specify either ``@lombok.Value`` or ``@lombok.AllArgsConstructor``
+* Specify ``@lombok.Getter`` to generate getters, in case of ``@lombok.AllArgsConstructor``
 
 .. code-block:: java
 
@@ -70,13 +62,11 @@ immutable（イミュータブル）
     private final Age age;
   }
 
-mutable（ミュータブル）
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-ミュータブルなエンティティクラスを定義する場合は下記の点に注意します。
+mutable entity classes
+~~~~~~~~~~~~~~~~~~~~~~
 
-* デフォルトコンストラクタを定義する（デフォルトコンストラクタの生成を抑制しない）
-* getter/setterを生成する場合は ``@lombok.Data`` もしくは ``@lombok.Getter`` / ``@lombok.Setter`` を注釈する
+* Define a default constructor
+* Specify ``@lombok.Data`` or ``@lombok.Getter``/``@lombok.Setter`` to generate getters/setters
 
 .. code-block:: java
 
@@ -101,13 +91,11 @@ mutable（ミュータブル）
     private Age age;
   }
 
-ドメインクラス
--------------------
+Domain class definition
+-----------------------
 
-ドメインクラスを定義する場合は下記の点に注意します。
-
-* ``@lombok.Value`` を注釈する
-* インスタンスフィールドは1つだけ定義し名前は ``value`` にする
+* Specify ``@lombok.Value``
+* Define only one instance field whose name is ``value``
 
 .. code-block:: java
 
@@ -117,13 +105,11 @@ mutable（ミュータブル）
     Integer value;
   }
 
-エンベッダブルクラス
-----------------------
-
-エンベッダブルクラスを定義する場合は下記の点に注意します。
+Embeddable class definition
+---------------------------
 
-* ``@lombok.Value`` もしくは ``@lombok.AllArgsConstructor`` を注釈する
-* ``@lombok.AllArgsConstructor`` を選んだ場合、getterを生成するためには ``@lombok.Getter`` を注釈する
+* Specify either ``@lombok.Value`` or ``@lombok.AllArgsConstructor``
+* Specify ``@lombok.Getter`` to generate getters, in case of ``@lombok.AllArgsConstructor``
 
 .. code-block:: java