first commit

2026-03-30 16:55:04 +08:00
commit 8d04a0fd6e
133 changed files with 11587 additions and 0 deletions
--- a/docs/08_Internationalization_Guide.md
+++ b/docs/08_Internationalization_Guide.md
@@ -0,0 +1,245 @@
+# 国际化指南
+
+## 1. 国际化概述
+
+Crawlful Hub 项目支持国际化，确保系统可以在不同语言环境下正常运行。本文档详细介绍了项目的国际化支持和实现方法。
+
+## 2. 国际化配置
+
+### 2.1 资源文件
+
+Crawlful Hub 项目使用 Spring 国际化支持，通过资源文件管理不同语言的文本。
+
+**资源文件位置**：
+- `src/main/resources/i18n/messages.properties` - 英文资源文件
+- `src/main/resources/i18n/messages_zh.properties` - 中文资源文件
+
+**资源文件示例**：
+
+**messages.properties**：
+```properties
+# Authentication
+auth.login.success=Login successful
+auth.login.failure=Invalid username or password
+auth.register.success=Registration successful
+auth.register.failure=Registration failed
+
+# Product
+product.create.success=Product created successfully
+product.create.failure=Failed to create product
+product.update.success=Product updated successfully
+product.update.failure=Failed to update product
+product.delete.success=Product deleted successfully
+product.delete.failure=Failed to delete product
+
+# Order
+order.create.success=Order created successfully
+order.create.failure=Failed to create order
+order.update.success=Order updated successfully
+order.update.failure=Failed to update order
+order.delete.success=Order deleted successfully
+order.delete.failure=Failed to delete order
+```
+
+**messages_zh.properties**：
+```properties
+# 认证
+auth.login.success=登录成功
+auth.login.failure=用户名或密码错误
+auth.register.success=注册成功
+auth.register.failure=注册失败
+
+# 商品
+product.create.success=商品创建成功
+product.create.failure=商品创建失败
+product.update.success=商品更新成功
+product.update.failure=商品更新失败
+product.delete.success=商品删除成功
+product.delete.failure=商品删除失败
+
+# 订单
+order.create.success=订单创建成功
+order.create.failure=订单创建失败
+order.update.success=订单更新成功
+order.update.failure=订单更新失败
+order.delete.success=订单删除成功
+order.delete.failure=订单删除失败
+```
+
+### 2.2 国际化配置类
+
+Crawlful Hub 项目通过 `InternationalizationConfig` 类配置国际化支持。
+
+**配置示例**：
+```java
+@Configuration
+public class InternationalizationConfig implements WebMvcConfigurer {
+    @Bean
+    public MessageSource messageSource() {
+        ResourceBundleMessageSource messageSource = new ResourceBundleMessageSource();
+        messageSource.setBasename("i18n/messages");
+        messageSource.setDefaultEncoding("UTF-8");
+        return messageSource;
+    }
+
+    @Bean
+    public LocaleResolver localeResolver() {
+        CookieLocaleResolver localeResolver = new CookieLocaleResolver();
+        localeResolver.setDefaultLocale(Locale.ENGLISH);
+        return localeResolver;
+    }
+
+    @Override
+    public void addInterceptors(InterceptorRegistry registry) {
+        LocaleChangeInterceptor interceptor = new LocaleChangeInterceptor();
+        interceptor.setParamName("lang");
+        registry.addInterceptor(interceptor);
+    }
+}
+```
+
+## 3. 国际化使用
+
+### 3.1 在控制器中使用
+
+Crawlful Hub 项目在控制器中使用国际化消息。
+
+**示例代码**：
+```java
+@RestController
+@RequestMapping("/api/v1/users")
+public class UserController {
+    @Autowired
+    private MessageSource messageSource;
+
+    @PostMapping("/register")
+    public ResponseEntity<String> register(@RequestBody User user, Locale locale) {
+        try {
+            userService.createUser(user);
+            return ResponseEntity.ok(messageSource.getMessage("auth.register.success", null, locale));
+        } catch (Exception e) {
+            return ResponseEntity.badRequest().body(messageSource.getMessage("auth.register.failure", null, locale));
+        }
+    }
+}
+```
+
+### 3.2 在服务中使用
+
+Crawlful Hub 项目在服务中使用国际化消息。
+
+**示例代码**：
+```java
+@Service
+public class ProductService {
+    @Autowired
+    private MessageSource messageSource;
+
+    public Product createProduct(Product product, Locale locale) {
+        try {
+            Product savedProduct = productRepository.save(product);
+            log.info(messageSource.getMessage("product.create.success", null, locale));
+            return savedProduct;
+        } catch (Exception e) {
+            log.error(messageSource.getMessage("product.create.failure", null, locale), e);
+            throw e;
+        }
+    }
+}
+```
+
+### 3.3 在异常处理中使用
+
+Crawlful Hub 项目在异常处理中使用国际化消息。
+
+**示例代码**：
+```java
+@RestControllerAdvice
+public class GlobalExceptionHandler {
+    @Autowired
+    private MessageSource messageSource;
+
+    @ExceptionHandler(Exception.class)
+    public ResponseEntity<ApiError> handleException(Exception e, Locale locale) {
+        ApiError error = new ApiError();
+        error.setCode("INTERNAL_ERROR");
+        error.setMessage(messageSource.getMessage("error.internal", null, locale));
+        error.setDetails(e.getMessage());
+        error.setTraceId(UUID.randomUUID().toString());
+        return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body(error);
+    }
+}
+```
+
+## 4. 语言切换
+
+Crawlful Hub 项目支持通过 URL 参数切换语言。
+
+**示例 URL**：
+- 英文：`http://localhost:3001/api/v1/users?lang=en`
+- 中文：`http://localhost:3001/api/v1/users?lang=zh`
+
+**实现细节**：
+- 使用 `LocaleChangeInterceptor` 拦截器处理语言切换
+- 通过 `lang` 参数指定语言
+- 支持的语言：`en`（英文）、`zh`（中文）
+
+## 5. 国际化最佳实践
+
+### 5.1 资源文件管理
+
+- **命名规范**：使用 `messages_{language}.properties` 命名资源文件
+- **组织方式**：按功能模块组织资源文件，如认证、商品、订单等
+- **编码格式**：使用 UTF-8 编码
+- **注释**：为资源文件添加适当的注释
+
+### 5.2 消息键命名
+
+- **命名规范**：使用 `module.action.result` 格式命名消息键
+- **一致性**：保持消息键的一致性，便于管理和维护
+- **可读性**：使用清晰、简洁的消息键，便于理解
+
+### 5.3 国际化测试
+
+- **测试不同语言**：测试系统在不同语言环境下的表现
+- **测试语言切换**：测试语言切换功能是否正常
+- **测试消息显示**：测试消息是否正确显示
+
+## 6. 扩展国际化支持
+
+### 6.1 添加新语言
+
+**步骤**：
+1. 在 `src/main/resources/i18n/` 目录下创建新的资源文件，如 `messages_fr.properties`（法语）
+2. 翻译资源文件中的消息
+3. 配置 `InternationalizationConfig` 类，支持新的语言
+
+**示例**：
+```java
+@Bean
+public LocaleResolver localeResolver() {
+    CookieLocaleResolver localeResolver = new CookieLocaleResolver();
+    localeResolver.setDefaultLocale(Locale.ENGLISH);
+    return localeResolver;
+}
+```
+
+### 6.2 动态消息
+
+Crawlful Hub 项目支持动态消息，通过参数传递动态值。
+
+**示例**：
+
+**资源文件**：
+```properties
+user.welcome=Welcome, {0}!
+```
+
+**使用示例**：
+```java
+String welcomeMessage = messageSource.getMessage("user.welcome", new Object[]{username}, locale);
+```
+
+## 7. 总结
+
+本国际化指南详细介绍了 Crawlful Hub 项目的国际化支持和实现方法。通过本指南，您可以了解如何确保系统在不同语言环境下正常运行。