使用Intlayer翻译您的Nest backend | 国际化(i18n)

express-intlayer 是一个强大的国际化 (i18n) 中间件，专为 Express 应用程序设计，旨在通过基于客户端偏好提供本地化响应来使您的后端服务在全球范围内可访问。由于 NestJS 是构建在 Express 之上的，您可以将 express-intlayer 无缝集成到您的 NestJS 应用程序中，以有效处理多语言内容。

技术用例

• 以用户语言显示后端错误: 当发生错误时，用用户的母语显示消息可以改善理解并减少挫折感。这对于可能在前端组件（如 toasts 或 modals）中显示的动态错误消息特别有用。

• 检索多语言内容：对于从数据库中提取内容的应用程序，国际化确保您可以以多种语言提供此内容。这对于电子商务网站或内容管理系统等平台至关重要，这些平台需要以用户首选的语言显示产品描述、文章和其他内容。

• 发送多语言电子邮件：无论是事务性电子邮件、营销活动还是通知，用收件人的语言发送电子邮件可以显著提高参与度和有效性。

• 多语言推送通知：对于移动应用程序，以用户偏好的语言发送推送通知可以增强交互和留存率。这种个人化的方式可以使通知感觉更加相关和可操作。

• 其他通信：任何形式的后端通信，例如短信消息、系统警报或用户界面更新，都受益于使用用户的语言，确保清晰度并增强整体用户体验。

express-intlayer 是一个功能强大的国际化（i18n）中间件，适用于 Express 应用程序，旨在通过根据客户端的偏好提供本地化响应，使您的后端服务能够面向全球用户。由于 NestJS 构建在 Express 之上，您可以将 express-intlayer 无缝集成到您的 NestJS 应用中，有效处理多语言内容。

入门指南

创建一个新的 NestJS 项目

npm install -g @nestjs/cli
nest new my-nest-app

安装

要开始使用 express-intlayer，请使用 npm 安装该包：

npx intlayer init --interactive

--interactive 标志是可选的。如果您是 AI 代理，请使用 intlayer-cli init。

该命令将检测您的环境并安装所需的软件包。例如：

npm install intlayer express-intlayer

配置 tsconfig.json

为了在 TypeScript 中使用 Intlayer，请确保您的 tsconfig.json 已设置为支持 ES 模块。您可以通过将 module 和 moduleResolution 选项设置为 nodenext 来实现此目的。

{
  compilerOptions: {
    module: "nodenext",
    moduleResolution: "nodenext",
    // ... 其他选项
  },
}

设置

通过在项目根目录创建 intlayer.config.ts 来配置国际化设置：

import { Locales, type IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  internationalization: {
    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
    defaultLocale: Locales.ENGLISH,
  },
};

export default config;

声明您的内容

创建并管理您的内容声明以存储翻译：

您的内容声明可以定义在应用程序中的任何位置，只要它们被包含在 contentDir 目录中（默认是 ./src），并且文件扩展名符合内容声明的格式（默认是 .content.{json,ts,tsx,js,jsx,mjs,cjs,md,mdx,yaml,yml}）。

更多详情，请参阅内容声明文档。

Express 中间件设置

将 express-intlayer 中间件集成到您的 NestJS 应用程序中以处理国际化：

import { MiddlewareConsumer, Module, NestModule } from "@nestjs/common";
import { AppController } from "./app.controller";
import { AppService } from "./app.service";
import { intlayer } from "express-intlayer";

@Module({
  imports: [],
  controllers: [AppController],
  providers: [AppService],
})
export class AppModule implements NestModule {
  configure(consumer: MiddlewareConsumer) {
    consumer.apply(intlayer()).forRoutes("*"); // 应用于所有路由
  }
}

在您的服务或控制器中使用翻译

您现在可以使用 getIntlayer 函数在服务或控制器中访问翻译：

import { Injectable } from "@nestjs/common";
import { getIntlayer } from "express-intlayer";

@Injectable()
export class AppService {
  getHello(): string {
    return getIntlayer("app").greet;
  }
}

兼容性

express-intlayer 完全兼容：

• 适用于 React 应用的 react-intlayer
• 适用于 Next.js 应用的 next-intlayer
• 适用于 Vite 应用的 vite-intlayer

它还可以无缝配合各种环境中的任何国际化解决方案，包括浏览器和 API 请求。您可以自定义中间件，通过请求头或 Cookie 来检测语言环境：

import { Locales, type IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  // ... 其他配置选项
  routing: {
    storage: [
      { type: "header", name: "my-locale-header" },
      { type: "cookie", name: "my-locale-cookie" },
    ],
  },
};

export default config;

默认情况下，express-intlayer 会解析 Accept-Language 头来确定客户端的首选语言。

有关配置和高级主题的更多信息，请访问我们的文档。

配置 TypeScript

express-intlayer 利用 TypeScript 强大的功能来增强国际化过程。TypeScript 的静态类型确保每个翻译键都被考虑到，减少了缺失翻译的风险，并提升了可维护性。

确保自动生成的类型（默认位于 ./types/intlayer.d.ts）已包含在你的 tsconfig.json 文件中。

{
  // ... 你现有的 TypeScript 配置
  include: [
    // ... 你现有的 TypeScript 配置
    ".intlayer/**/*.ts", // 包含自动生成的类型
  ],
}

VS Code 扩展

为了提升您使用 Intlayer 的开发体验，您可以安装官方的 Intlayer VS Code 扩展。

从 VS Code 市场安装

该扩展提供：

• 翻译键的 自动补全。
• 缺失翻译的 实时错误检测。
• 翻译内容的 内联预览。
• 轻松创建和更新翻译的 快速操作。

有关如何使用该扩展的更多详细信息，请参阅 Intlayer VS Code 扩展文档。

Git 配置

建议忽略 Intlayer 生成的文件，这样可以避免将它们提交到您的 Git 仓库中。

要做到这一点，您可以将以下指令添加到您的 .gitignore 文件中：

# 忽略 Intlayer 生成的文件
.intlayer

常见问题