Translate faq.rst

Author: nakamura-to

docs/build.rst

@@ -59,6 +59,8 @@ Build with IntelliJ IDEA
 
 See :ref:`idea-annotation-processor`.
 
+.. _build-with-gradle:
+
 Build with Gradle
 =================
 

docs/faq.rst

@@ -1,135 +1,128 @@
-==================
-FAQ
-==================
+==========================
+Frequently Asked Questions
+==========================
 
-.. contents:: 目次
+.. contents::
    :depth: 3
 
-一般的な質問
-============
+General Questions
+=================
 
-Domaとはどのような意味ですか？
+What does Doma stand for?
+-------------------------
+
+Doma stands for the **D** ao **O** riented database **MA** pping framework.
+
+What is annotation processing?
 ------------------------------
 
-**D** AO **O** riented Database **MA** pping Framework の略です。
+Annotation processing, that is introduced in Java 6,
+allows us to validate and generate source codes at compile time.
 
-注釈処理とはなんですか？
-------------------------
+We use annotation processing to do followings:
 
-Java 6 で導入された Pluggable Annotation Processing API を利用した処理で、
-コンパイル時のソースコード検証や、ソースコード生成が可能です。
+- Generating meta classes from the classes annotated with ``@Entity`` and ``@Domain``
+- Generating implementation classes of the interfaces annotated with ``@Dao``
+- Validating SQL statements
 
-Domaでは、注釈処理を使用して以下のことを実現しています。
+Runtime environment
+===================
 
-* エンティティクラスやドメインクラスのメタ情報の生成
-* Daoのインタフェースから実装クラスの生成
-* SQLファイルのバリデーション
+Which version of JRE does Doma support?
+---------------------------------------
 
-動作環境に関する質問
-====================
+JRE 8、9、10 and 11.
 
-どのバージョンのJREをサポートしていますか？
--------------------------------------------
+What libraries are required to work Doma?
+--------------------------------------
 
-JRE 8、9、10、11 をサポートしています。
+Nothing.
 
-Domaを動作させるのに必要なライブラリは何ですか？
-------------------------------------------------
+Doma has no dependencies to other libraries.
 
-何もありません。
-DomaはJRE以外のどんなライブラリにも依存していません。
+Development environment
+=======================
 
-開発環境に関する質問
-====================
+Which version of JDK does Doma support?
+---------------------------------------
 
-どのバージョンのJDKをサポートしていますか？
--------------------------------------------
+JDK 8、9、10 and 11.
 
-JDK 8、9、10、11 をサポートしています。
+Which IDE do you recommend?
+---------------------------
 
-推奨されたIDE（統合開発環境）はありますか？
--------------------------------------------
+We recommend Eclipse and IntelliJ IDEA.
 
-Eclipse と IntelliJ IDEA です。
+In Eclipse, the jar file of Doma is added to the Java Build Path but annotation processing doesn't run.
+-------------------------------------------------------------------------------------------------------
 
-DomaのjarをEclipseのビルドパスに設定しましたが注釈処理が実行されません。
-------------------------------------------------------------------------
+Enable annotation processing and add the jar file to the Factory Path too.
+See also :ref:`eclipse-build`.
 
-Factory PathにもDomaのjarファイルを登録してください。
+Where are generated source files in annotation processing?
+----------------------------------------------------------
 
-Factory Pathの設定画面は、プロジェクトのプロパティ設定画面から、
-Java - Compiler - Annotation Processing - Factory Path と辿れます。
-Annotation ProcessingとFactory Pathの画面では、
-「Enable project specific settings」のチェックボックスをチェックしてください。
+In Eclipse, they are found in the .apt_generated directory.
 
-注釈処理で生成されたコードはどこに出力されますか？
+In Eclipse, where is the .apt_generated directory?
 --------------------------------------------------
 
-Eclipseを利用している場合、
-デフォルトではプロジェクト直下の ``.apt_generated`` ディレクトリに出力されます。
+You can find it in the Nivigator view.
 
-Eclipseを使用していますが、.apt_generated ディレクトリがみつかりません。
-----------------------------------------------------------------------------------------
+I get the message that the sql file is not found, but it exists.
+----------------------------------------------------------------
 
