@intlayer/docs 7.5.9 → 7.5.10

package/docs/zh/intlayer_with_fastify.md

@@ -0,0 +1,451 @@
+---
+createdAt: 2025-12-30
+updatedAt: 2025-12-30
+title: 如何翻译你的 Fastify 后端 — 国际化 (i18n) 指南 2026
+description: 了解如何使你的 Fastify 后端实现多语言。按照文档对其进行国际化 (i18n) 并翻译。
+keywords:
+  - 国际化
+  - 文档
+  - Intlayer
+  - Fastify
+  - JavaScript
+  - 后端
+slugs:
+  - doc
+  - environment
+  - fastify
+applicationTemplate: https://github.com/aymericzip/intlayer-fastify-template
+history:
+  - version: 7.6.0
+    date: 2025-12-31
+    changes: 添加 init 命令
+  - version: 7.6.0
+    date: 2025-12-31
+    changes: 初始化历史
+---
+
+# 使用 Intlayer 翻译你的 Fastify 后端网站 | 国际化 (i18n)
+
+`fastify-intlayer` 是一个功能强大的 Fastify 应用国际化 (i18n) 插件，旨在通过根据客户端偏好提供本地化响应，使你的后端服务可在全球范围内访问。
+
+### 实用用例
+
+- **以用户语言显示后端错误**：当发生错误时，以用户的母语显示消息能提高理解并减少挫败感。这对于可能在前端组件（如 toast 或模态窗口）中显示的动态错误消息尤其有用。
+
+`fastify-intlayer` 是一个强大的 Fastify 应用国际化 (i18n) 插件，旨在根据客户端的偏好提供本地化响应，使你的后端服务在全球范围内可访问。
+
+### 实用场景
+
+- **以用户语言显示后端错误**：当发生错误时，以用户的母语显示消息可以提高理解并减少挫折感。这对那些可能在前端组件（例如 toasts 或 modals）中显示的动态错误消息尤其有用。
+- **检索多语言内容**：对于从数据库拉取内容的应用，国际化可确保你以多种语言提供这些内容。这对于需要以用户首选语言显示产品描述、文章和其他内容的平台（如电子商务网站或内容管理系统）至关重要。
+- **发送多语言电子邮件**：无论是事务性邮件、营销活动还是通知，以收件人语言发送邮件都能显著提高参与度和效果。
+- **多语言推送通知**：对于移动应用，在用户偏好的语言中发送推送通知可以提升互动和用户留存。这样的个性化处理会让通知显得更相关且更容易促使用户采取行动。
+- **其他通讯**：来自后端的任何形式的通信，例如短信、系统告警或用户界面更新，在用户语言中呈现都能提升清晰度并增强整体用户体验。
+
+通过对后端进行国际化，您的应用不仅尊重文化差异，而且更符合全球市场需求，这是一项将服务扩展到全球的重要步骤。
+
+## 入门
+
+### 安装
+
+要开始使用 `fastify-intlayer`，请使用 npm 安装该包：
+
+```bash packageManager="npm"
+npm install intlayer fastify-intlayer
+npx intlayer init
+
+```
+
+```bash packageManager="pnpm"
+pnpm add intlayer fastify-intlayer
+pnpm intlayer init
+
+```
+
+```bash packageManager="yarn"
+yarn add intlayer fastify-intlayer
+yarn intlayer init
+
+```
+
+```bash packageManager="bun"
+bun add intlayer fastify-intlayer
+bunx intlayer init
+
+```
+
+### 设置
+
+通过在项目根目录创建一个 `intlayer.config.ts` 来配置国际化设置：
+
+```typescript fileName="intlayer.config.ts"  codeFormat="typescript"
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [
+      Locales.ENGLISH,
+      Locales.FRENCH,
+      Locales.SPANISH_MEXICO,
+      Locales.SPANISH_SPAIN,
+    ],
+    defaultLocale: Locales.ENGLISH,
+  },
+};
+
+export default config;
+```
+
+```javascript fileName="intlayer.config.mjs" codeFormat="esm"
+import { Locales } from "intlayer";
+
+/** @type {import('intlayer').IntlayerConfig} */ // 类型注释：Intlayer 配置
+const config = {
+  internationalization: {
+    locales: [
+      Locales.ENGLISH,
+      Locales.FRENCH,
+      Locales.SPANISH_MEXICO,
+      Locales.SPANISH_SPAIN,
+    ],
+    defaultLocale: Locales.ENGLISH,
+  },
+};
+
+export default config;
+```
+
+```javascript fileName="intlayer.config.cjs" codeFormat="commonjs"
+const { Locales } = require("intlayer");
+
+/** @type {import('intlayer').IntlayerConfig} */ // 类型注释：Intlayer 配置
+const config = {
+  internationalization: {
+    locales: [
+      Locales.ENGLISH,
+      Locales.FRENCH,
+      Locales.SPANISH_MEXICO,
+      Locales.SPANISH_SPAIN,
+    ],
+    defaultLocale: Locales.ENGLISH,
+  },
+};
+
+module.exports = config;
+```
+
+### 声明您的内容
+
+创建并管理您的内容声明以存储翻译：
+
+```typescript fileName="src/index.content.ts" contentDeclarationFormat="typescript"
+import { t, type Dictionary } from "intlayer";
+
+const indexContent = {
+  key: "index",
+  content: {
+    exampleOfContent: t({
+      zh: "返回内容示例（英语）",
+      en: "Example of returned content in English",
+      fr: "Exemple de contenu renvoyé en français",
+      "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;
+```
+
+```javascript fileName="src/index.content.mjs" contentDeclarationFormat="esm"
+import { t } from "intlayer";
+
+/** @type {import('intlayer').Dictionary} */ // 类型注解：import('intlayer').Dictionary
+const indexContent = {
+  key: "index",
+  content: {
+    exampleOfContent: t({
+      zh: "示例：返回的内容（中文）",
+      en: "Example of returned content in English",
+      fr: "Exemple de contenu renvoyé en français",
+      "es-ES": "Ejemplo de contenido devuelto en español (España)",
+      "es-MX": "Ejemplo de contenido devuelto en español (México)",
+    }),
+  },
+};
+
+export default indexContent;
+```
+
+```javascript fileName="src/index.content.cjs" contentDeclarationFormat="commonjs"
+const { t } = require("intlayer");
+
+/** @type {import('intlayer').Dictionary} */ // 类型注解：import('intlayer').Dictionary
+const indexContent = {
+  key: "index",
+  content: {
+    exampleOfContent: t({
+      zh: "示例：返回的内容（中文）",
+      en: "Example of returned content in English",
+      fr: "Exemple de contenu renvoyé en français",
+      "es-ES": "Ejemplo de contenido devuelto en español (España)",
+      "es-MX": "Ejemplo de contenido devuelto en español (México)",
+    }),
+  },
+};
+
+module.exports = indexContent;
+```
+
+```json fileName="src/index.content.json" contentDeclarationFormat="json"
+{
+  "$schema": "https://intlayer.org/schema.json",
+  "key": "index",
+  "content": {
+    "exampleOfContent": {
+      "nodeType": "translation",
+      "translation": {
+        "zh": "返回内容示例（英语）",
+        "en": "Example of returned content in English",
+        "fr": "Exemple de contenu renvoyé en français",
+        "es-ES": "Ejemplo de contenido devuelto en español (España)",
+        "es-MX": "Ejemplo de contenido devuelto en español (México)"
+      }
+    }
+  }
+}
+```
+
+> 一旦内容声明文件被包含到 `contentDir` 目录（默认 `./src`）中，你可以在应用的任何位置定义它们。并且文件扩展名应匹配内容声明文件扩展名（默认 `.content.{json,ts,tsx,js,jsx,mjs,mjx,cjs,cjx}`）。
+
+> 更多详情，请参阅 [内容声明文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/dictionary/content_file.md)。
+
+### Fastify 应用设置
+
+配置你的 Fastify 应用以使用 `fastify-intlayer`：
+
+```typescript fileName="src/index.ts" codeFormat="typescript"
+import Fastify from "fastify";
+import { intlayer, t, getDictionary, getIntlayer } from "fastify-intlayer";
+import dictionaryExample from "./index.content";
+
+const fastify = Fastify({ logger: true });
+
+// 加载国际化插件
+await fastify.register(intlayer);
+
+// 路由
+fastify.get("/t_example", async (_req, reply) => {
+  return t({
+    zh: "返回的内容示例（中文）",
+    en: "Example of returned content in English",
+    fr: "Exemple de contenu renvoyé en français",
+    "es-ES": "Ejemplo de contenido devuelto en español (España)",
+    "es-MX": "Ejemplo de contenido devuelto en español (México)",
+  });
+});
+
+fastify.get("/getIntlayer_example", async (_req, reply) => {
+  return getIntlayer("index").exampleOfContent;
+});
+
+fastify.get("/getDictionary_example", async (_req, reply) => {
+  return getDictionary(dictionaryExample).exampleOfContent;
+});
+
+// 启动服务器
+const start = async () => {
+  try {
+    await fastify.listen({ port: 3000 });
+  } catch (err) {
+    fastify.log.error(err);
+    process.exit(1);
+  }
+};
+
+start();
+```
+
+```javascript fileName="src/index.mjs" codeFormat="esm"
+import Fastify from "fastify";
+import { intlayer, t, getDictionary, getIntlayer } from "fastify-intlayer";
+import dictionaryExample from "./index.content";
+
+const fastify = Fastify({ logger: true });
+
+// 加载国际化插件
+await fastify.register(intlayer);
+
+// 路由
+fastify.get("/t_example", async (_req, reply) => {
+  return t({
+    zh: "示例：以中文返回的内容",
+    en: "Example of returned content in English",
+    fr: "Exemple de contenu renvoyé en français",
+    "es-ES": "Ejemplo de contenido devuelto en español (España)",
+    "es-MX": "Ejemplo de contenido devuelto en español (México)",
+  });
+});
+
+fastify.get("/getIntlayer_example", async (_req, reply) => {
+  return getIntlayer("index").exampleOfContent;
+});
+
+fastify.get("/getDictionary_example", async (_req, reply) => {
+  return getDictionary(dictionaryExample).exampleOfContent;
+});
+
+// 启动服务器
+const start = async () => {
+  try {
+    await fastify.listen({ port: 3000 });
+  } catch (err) {
+    fastify.log.error(err);
+    process.exit(1);
+  }
+};
+
+start();
+```
+
+```javascript fileName="src/index.cjs" codeFormat="commonjs"
+const Fastify = require("fastify");
+const { intlayer, t, getDictionary, getIntlayer } = require("fastify-intlayer");
+const dictionaryExample = require("./index.content");
+
+const fastify = Fastify({ logger: true });
+
+// 启动服务器的 async/await 包装器
+const start = async () => {
+  try {
+    // 加载国际化插件
+    await fastify.register(intlayer);
+
+    // 路由
+    fastify.get("/t_example", async (_req, reply) => {
+      return t({
+        zh: "示例：以英文/法文/西班牙文返回的内容（参见各语言对应条目）",
+        en: "Example of returned content in English",
+        fr: "Exemple de contenu renvoyé en français",
+        "es-ES": "Ejemplo de contenido devuelto en español (España)",
+        "es-MX": "Ejemplo de contenido devuelto en español (México)",
+      });
+    });
+
+    fastify.get("/getIntlayer_example", async (_req, reply) => {
+      return getIntlayer("index").exampleOfContent;
+    });
+
+    fastify.get("/getDictionary_example", async (_req, reply) => {
+      return getDictionary(dictionaryExample).exampleOfContent;
+    });
+
+    await fastify.listen({ port: 3000 });
+  } catch (err) {
+    fastify.log.error(err);
+    process.exit(1);
+  }
+};
+
+start();
+```
+
+### 兼容性
+
+`fastify-intlayer` 完全兼容：
+
+- [`react-intlayer`](<https://www.google.com/search?q=%5Bhttps://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/packages/react-intlayer/index.md%5D(https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/packages/react-intlayer/index.md)>) 用于 React 应用
+- [`next-intlayer`](<https://www.google.com/search?q=%5Bhttps://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/packages/next-intlayer/index.md%5D(https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/packages/next-intlayer/index.md)>) 用于 Next.js 应用
+- [`vite-intlayer`](<https://www.google.com/search?q=%5Bhttps://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/packages/vite-intlayer/index.md%5D(https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/packages/vite-intlayer/index.md)>) 适用于 Vite 应用程序
+
+它还可与各种环境中的任何国际化解决方案无缝配合，包括浏览器和 API 请求。您可以自定义中间件，通过请求头或 Cookie 检测 locale：
+
+```typescript fileName="intlayer.config.ts" codeFormat="typescript"
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  // ... 其他配置选项
+  middleware: {
+    headerName: "my-locale-header",
+    cookieName: "my-locale-cookie",
+  },
+};
+
+export default config;
+```
+
+```javascript fileName="intlayer.config.mjs" codeFormat="esm"
+import { Locales } from "intlayer";
+
+/** @type {import('intlayer').IntlayerConfig} */
+const config = {
+  // ... 其他配置选项
+  middleware: {
+    headerName: "my-locale-header",
+    cookieName: "my-locale-cookie",
+  },
+};
+
+export default config;
+```
+
+```javascript fileName="intlayer.config.cjs" codeFormat="commonjs"
+const { Locales } = require("intlayer");
+
+/** @type {import('intlayer').IntlayerConfig} */
+const config = {
+  // ... 其他配置选项
+  middleware: {
+    headerName: "my-locale-header",
+    cookieName: "my-locale-cookie",
+  },
+};
+
+module.exports = config;
+```
+
+默认情况下，`fastify-intlayer` 会解析 `Accept-Language` 头以确定客户端的首选语言。
+
+> 欲了解有关配置和高级主题的更多信息，请访问我们的[文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/configuration.md)。
+
+### 配置 TypeScript
+
+`fastify-intlayer` 利用 TypeScript 强大的能力来增强国际化流程。TypeScript 的静态类型确保每个翻译键都被涵盖，降低遗漏翻译的风险并提高可维护性。
+
+确保自动生成的类型（默认位于 ./types/intlayer.d.ts）已包含在你的 tsconfig.json 文件中。
+
+```json5 fileName="tsconfig.json"
+{
+  // ... 你现有的 TypeScript 配置
+  "include": [
+    // ... 你现有的 TypeScript 配置
+    ".intlayer/**/*.ts", // 包含自动生成的类型
+  ],
+}
+```
+
+### VS Code 扩展
+
+为提升您使用 Intlayer 的开发体验，您可以安装官方的 **Intlayer VS Code Extension**。
+
+[从 VS Code Marketplace 安装](https://marketplace.visualstudio.com/items?itemName=intlayer.intlayer-vs-code-extension)
+
+该扩展提供：
+
+- **自动完成（Autocompletion）** 翻译键。
+- **实时错误检测**，用于发现缺失的翻译。
+- **内联预览** 已翻译的内容。
+- **快速操作**，便于快速创建和更新翻译。
+
+有关如何使用该扩展的更多详细信息，请参阅 [Intlayer VS Code Extension 文档](https://intlayer.org/doc/vs-code-extension)。
+
+### Git 配置
+
+建议忽略 Intlayer 生成的文件，这样可以避免将它们提交到 Git 仓库。
+
+为此，您可以将以下指令添加到 `.gitignore` 文件：
+
+```plaintext fileName=".gitignore"
+# 忽略 Intlayer 生成的文件
+.intlayer
+```

package/docs/zh/readme.md

@@ -50,7 +50,7 @@ Intlayer 是一个面向网页和移动应用的**现代国际化解决方案**
 | 功能                                                                                                                                                | 描述                                                                                                                                                                                                                                                                                                                                                        |
 | --------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | <img src="https://github.com/aymericzip/intlayer/blob/main/docs/assets/frameworks.png?raw=true" alt="功能" width="700">                             | **跨框架支持**<br><br>Intlayer 兼容所有主流框架和库，包括 Next.js、React、Vite、Vue.js、Nuxt、Preact、Express 等。                                                                                                                                                                                                                                          |
-| <img src="https://github.com/aymericzip/intlayer/blob/main/docs/assets/javascript_content_management.png?raw=true" alt="Feature" width="700">       | **基于JavaScript的内容管理**<br><br>利用JavaScript的灵活性高效地定义和管理您的内容。<br><br> - [内容声明](https://intlayer.org/doc/concept/content)                                                                                                                                                                                                         |
+| <img src="https://github.com/aymericzip/intlayer/blob/main/docs/assets/javascript_content_management.jpg?raw=true" alt="Feature" width="700">       | **基于JavaScript的内容管理**<br><br>利用JavaScript的灵活性高效地定义和管理您的内容。<br><br> - [内容声明](https://intlayer.org/doc/concept/content)                                                                                                                                                                                                         |
 | <img src="https://github.com/aymericzip/intlayer/blob/main/docs/assets/per_locale_content_declaration_file.png?raw=true" alt="Feature" width="700"> | **每语言内容声明文件**<br><br>通过在自动生成之前只声明一次内容，加快您的开发速度。<br><br> - [每语言内容声明文件](https://intlayer.org/doc/concept/per-locale-file)                                                                                                                                                                                         |
 | <img src="https://github.com/aymericzip/intlayer/blob/main/docs/assets/autocompletion.png?raw=true" alt="Feature" width="700">                      | **类型安全环境**<br><br>利用 TypeScript 确保您的内容定义和代码无错误，同时享受 IDE 自动补全的便利。<br><br> - [TypeScript 配置](https://intlayer.org/doc/environment/vite-and-react#configure-typescript)                                                                                                                                                   |
 | <img src="https://github.com/aymericzip/intlayer/blob/main/docs/assets/config_file.png?raw=true" alt="功能" width="700">                            | **简化设置**<br><br>通过最少的配置快速启动。轻松调整国际化、路由、AI、构建和内容处理的设置。<br><br> - [探索 Next.js 集成](https://intlayer.org/doc/environment/nextjs)                                                                                                                                                                                     |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intlayer/docs",
-  "version": "7.5.9",
+  "version": "7.5.10",
   "private": false,
   "description": "Intlayer documentation",
   "keywords": [
@@ -73,13 +73,13 @@
     "watch": "webpack --config ./webpack.config.ts --watch"
   },
   "dependencies": {
-    "@intlayer/config": "7.5.9",
-    "@intlayer/core": "7.5.9",
-    "@intlayer/types": "7.5.9"
+    "@intlayer/config": "7.5.10",
+    "@intlayer/core": "7.5.10",
+    "@intlayer/types": "7.5.10"
   },
   "devDependencies": {
-    "@intlayer/api": "7.5.9",
-    "@intlayer/cli": "7.5.9",
+    "@intlayer/api": "7.5.10",
+    "@intlayer/cli": "7.5.10",
     "@types/node": "25.0.3",
     "@utils/ts-config": "1.0.4",
     "@utils/ts-config-types": "1.0.4",

package/src/generated/docs.entry.ts

@@ -908,6 +908,25 @@ export const docsEntry = {
     id: readLocale('intlayer_with_express.md', 'id'),
     vi: readLocale('intlayer_with_express.md', 'vi'),
   } as unknown as Record<LocalesValues, Promise<string>>,
+  './docs/en/intlayer_with_fastify.md': {
+    en: readLocale('intlayer_with_fastify.md', 'en'),
+    ru: readLocale('intlayer_with_fastify.md', 'ru'),
+    ja: readLocale('intlayer_with_fastify.md', 'ja'),
+    fr: readLocale('intlayer_with_fastify.md', 'fr'),
+    ko: readLocale('intlayer_with_fastify.md', 'ko'),
+    zh: readLocale('intlayer_with_fastify.md', 'zh'),
+    es: readLocale('intlayer_with_fastify.md', 'es'),
+    de: readLocale('intlayer_with_fastify.md', 'de'),
+    ar: readLocale('intlayer_with_fastify.md', 'ar'),
+    it: readLocale('intlayer_with_fastify.md', 'it'),
+    'en-GB': readLocale('intlayer_with_fastify.md', 'en-GB'),
+    pt: readLocale('intlayer_with_fastify.md', 'pt'),
+    hi: readLocale('intlayer_with_fastify.md', 'hi'),
+    tr: readLocale('intlayer_with_fastify.md', 'tr'),
+    pl: readLocale('intlayer_with_fastify.md', 'pl'),
+    id: readLocale('intlayer_with_fastify.md', 'id'),
+    vi: readLocale('intlayer_with_fastify.md', 'vi'),
+  } as unknown as Record<LocalesValues, Promise<string>>,
   './docs/en/intlayer_with_lynx+react.md': {
     en: readLocale('intlayer_with_lynx+react.md', 'en'),
     ru: readLocale('intlayer_with_lynx+react.md', 'ru'),