wwjcloud-nest-v1/wwjcloud-nest-v1/docs/LANG-GUIDE.md

多语言（i18n）实现与对齐指南（Java-first)

本指南说明在 wwjcloud-nest-v1 中接入与落地国际化（i18n），并与 Java 项目的语言包与 key 规范保持一致（Java-first）。

背景与原则

• 单一标准：以 Java 的 .properties 和模块化规范为源头标准（source of truth）。
• 统一 key：点分层级命名，如 common.success、error.auth.invalid_token。
• 统一语言：后端统一 zh-CN、en-US，默认 zh-CN。
• 语言协商：优先级 ?lang= > Accept-Language > 默认。
• 兜底策略：未命中返回原始 key（与 Java 行为一致）。
• 历史兼容：仅为极少量老 key 建立别名映射（如 SUCCESS → common.success）。

目录结构（Nest 项目）

建议在本项目内遵循以下结构：

wwjcloud-nest-v1/
  apps/api/src/lang/
    zh-CN/
      common.json
      error.json
      user.json
    en-US/
      common.json
      error.json
      user.json
  libs/wwjcloud-boot/src/infra/lang/
    boot-i18n.module.ts
    resolvers.ts         # 可选：自定义解析器集合（Query/Header）
  apps/api/src/common/
    interceptors/response.interceptor.ts   # 使用 i18n 翻译成功提示
    filters/http-exception.filter.ts       # 使用 i18n 翻译错误提示
  apps/api/src/app.module.ts               # 导入 BootI18nModule

接入步骤

1) 安装依赖

使用你项目的包管理器安装：

pnpm add nestjs-i18n i18n accept-language-parser
# 或
npm i nestjs-i18n i18n accept-language-parser

2) 创建 i18n 模块（BootI18nModule）

文件：libs/wwjcloud-boot/src/infra/lang/boot-i18n.module.ts

import { Global, Module } from '@nestjs/common';
import { I18nModule, I18nJsonLoader, HeaderResolver, QueryResolver } from 'nestjs-i18n';
import { join } from 'path';

@Global()
@Module({
  imports: [
    I18nModule.forRoot({
      fallbackLanguage: 'zh-CN',
      loader: I18nJsonLoader,
      loaderOptions: {
        path: join(process.cwd(), 'apps/api/src/lang'),
        watch: process.env.NODE_ENV !== 'test',
      },
      resolvers: [
        { use: QueryResolver, options: ['lang'] },
        new HeaderResolver(), // 默认读取 'Accept-Language'
      ],
    }),
  ],
  exports: [I18nModule],
})
export class BootI18nModule {}

3) 在 AppModule 导入（推荐使用 BootLangModule 软别名）

文件：apps/api/src/app.module.ts

import { Module } from '@nestjs/common';
import { BootLangModule } from '@libs/wwjcloud-boot/src/infra/lang/boot-lang.module';

@Module({
  imports: [BootLangModule /* 以及其他模块 */],
})
export class AppModule {}

4) 响应拦截器使用 i18n

文件：apps/api/src/common/interceptors/response.interceptor.ts

import { CallHandler, ExecutionContext, Injectable, NestInterceptor } from '@nestjs/common';
import { I18nService } from 'nestjs-i18n';
import { Observable, map } from 'rxjs';

@Injectable()
export class ResponseInterceptor implements NestInterceptor {
  constructor(private readonly i18n: I18nService) {}

  intercept(ctx: ExecutionContext, next: CallHandler): Observable<any> {
    const req = ctx.switchToHttp().getRequest();
    return next.handle().pipe(
      map((original) => {
        const { code = 0, data = null, msg_key } = original ?? {};
        const key = msg_key || 'common.success';
        const msg = this.i18n.translate(key, {
          lang: req.i18nLang, // 来自解析器（Query/Header）
          defaultValue: key,
        });
        return { code, msg_key: key, msg, data };
      })
    );
  }
}

5) 异常过滤器使用 i18n

文件：apps/api/src/common/filters/http-exception.filter.ts

import { ArgumentsHost, Catch, ExceptionFilter, HttpException } from '@nestjs/common';
import { I18nService } from 'nestjs-i18n';

@Catch()
export class HttpExceptionFilter implements ExceptionFilter {
  constructor(private readonly i18n: I18nService) {}

  catch(exception: unknown, host: ArgumentsHost) {
    const ctx = host.switchToHttp();
    const req = ctx.getRequest();
    const res = ctx.getResponse();

    let code = 500;
    let msgKey = 'error.common.unknown';
    let args: Record<string, any> | undefined;

    if (exception instanceof HttpException) {
      const response: any = exception.getResponse();
      code = exception.getStatus();
      msgKey = response?.msg_key || msgKey;
      args = response?.args;
    }

    const msg = this.i18n.translate(msgKey, {
      lang: req.i18nLang,
      defaultValue: msgKey,
      args,
    });

    res.status(code).json({ code, msg_key: msgKey, msg, data: null });
  }
}

6) 语言资源示例

文件：apps/api/src/lang/zh-CN/common.json

{
  "success": "操作成功"
}

文件：apps/api/src/lang/en-US/common.json

{
  "success": "Success"
}

文件：apps/api/src/lang/zh-CN/error.json

{
  "auth": { "invalid_token": "令牌无效或已过期" },
  "common": { "unknown": "系统繁忙，请稍后重试" }
}

文件：apps/api/src/lang/en-US/error.json

