docs: Update embeddable documentation for nested and optional embeddables

- Add documentation for nested embeddable classes with examples
- Update field type lists to include embeddable classes in Optional types
- Update Japanese translations for new embeddable features
- Improve clarity of optional embeddable behavior documentation

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>

Author: nakamura-to

docs/embeddable.md

@@ -81,7 +81,8 @@ The field type must be one of the following:
 
 - [Basic classes](basic.md)
 - [Domain classes](domain.md)
-- java.util.Optional, whose element is either [Basic classes](basic.md) or [Domain classes](domain.md)
+- [Embeddable classes](embeddable.md) (nested embeddables)
+- java.util.Optional, whose element is either [Basic classes](basic.md), [Domain classes](domain.md), or [Embeddable classes](embeddable.md)
 - java.util.OptionalInt
 - java.util.OptionalLong
 - java.util.OptionalDouble
@@ -105,7 +106,56 @@ final String zip;
 
 ### Transient
 
-If an embeddable has fields that you don’t want to persist, you can annotate them using `@Transient`:
+If an embeddable has fields that you don't want to persist, you can annotate them using `@Transient`:
+
+### Nested embeddable classes
+
+Embeddable classes can contain other embeddable classes as fields, allowing for nested composition:
+
+```java
+@Embeddable
+public class Address {
+    String street;
+    String city;
+    String zipCode;
+}
+
+@Embeddable
+public class ContactInfo {
+    String email;
+    String phone;
+    Address address; // Nested embeddable
+}
+
+@Entity
+public class Customer {
+    @Id
+    Integer id;
+    String name;
+    ContactInfo contactInfo; // Contains nested Address
+}
+```
+
+This creates a hierarchical structure where the `Customer` entity contains `ContactInfo`, which in turn contains `Address`. 
+All fields from nested embeddables are flattened into the entity's table structure.
+
+### Optional embeddable classes
+
+Embeddable classes can be wrapped in `java.util.Optional` to indicate that the entire embeddable group may be null:
+
+```java
+@Entity
+public class Employee {
+    @Id
+    Integer id;
+    String name;
+    Optional<Address> homeAddress;    // Optional embeddable
+    Optional<ContactInfo> emergencyContact; // Optional nested embeddable
+}
+```
+
+When an Optional embeddable is null, all corresponding database columns will be null. 
+Conversely, when all columns corresponding to an Optional embeddable are null in the database, the Optional field will be empty (Optional.empty()). 
 
 ## Method definition
 

docs/entity.md

@@ -141,7 +141,7 @@ The field type must be one of the following:
 - [Basic classes](basic.md)
 - [Domain classes](domain.md)
 - [Embeddable classes](embeddable.md)
-- java.util.Optional, whose element is either [Basic classes](basic.md) or [Domain classes](domain.md)
+- java.util.Optional, whose element is either [Basic classes](basic.md), [Domain classes](domain.md), or [Embeddable classes](embeddable.md)
 - java.util.OptionalInt
 - java.util.OptionalLong
 - java.util.OptionalDouble

docs/locale/ja/LC_MESSAGES/embeddable.po

@@ -3,7 +3,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version:  doma-docs\n"
 "Report-Msgid-Bugs-To: \n"
-"POT-Creation-Date: 2025-07-12 16:05+0900\n"
+"POT-Creation-Date: 2025-07-26 00:57+0900\n"
 "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
 "Last-Translator: \n"
 "Language: ja_JP\n"
@@ -77,56 +77,102 @@ msgid "[Domain classes](domain.md)"
 msgstr "[ドメインクラス](domain.md)"
 
 #: ../../embeddable.md:84
-msgid ""
-"java.util.Optional, whose element is either [Basic classes](basic.md) or "
-"[Domain classes](domain.md)"
-msgstr "要素を [基本クラス](basic.md) または [ドメインクラス](domain.md) のいずれかとする java.util.Optional"
+msgid "[Embeddable classes](embeddable.md) (nested embeddables)"
+msgstr "[埋め込み可能クラス](embeddable.md) (ネストした埋め込み可能クラス)"
 
 #: ../../embeddable.md:85
-msgid "java.util.OptionalInt"
+msgid ""
+"java.util.Optional, whose element is either [Basic classes](basic.md), "
+"[Domain classes](domain.md), or [Embeddable classes](embeddable.md)"
 msgstr ""
+"要素を [基本クラス](basic.md)、[ドメインクラス](domain.md)、または [埋め込み可能クラス](embeddable.md)"
+" のいずれかとする java.util.Optional"
 
 #: ../../embeddable.md:86
-msgid "java.util.OptionalLong"
-msgstr ""
+msgid "java.util.OptionalInt"
+msgstr "java.util.OptionalInt"
 
 #: ../../embeddable.md:87
+msgid "java.util.OptionalLong"
+msgstr "java.util.OptionalLong"
+
+#: ../../embeddable.md:88
 msgid "java.util.OptionalDouble"
-msgstr ""
+msgstr "java.util.OptionalDouble"
 
-#: ../../embeddable.md:97
+#: ../../embeddable.md:98
 msgid "Column"
 msgstr "カラム"
 
