# 国际化指南

## 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 项目的国际化支持和实现方法。通过本指南，您可以了解如何确保系统在不同语言环境下正常运行。