add en doc

Author: astral-data

docs/en/annotation/alisa-annotation.md

@@ -1,139 +1,139 @@
-## 名称映射
+## Name Mapping
 
-### 基础使用
+### Basic Usage
 
 ```php
 use Astral\Serialize\Attributes\InputName;
 use Astral\Serialize\Attributes\OutputName;
 use Astral\Serialize\Serialize;
 
 class User extends Serialize {
-    // 输入时使用不同的属性名
+    // Use a different property name for input
     #[InputName('user_name')]
     public string $name;
 
-    // 输出时使用不同的属性名
+    // Use a different property name for output
     #[OutputName('user_id')]
     public int $id;
 
-    // 同时支持输入和输出不同名称
+    // Support different names for both input and output
     #[InputName('register_time')]
     #[OutputName('registeredAt')]
     public DateTime $createdAt;
 }
 
-// 使用不同名称的输入数据
+// Input data with different names
 $user = User::from([
-    'user_name' => '张三',       // 映射到 $name
-    'id' => 123,                // 保持不变
-    'register_time' => '2023-01-01 10:00:00'  // 映射到 $createdAt
+    'user_name' => 'Job',       // Mapped to $name
+    'id' => 123,                // Remains unchanged
+    'register_time' => '2023-01-01 10:00:00'  // Mapped to $createdAt
 ]);
 
-// 输出数据
+// Output data
 $userArray = $user->toArray();
-// $userArray 的内容:
+// $userArray toArray:
 // [
-//     'name' => '张三',
+//     'name' => 'Job',
 //     'user_id' => 123,
 //     'registeredAt' => '2023-01-01 10:00:00'
 // ]
 ```
 
-### 多输入/输出名称处理
+### Handling Multiple Input/Output Names
 
 ```php
 use Astral\Serialize\Attributes\InputName;
 use Astral\Serialize\Attributes\OutputName;
 use Astral\Serialize\Serialize;
 
 class MultiOutputUser extends Serialize {
-    // 多个输出名称
+    // output multiple names
     #[OutputName('user_id')]
     #[OutputName('id')]
     #[OutputName('userId')]
     public int $id;
 
-    // 多个输出名称 按照声明顺序取地一个匹配的name
+    // Multiple input names, the first matching name in declaration order will be used
     #[InputName('user_name')]
     #[InputName('other_name')]
     #[InputName('userName')]
     public int $name;
 
 }
 
-// 场景1：使用第一个匹配的输入名称
+// Scenario 1: Use the first matching input name
 $user1 = MultiInputUser::from([
-    'user_name' => '张三'  // 使用 'user_name'
+    'user_name' => 'Job'  // Use 'user_name'
 ]);
-echo $user1->name;  // 输出 '张三'
+echo $user1->name;  // Output 'Job'
 
-// 场景2：使用第二个匹配的输入名称
+// Scenario 2: Use the second matching input name
 $user2 = MultiInputUser::from([
-    'other_name' => '李四'  // 使用 'other_name'
+    'other_name' => 'Tom'  // Use 'Tom'
 ]);
-echo $user2->name;  // 输出 '李四'
+echo $user2->name;  // Output 'Tom'
 
-// 场景3：使用最后的输入名称
+// Scenario 3: Use the last input name
 $user3 = MultiInputUser::from([
-    'userName' => '王五'  // 使用 'userName'
+    'userName' => 'Lin'  // Use 'userName'
 ]);
-echo $user3->name;  // 输出 '王五'
+echo $user3->name;  // Output 'Lin'
 
-// 场景4：传入多个的时候 按照声明顺序取地一个匹配的name
+// Scenario 4: When multiple are passed, the first matching name in declaration order is used
 $user4 = MultiInputUser::from([
-    'userName' => '王五',
-    'other_name' => '李四',
-    'user_name' => '张三',
+    'userName' => 'Job',
+    'other_name' => 'Tom',
+    'user_name' => 'Lin',
 ]);
-echo $user4->name;  // 输出 '张三'
+echo $user4->name;  // Output 'Job'
 
-// 创建用户对象
+// Create user object
 $user = MultiOutputUser::from([
     'id' => 123,
-    'name' => '张三'
+    'name' => 'Job'
 ]);
 
-// 转换为数组
-// tips: 因为id 有多个outputname 所以输出了 ['user_id','id','userId']
+// Convert to array
+// tips: Since id has multiple output names, the output includes ['user_id','id','userId']
 $userArray = $user->toArray();
-// $userArray 的内容:
+// $userArray toArray:
 // [
 //     'user_id' => 123,
 //     'id' => 123,
 //     'userId' => 123,
 // ]
 ```
 
