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