makemd/serverjava/docs/08_Internationalization_Guide.md

国际化指南

1. 国际化概述

Crawlful Hub 项目支持国际化，确保系统可以在不同语言环境下正常运行。本文档详细介绍了项目的国际化支持和实现方法。

2. 国际化配置

2.1 资源文件

Crawlful Hub 项目使用 Spring 国际化支持，通过资源文件管理不同语言的文本。

资源文件位置：

• src/main/resources/i18n/messages.properties - 英文资源文件
• src/main/resources/i18n/messages_zh.properties - 中文资源文件

资源文件示例：

messages.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：

# 认证
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 类配置国际化支持。

配置示例：

@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 项目在控制器中使用国际化消息。

示例代码：

@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 项目在服务中使用国际化消息。

示例代码：

@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 项目在异常处理中使用国际化消息。

示例代码：

@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 类，支持新的语言

示例：

@Bean
public LocaleResolver localeResolver() {
    CookieLocaleResolver localeResolver = new CookieLocaleResolver();
    localeResolver.setDefaultLocale(Locale.ENGLISH);
    return localeResolver;
}

6.2 动态消息

Crawlful Hub 项目支持动态消息，通过参数传递动态值。

示例：

资源文件：

user.welcome=Welcome, {0}!

使用示例：

String welcomeMessage = messageSource.getMessage("user.welcome", new Object[]{username}, locale);

7. 总结

本国际化指南详细介绍了 Crawlful Hub 项目的国际化支持和实现方法。通过本指南，您可以了解如何确保系统在不同语言环境下正常运行。