-### 复杂映射场景
+### Complex Mapping Scenarios
 
 ```php
 use Astral\Serialize\Serialize;
 
 class ComplexUser extends Serialize {
-    // 嵌套对象的名称映射
+    // Name mapping for nested objects
     #[InputName('user_profile')]
     public UserProfile $profile;
 
-    // 数组元素的名称映射
+    // Name mapping for array elements
     #[InputName('user_tags')]
     public array $tags;
 }
 
-// 处理复杂的输入结构
+// Handle complex input structure
 $complexUser = ComplexUser::from([
     'user_profile' => [
-        'nickname' => '小明',
+        'nickname' => 'job',
         'age' => 25
     ],
     'user_tags' => ['developer', 'programmer']
 ]);
 
-// 转换为标准数组
+// Convert to standard array
 $complexUserArray = $complexUser->toArray();
-// $complexUserArray 的内容:
+// $complexUserArray toArray:
 // [
 //     'profile' => UserProfile Object ([
-//         'nickname' => '小明',
+//         'nickname' => 'job',
 //         'age' => 25
 //     ]),
 //     'tags' => ['developer', 'programmer']

docs/en/annotation/customer-annotation.md

@@ -1,17 +1,17 @@
-### 自定义注解类实现
+### Custom Annotation Class Implementation
 
-你可以通过自定义注解类，灵活地扩展序列化库的输入输出处理逻辑。
+You can flexibly extend the input/output handling logic of the serialization library by defining custom annotation classes.
 
 ---
 
-#### 入参处理注解类
+#### Input Processing Annotation Class
 
-实现 `InputValueCastInterface` 接口，重写其中的 `match` 和 `resolve` 方法，来自定义输入数据的转换和处理。
+Implement the `InputValueCastInterface` interface, and override its `match` and `resolve` methods to customize the conversion and handling of input data.
 
-- **`match`**：用于判断是否对当前值进行处理，返回 `true` 表示进入 `resolve`。
-- **`resolve`**：对匹配的输入值进行转换，并返回转换后的结果。
+- **`match`**: Used to determine whether to process the current value; returning `true` means `resolve` will be called.
+- **`resolve`**: Converts the matched input value and returns the result.
 
-示例：给输入值添加自定义前缀的注解类
+Example: Annotation class that adds a custom prefix to the input value
 
 ```php
 use Astral\Serialize\Contracts\Attribute\InputValueCastInterface;
@@ -27,23 +27,23 @@ class CustomerInput implements InputValueCastInterface
 
     public function match(mixed $value, DataCollection $collection, InputValueContext $context): bool
     {
-        // 对所有输入值都生效
+        // Applies to all input values
         return true;
     }
 
     public function resolve(mixed $value, DataCollection $collection, InputValueContext $context): mixed
     {
-        // 给输入值添加前缀
+        // Add prefix to input value
         return $this->prefix . $value;
     }
 }
-````
+```
 
-### 输出处理注解类
+### Output Processing Annotation Class
 
-输出处理注解与输入处理注解类似，只是实现的接口不同——需要实现 `OutputValueCastInterface`，用以对序列化输出的值进行自定义转换。
+The output processing annotation is similar to the input processing annotation, but implements a different interface—`OutputValueCastInterface`, which is used to customize the conversion of serialized output values.
 
-示例：给序列化输出的值添加自定义后缀的注解类
+Example: Annotation class that adds a custom suffix to the serialized output value
 
 ```php
 use Astral\Serialize\Contracts\Attribute\OutputValueCastInterface;
@@ -59,13 +59,13 @@ class CustomerOutput implements OutputValueCastInterface
 
     public function match(mixed $value, DataCollection $collection, OutputValueContext $context): bool
     {
-        // 对所有输出值都生效
+        // Applies to all output values
         return true;
     }
 
     public function resolve(mixed $value, DataCollection $collection, OutputValueContext $context): mixed
     {
-        // 给输出值添加后缀
+        // Add suffix to output value
         return $value . $this->suffix;
     }
 }

docs/en/annotation/date-annotation.md

@@ -1,16 +1,16 @@
-## 时间转换
+## Date/Time Conversion
 