{
  "auth": { "invalid_token": "Invalid or expired token" },
  "common": { "unknown": "Service is busy, please try later" }
}

文件：apps/api/src/lang/zh-CN/user.json

{
  "profile": { "updated": "资料已更新" }
}

文件：apps/api/src/lang/en-US/user.json

{
  "profile": { "updated": "Profile updated" }
}

7) 历史 key 别名（可选）

在拦截器或统一工具内对少量老 key 做映射：

const aliasMap = new Map<string, string>([
  ['SUCCESS', 'common.success'],
]);

function mapAlias(key: string) { return aliasMap.get(key) || key; }

8) 使用示例（Controller 返回约定）

return { code: 0, msg_key: 'user.profile.updated', data: { id: 1 } };

语言协商与 DI 导入规范

• 解析优先级：Query(lang) > Header(Accept-Language) > 默认 zh-CN。
• DI 与导入：推荐使用 BootLangModule（底层为 BootI18nModule）仅在 AppModule 里导入一次（全局模块），遵循项目的「Nest DI 与导入规范」。拦截器与过滤器以 Provider 方式注入 I18nService。

测试与验证

• 默认语言：

curl http://localhost:3000/api/ping
# => { code:0, msg_key:"common.success", msg:"操作成功" }

• 指定英文：

curl -H "Accept-Language: en-US" http://localhost:3000/api/ping
# 或
curl "http://localhost:3000/api/ping?lang=en-US"
# => { code:0, msg_key:"common.success", msg:"Success" }

• 错误示例：

# 返回 { code:401, msg_key:"error.auth.invalid_token", msg:"令牌无效或已过期" }

维护策略

• 新增文案：按模块/域定义 key，避免重复；中英文同时维护。
• 变更文案：保持 key 不变，更新不同语言的文本内容。
• 清理策略：定期检查未使用 key，删除并在变更日志记录。

与 Java 的对齐

• Java：沿用 .properties 的模块化与 key 命名；Nest 端资源内容与 Java 的 key 同名对齐。
• NestJS：使用 JSON 格式存储翻译资源，key 命名与 Java 保持一致。

// 术语对齐：对外事件与模块名统一使用 lang；内部技术栈保留 i18n。 如需我在 wwjcloud-nest-v1 中继续完成代码接入（创建 BootI18nModule、改造拦截器与异常过滤器、添加示例语言资源），请在本指南基础上确认，我将按以上目录与步骤实施。

依赖解耦合与兜底（推荐）

• 软依赖：拦截器/过滤器不对 I18nService 形成硬依赖；当未导入 BootLangModule 时，功能自动降级为直接返回 msg_key。
• 实现方式：运行时从 ModuleRef 中“可选获取” I18nService，未获取到则兜底。

示例：可选 i18n 的响应拦截器

import { CallHandler, ExecutionContext, Injectable, NestInterceptor } from '@nestjs/common';
import { ModuleRef } from '@nestjs/core';
import { I18nService } from 'nestjs-i18n';
import { Observable, map } from 'rxjs';

@Injectable()
export class ResponseInterceptor implements NestInterceptor {
  constructor(private readonly moduleRef: ModuleRef) {}

  private getI18n(): I18nService | undefined {
    // strict:false → 未注册时返回 undefined
    return this.moduleRef.get(I18nService, { strict: false });
  }

  intercept(ctx: ExecutionContext, next: CallHandler): Observable<any> {
    const req = ctx.switchToHttp().getRequest();
    const i18n = this.getI18n();
    return next.handle().pipe(
      map((original) => {
        const { code = 0, data = null, msg_key } = original ?? {};
        const key = msg_key || 'common.success';
        let msg = key;
        if (i18n) {
          try {
            const translated = i18n.translate(key, { lang: req.i18nLang });
            msg = translated || key;
          } catch {
            msg = key; // 兜底：翻译失败返回 key
          }
        }
        return { code, msg_key: key, msg, data };
      }),
    );
  }
}

异常过滤器同理：

import { ArgumentsHost, Catch, ExceptionFilter, HttpException } from '@nestjs/common';
import { ModuleRef } from '@nestjs/core';
import { I18nService } from 'nestjs-i18n';

@Catch()
export class HttpExceptionFilter implements ExceptionFilter {
  constructor(private readonly moduleRef: ModuleRef) {}
  private getI18n(): I18nService | undefined { return this.moduleRef.get(I18nService, { strict: false }); }

  catch(exception: unknown, host: ArgumentsHost) {
    const ctx = host.switchToHttp();
    const req = ctx.getRequest();
    const res = ctx.getResponse();
    const i18n = this.getI18n();

    let code = 500;
    let msgKey = 'error.common.unknown';
    let args: Record<string, any> | undefined;

    if (exception instanceof HttpException) {
      const response: any = exception.getResponse();
      code = exception.getStatus();
      msgKey = response?.msg_key || msgKey;
      args = response?.args;
    }

    let msg = msgKey;
    if (i18n) {
      try { msg = i18n.translate(msgKey, { lang: req.i18nLang /* args */ }) || msgKey; } catch { msg = msgKey; }
    }

    res.status(code).json({ code, msg_key: msgKey, msg, data: null });
  }
}

落地建议：

• 在 apps/api/src/app.module.ts 导入 BootLangModule 即启用翻译；测试或最简环境可跳过导入，系统仍可工作（只返回 msg_key）。
• 当引入 i18n 时，建议在 LANG_READY 就绪服务中校验语言资源目录存在并上报状态（见 V11-BOOT-READINESS.md）。