-#: ../../embeddable.md:99
+#: ../../embeddable.md:100
 msgid ""
 "You can specify the corresponding column name with the `@Column` "
 "annotation:"
 msgstr "カラム名を `@Column`  アノテーションで指定できます。"
 
-#: ../../embeddable.md:106
+#: ../../embeddable.md:107
 msgid "Transient"
 msgstr "Transient"
 
-#: ../../embeddable.md:108
+#: ../../embeddable.md:109
 msgid ""
-"If an embeddable has fields that you don’t want to persist, you can "
+"If an embeddable has fields that you don't want to persist, you can "
 "annotate them using `@Transient`:"
-msgstr "埋め込み可能オブジェクトに永続化したくないフィールドがある場合は、 `@Transient` アノテーションを指定できます。"
+msgstr "埋め込み可能クラスに永続化したくないフィールドがある場合は、`@Transient` アノテーションを指定できます："
+
+#: ../../embeddable.md:111
+msgid "Nested embeddable classes"
+msgstr "ネストした埋め込み可能クラス"
+
+#: ../../embeddable.md:113
+msgid ""
+"Embeddable classes can contain other embeddable classes as fields, "
+"allowing for nested composition:"
+msgstr "埋め込み可能クラスは他の埋め込み可能クラスをフィールドとして含むことができ、ネストした構成が可能です："
+
+#: ../../embeddable.md:139
+msgid ""
+"This creates a hierarchical structure where the `Customer` entity "
+"contains `ContactInfo`, which in turn contains `Address`.  All fields "
+"from nested embeddables are flattened into the entity's table structure."
+msgstr ""
+"これにより、`Customer` エンティティが `ContactInfo` を含み、さらに `ContactInfo` が `Address` "
+"を含む階層構造が作成されます。ネストした埋め込み可能クラスのすべてのフィールドは、エンティティのテーブル構造にフラット化されます。"
+
+#: ../../embeddable.md:142
+msgid "Optional embeddable classes"
+msgstr "Optionalな埋め込み可能クラス"
 
-#: ../../embeddable.md:110
+#: ../../embeddable.md:144
+msgid ""
+"Embeddable classes can be wrapped in `java.util.Optional` to indicate "
+"that the entire embeddable group may be null:"
+msgstr ""
+"埋め込み可能クラスを `java.util.Optional` でラップして、埋め込み可能グループ全体が null "
+"になる可能性があることを示すことができます："
+
+#: ../../embeddable.md:157
+msgid ""
+"When an Optional embeddable is null, all corresponding database columns "
+"will be null.  Conversely, when all columns corresponding to an Optional "
+"embeddable are null in the database, the Optional field will be empty "
+"(Optional.empty())."
+msgstr ""
+"Optionalな埋め込み可能クラスがnullの場合、対応するすべてのデータベースカラムがnullになります。逆に、Optionalな埋め込み可能クラスに対応するすべてのカラムがデータベースでnullの場合、Optionalフィールドは空（Optional.empty()）になります。"
+
+#: ../../embeddable.md:160
 msgid "Method definition"
 msgstr "メソッドの定義"
 
-#: ../../embeddable.md:112
+#: ../../embeddable.md:162
 msgid "There are no limitations in the use of methods."
 msgstr "メソッドの使用に制限はありません。"
 
-#: ../../embeddable.md:114
+#: ../../embeddable.md:164
 msgid "Using @Embedded annotation"
 msgstr "@Embeddedアノテーションの使用"
 
-#: ../../embeddable.md:116
+#: ../../embeddable.md:166
 msgid ""
 "You can use the `@Embedded` annotation to embed the same embeddable type "
 "multiple times within a single entity with different column name "
@@ -135,99 +181,99 @@ msgstr ""
 "`@Embedded` "
 "アノテーションを使用すると、同じ埋め込み可能型を異なるカラム名プレフィックスで単一のエンティティ内に複数回埋め込むことができます。"
 
-#: ../../embeddable.md:118
+#: ../../embeddable.md:168
 msgid "Basic usage"
 msgstr "基本的な使用方法"
 
-#: ../../embeddable.md:137
+#: ../../embeddable.md:187
 msgid "This will generate the following columns in the SQL statements:"
 msgstr "これにより、SQL文で以下のカラムが生成されます："
 
-#: ../../embeddable.md:139
+#: ../../embeddable.md:189
 msgid "`billing_street`"
 msgstr "`billing_street`"
 
-#: ../../embeddable.md:140
+#: ../../embeddable.md:190
 msgid "`billing_city`"
 msgstr "`billing_city`"
 
-#: ../../embeddable.md:141
+#: ../../embeddable.md:191
 msgid "`billing_zip_code`"
 msgstr "`billing_zip_code`"
 
-#: ../../embeddable.md:142
+#: ../../embeddable.md:192
 msgid "`shipping_street`"
 msgstr "`shipping_street`"
 
-#: ../../embeddable.md:143
+#: ../../embeddable.md:193
 msgid "`shipping_city`"
 msgstr "`shipping_city`"
 