-1. 格式灵活性
-   支持多种输入和输出时间格式
-   可以轻松处理不同地区的日期表示
-2. 时区处理
-   支持在不同时区间转换
-   自动处理时间的时区偏移
-3. 类型安全
-   自动将字符串转换为 DateTime 对象
-   保证类型的一致性和正确性
+1. Flexible Formatting
+   Supports multiple input and output date/time formats
+   Easily handles date representations from different regions
+2. Timezone Handling
+   Supports conversion between different timezones
+   Automatically handles timezone offsets for times
+3. Type Safety
+   Automatically converts strings to DateTime objects
+   Ensures type consistency and correctness
 
-### 基础使用
+### Basic Usage
 
 ```php
 use Astral\Serialize\Attributes\Input\InputDateFormat;
@@ -27,37 +27,37 @@ class TimeExample extends Serialize {
     #[InputDateFormat('Y-m-d')]
     public string $dateDateString;
 
-    // 输出时间格式转换
+    // Output date format conversion
     #[OutputDateFormat('Y/m/d H:i')]
     public DateTime|string $processedAt;
 
 
-    // 支持多种时间格式
+    // Supports multiple date/time formats
     #[InputDateFormat('Y-m-d H:i:s')]
     #[OutputDateFormat('Y-m-d')]
     public string $createdAt;
 }
 
-// 创建订单对象
+// Create order object
 $order = TimeExample::from([
-    'dateTime' => new DateTime('2023-08-11'),           // 输入格式：Y-m-d
-    'dateDateString' => '2023-08-15',           // 输入格式：Y-m-d
-    'processedAt' => '2023-08-16 14:30',   // 输入默认格式 也支持DateTime对象
-    'createdAt' => '2023-08-16 14:45:30'   // 输入格式：Y-m-d H:i:s
+    'dateTime' => new DateTime('2023-08-11'),           // Input format: Y-m-d
+    'dateDateString' => '2023-08-15',           // Input format: Y-m-d
+    'processedAt' => '2023-08-16 14:30',   // Default input format, also supports DateTime objects
+    'createdAt' => '2023-08-16 14:45:30'   // Input format: Y-m-d H:i:s
 ]);
 
-// 转换为数组
+// Convert to array
 $orderArray = $order->toArray();
-// $orderArray 的内容:
+// Content of $orderArray:
 // [
 //     'dateTime' => '2023-08-11',
-//     ’dateDateString' => '2023-08-15',
+//     'dateDateString' => '2023-08-15',
 //     'processedAt' => '2023/08/16 14:30',
 //     'createdAt' => '2023-08-16'
 // ]
 ```
 
-### 带时区的时间转换
+### Time Conversion with Timezone
 
 ```php
 
@@ -66,27 +66,27 @@ use Astral\Serialize\Attributes\Output\OutputDateFormat;
 use Astral\Serialize\Serialize;
 
 class AdvancedTimeUser extends Serialize {
-    // 支持时区转换
+    // Supports timezone conversion
     #[InputDateFormat('Y-m-d H:i:s', timezone: 'UTC')]
     #[OutputDateFormat('Y-m-d H:i:s', timezone: 'Asia/Shanghai')]
     public DateTime $registeredAt;
 
-    // 支持不同地区的时间格式
-    #[InputDateFormat('d/m/Y')]  // 英国格式
-    #[OutputDateFormat('Y-m-d')]  // 标准格式
+    // Supports date formats from different regions
+    #[InputDateFormat('d/m/Y')]  // UK format
+    #[OutputDateFormat('Y-m-d')]  // Standard format
     public DateTime $birthDate;
 }
 
-// 使用高级时间转换
+// Use advanced time conversion
 $advancedUser = AdvancedTimeUser::from([
-    'registeredAt' => '2023-08-16 10:00:00',  // UTC 时间
-    'birthDate' => '15/08/1990'  // 英国日期格式
+    'registeredAt' => '2023-08-16 10:00:00',  // UTC time
+    'birthDate' => '15/08/1990'  // UK date format
 ]);
 
 $advancedUserArray = $advancedUser->toArray();
-// $advancedUserArray 的内容:
+// Content of $advancedUserArray:
 // [
-//     'registeredAt' => '2023-08-16 18:00:00',  // 转换为上海时区
+//     'registeredAt' => '2023-08-16 18:00:00',  // Converted to Shanghai timezone
 //     'birthDate' => '1990-08-15'
 // ]
 ```