使用 Intlayer 翻译您的 AdonisJS 后端网站 | 国际化 (i18n)

adonis-intlayer 是一个专为 AdonisJS 应用程序设计的强大国际化 (i18n) 包，旨在通过根据客户端首选项提供本地化响应，使您的后端服务全球化。

实际用例

• 以用户语言显示后端错误：当发生错误时，以用户的母语显示消息可以提高理解力并减少挫败感。这对于可能显示在前端组件（如 toast 或模态框）中的动态错误消息特别有用。

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

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

• 多语言推送通知：对于移动应用程序，以用户首选语言发送推送通知可以增强互动和留存。这种个性化的触达可以使通知感觉更相关且更具操作性。

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

通过对后端进行国际化，您的应用程序不仅尊重文化差异，而且更好地符合全球市场需求，这是在全球范围内扩展服务的关键一步。

入门

See Application Template on GitHub.

安装

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

npx intlayer init --interactive

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

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

npm install intlayer adonis-intlayer

设置

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

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

const config: IntlayerConfig = {
  internationalization: {
    locales: [
      Locales.ENGLISH,
      Locales.RUSSIAN,
      Locales.JAPANESE,
      Locales.FRENCH,
      Locales.KOREAN,
      Locales.CHINESE,
      Locales.SPANISH,
      Locales.GERMAN,
      Locales.ARABIC,
      Locales.ITALIAN,
      Locales.ENGLISH_UNITED_KINGDOM,
      Locales.PORTUGUESE,
      Locales.HINDI,
      Locales.TURKISH,
      Locales.POLISH,
      Locales.INDONESIAN,
      Locales.VIETNAMESE,
      Locales.UKRAINIAN,
    ],
    defaultLocale: Locales.ENGLISH,
  },
};

export default config;

声明内容

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

import { t, type Dictionary } from "intlayer";

const indexContent = {
  key: "index",
  content: {
    exampleOfContent: t({
      en: "Example of returned content in English",
      fr: "Exemple de contenu renvoyé en français",
      zh: "中文返回内容示例",
      "es-ES": "Ejemplo de contenido devuelto en español (España)",
      "es-MX": "Ejemplo de contenido devuelto en español (México)",
    }),
  },
} satisfies Dictionary;

export default indexContent;

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

有关更多详细信息，请参阅 内容声明文档。

AdonisJS 应用程序设置

设置您的 AdonisJS 应用程序以使用 adonis-intlayer。

注册中间件

首先，您需要在应用程序中注册 intlayer 中间件。

router.use([() => import("adonis-intlayer/middleware")]);

定义路由

import router from "@adonisjs/core/services/router";
import { t, getIntlayer, getDictionary } from "adonis-intlayer";
import indexContent from "../app/index.content";

router.get("/t_example", async () => {
  return t({
    en: "Example of returned content in English",
    fr: "Exemple de contenu renvoyé en français",
    zh: "中文返回内容示例",
    "es-ES": "Ejemplo de contenido devuelto en español (España)",
    "es-MX": "Ejemplo de contenido devuelto en español (México)",
  });
});

router.get("/getIntlayer_example", async () => {
  return getIntlayer("index").exampleOfContent;
});

router.get("/getDictionary_example", async () => {
  return getDictionary(indexContent).exampleOfContent;
});

函数

adonis-intlayer 导出了几个函数来处理应用程序中的国际化：

• t(content, locale?)：基础翻译函数。
• getIntlayer(key, locale?)：通过键从字典中检索内容。
• getDictionary(dictionary, locale?)：从特定字典对象检索内容。
• getLocale()：从请求上下文中检索当前语言区域。

在控制器中使用

import type { HttpContext } from "@adonisjs/core/http";
import { t } from "adonis-intlayer";

export default class ExampleController {
  async index({ response }: HttpContext) {
    return response.send(
      t({
        en: "Hello from controller",
        zh: "来自控制器的你好",
      })
    );
  }
}

兼容性

adonis-intlayer 完全兼容：

• react-intlayer 用于 React 应用程序
• next-intlayer 用于 Next.js 应用程序
• vite-intlayer 用于 Vite 应用程序

它还可以无缝地与跨各种环境（包括浏览器和 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;

默认情况下，adonis-intlayer 将解释 Accept-Language 标头以确定客户端的首选语言。

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

配置 TypeScript

adonis-intlayer 利用 TypeScript 的强大功能来增强国际化过程。TypeScript 的静态类型确保每个翻译键都被考虑到，从而降低丢失翻译的风险并提高可维护性。

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

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

VS Code 扩展

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

从 VS Code 市场安装

此扩展提供：

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

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

Git 配置

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

为此，您可以将以下指令添加到您的 .gitignore 文件中：

# 忽略 Intlayer 生成的文件
.intlayer

常见问题