-#: ../../embeddable.md:144
+#: ../../embeddable.md:194
 msgid "`shipping_zip_code`"
 msgstr "`shipping_zip_code`"
 
-#: ../../embeddable.md:146
+#: ../../embeddable.md:196
 msgid "Prefix behavior"
 msgstr "プレフィックスの動作"
 
-#: ../../embeddable.md:148
+#: ../../embeddable.md:198
 msgid "The `prefix` attribute controls how column names are generated:"
 msgstr "`prefix` 属性はカラム名の生成方法を制御します："
 
-#: ../../embeddable.md:150
+#: ../../embeddable.md:200
 msgid ""
 "Column names are generated by combining the prefix with the embeddable "
 "field column name"
 msgstr "カラム名は、プレフィックスと埋め込み可能フィールドのカラム名を組み合わせて生成されます"
 
-#: ../../embeddable.md:151
+#: ../../embeddable.md:201
 msgid "The prefix is added as-is to the field column name"
 msgstr "プレフィックスはフィールドのカラム名にそのまま追加されます"
 
-#: ../../embeddable.md:152
+#: ../../embeddable.md:202
 msgid ""
 "If no prefix is specified, the behavior remains the same as using the "
 "embeddable field column name directly"
 msgstr "プレフィックスが指定されていない場合、動作は埋め込み可能フィールドのカラム名を直接使用する場合と同じままです"
 
-#: ../../embeddable.md:169
+#: ../../embeddable.md:219
 msgid "Column overrides"
 msgstr "カラムのオーバーライド"
 
-#: ../../embeddable.md:171
+#: ../../embeddable.md:221
 msgid ""
 "You can use the `columnOverrides` attribute along with `@ColumnOverride` "
 "annotations to have fine-grained control over individual column mappings:"
 msgstr ""
 "`columnOverrides` 属性を `@ColumnOverride` "
 "アノテーションと共に使用することで、個々のカラムマッピングをきめ細かく制御できます："
 
-#: ../../embeddable.md:193
+#: ../../embeddable.md:243
 msgid "The `@ColumnOverride` annotation allows you to:"
 msgstr "`@ColumnOverride` アノテーションを使用すると、以下のことができます："
 
-#: ../../embeddable.md:195
+#: ../../embeddable.md:245
 msgid "Specify a custom column name for a specific embeddable field"
 msgstr "特定の埋め込み可能フィールドにカスタムカラム名を指定する"
 
-#: ../../embeddable.md:196
+#: ../../embeddable.md:246
 msgid "Override column attributes such as `insertable`, `updatable`, and `quote`"
 msgstr "`insertable`、`updatable`、`quote` などのカラム属性をオーバーライドする"
 
-#: ../../embeddable.md:197
+#: ../../embeddable.md:247
 msgid "Take precedence over any `prefix` attribute when both are specified"
 msgstr "両方が指定されている場合、`prefix` 属性よりも優先される"
 
-#: ../../embeddable.md:200
+#: ../../embeddable.md:250
 msgid ""
 "When both `prefix` and `columnOverrides` are used, the `@ColumnOverride` "
 "settings take precedence for the specified fields."
 msgstr ""
 "`prefix` と `columnOverrides` の両方が使用されている場合、指定されたフィールドに対しては "
 "`@ColumnOverride` の設定が優先されます。"
 
-#: ../../embeddable.md:203
+#: ../../embeddable.md:253
 msgid "Example"
 msgstr "例"
 
@@ -243,3 +289,9 @@ msgstr "例"
 #~ msgid "{doc}`domain`"
 #~ msgstr ""
 
+#~ msgid ""
+#~ "When an Optional embeddable is null, "
+#~ "all corresponding database columns will "
+#~ "be null."
+#~ msgstr "Optional な埋め込み可能クラスが null の場合、対応するすべてのデータベースカラムが null になります。"
+

docs/locale/ja/LC_MESSAGES/entity.po

@@ -3,7 +3,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version:  doma-docs\n"
 "Report-Msgid-Bugs-To: \n"
-"POT-Creation-Date: 2025-07-12 16:05+0900\n"
+"POT-Creation-Date: 2025-07-25 22:20+0900\n"
 "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
 "Last-Translator: \n"
 "Language: ja_JP\n"
@@ -181,9 +181,9 @@ msgstr "[埋め込み可能クラス](embeddable.md)"
 
 #: ../../entity.md:144
 msgid ""
-"java.util.Optional, whose element is either [Basic classes](basic.md) or "
-"[Domain classes](domain.md)"
-msgstr "[基本クラス](basic.md)または [ドメインクラス](domain.md) のいずれかを要素とする java.util.Optional"
+"java.util.Optional, whose element is either [Basic classes](basic.md), "
+"[Domain classes](domain.md), or [Embeddable classes](embeddable.md)"
+msgstr "要素を [基本クラス](basic.md)、[ドメインクラス](domain.md)、または [埋め込み可能クラス](embeddable.md) のいずれかとする java.util.Optional"
 
 #: ../../entity.md:145
 msgid "java.util.OptionalInt"