-単にPackage Explorerビュー上に ``.apt_generated``
-ディレクトリが表示されていないだけかもしれません。
-``.apt_generated`` は、名称が ``.`` で始まっているために、
-Package Explorerビューで表示対象外になります。
-対応方法としては以下のいずれかを選択してください。
+You may get the following message, though the file exists:
 
-* Nivigatorビューから ``.apt_generated`` ディレクトリを確認する
-* Package Explorerビューのフィルタリングの設定を変更し ``.apt_generated`` ディレクトリを表示させる
-* 出力先ディレクトリを変更し名称が ``.`` で始まらないようにする
+.. code-block:: sh
 
-SQLファイルが見つかりません。
------------------------------
+  [DOMA4019] The file[META-INF/../select.sql] is not found from the classpath
 
-SQLファイルが存在するにも関わらず、次のエラーメッセージが出力されることがあります。
-::
+When you use Eclipse, check that the location of the output folder of resources is
+same as the one of class files in the Java Build Path dialog.
 
-  [DOMA4019] SQLファイル[META-INF/../select.sql]がクラスパスから見つかりませんでした
+When you use Gradle, check that the resource files are copied to ``compileJava.destinationDir``
+in advance of the compileJava task. See also :ref:`build-with-gradle`.
 
-SQLファイルはクラスの出力ディレクトリから検索されます。
-SQLファイルの出力ディレクトリとクラスの出力ディレクトリが同じであることを確認してください。
 
-Eclipseの場合、プロジェクトのプロパティの「Java Build Path」の設定画面で、
-ソースフォルダごとに出力先ディレクトリを変更可能になっています。
+Features as the database access library
+=======================================
 
-DBアクセスライブラリとしての機能に関する質問
-============================================
+Does Doma generate SQL statements?
+----------------------------------
 
-SQLを自動生成する機能はありますか？
------------------------------------
+Yes, Doma generates following statements:
 
-はい。
+- INSERT
+- DELETE
+- UPDATE
+- stored procedure call
+- stored function call
 
-更新系SQL、ストアドプロシージャー/ファンクション呼び出しについてはSQLを自動で生成できます。
-検索系のSQLについては、自動生成機能はありませんが、ファイルに外部化したSQLを実行し、
-その結果をJavaのオブジェクトにマッピングする機能があります。
+Doma doesn't generate SELECT statements
+but executes arbitrary SELECT statements and maps the results to the Java objects.
 
-詳しくは :doc:`query/index` を参照してください。
+See also :doc:`query/index` for detail information.
 
-条件が動的に変わるSQLはどのように実行できますか？
--------------------------------------------------
+How dynamic SQL statements are executed?
+----------------------------------------
 
-SQLファイルに、SQLコメントを使って条件を指定できます。
-SQLコメントは実行時に解析され、条件によって異なるSQLが生成されます。
+The dynamic SQL statements are built by directives that are represented as the SQL comments.
 
-詳しくは :doc:`sql` を参照してください。
+See also :doc:`sql` for detail information.
 
-1対1 や 1対n などデータベース上のリレーションシップをJavaオブジェクトにマッピングできますか？
----------------------------------------------------------------------------------------------
+Does Doma map database relationships such as one-to-one and one-to-many to Java objects?
+----------------------------------------------------------------------------------------
 
-いいえ、できません。
+No.
 
-Domaでは、SQLの結果セットの1行をそのまま1つのエンティティのインスタンスにマッピングします。
-このほうがシンプルでわかりやすいと考えているためです。
+Doma only maps each row of the SQL result set to a Java entity instance.
 
-コネクションプーリングの機能はありますか？
-------------------------------------------
+Does Doma provide a JDBC connection pooling feature?
+----------------------------------------------------
 
-いいえ、Domaでは提供していません。
+No.
 
-コネクションプーリング機能をもつアプリケーションサーバー、フレームワーク、
-ライブラリ等と組み合わせて使用してください。
+Use Doma together with
+the JDBC connection pool library such as `HikariCP <https://github.com/brettwooldridge/HikariCP>`_.