@intlayer/docs 5.5.8

package/zh/packages/lynx-intlayer/index.md

@@ -0,0 +1,60 @@
+# lynx-intlayer: 国际化 (i18n) 一个 Lynx 应用程序
+
+**Intlayer** 是专为 JavaScript 开发者设计的一套工具包。它兼容 React、React 和 Express.js 等框架。
+
+**`lynx-intlayer` 包** 允许您对 Vite 应用程序进行国际化。它包括 Metro 插件，通过环境变量将配置设置到 [Lynx 打包工具](https://lynxjs.org/index.html)。
+
+## 为什么要对您的 Lynx 应用程序进行国际化？
+
+对您的 Lynx 应用程序进行国际化对于有效服务全球用户至关重要。它允许您的应用程序以每个用户偏好的语言提供内容和消息。这种能力提升了用户体验，并通过使您的应用程序更易于访问和更贴近不同语言背景的人群，从而扩大了应用程序的覆盖范围。
+
+## 配置
+
+`lynx-intlayer` 包与 [`react-intlayer` 包](https://github.com/aymericzip/intlayer/blob/main/docs/zh/packages/react-intlayer/index.md) 和 [`intlayer` 包](https://github.com/aymericzip/intlayer/blob/main/docs/zh/packages/intlayer/index.md) 无缝协作。请查看相关文档以获取更多信息。
+
+## 安装
+
+使用您喜欢的包管理器安装必要的包：
+
+```bash packageManager="npm"
+npm install lynx-intlayer
+```
+
+```bash packageManager="yarn"
+yarn add lynx-intlayer
+```
+
+```bash packageManager="pnpm"
+pnpm add lynx-intlayer
+```
+
+## 使用示例
+
+查看如何将插件包含到您的 Vite 配置中的示例。
+
+```ts
+// lynx.config.ts
+import { defineConfig } from "@lynx-js/rspeedy";
+import { pluginIntlayerLynx } from "lynx-intlayer/plugin";
+
+export default defineConfig({
+  plugins: [
+    // ... 其他插件
+    pluginIntlayerLynx(),
+  ],
+});
+```
+
+## 掌握 Vite 应用程序的国际化
+
+Intlayer 提供了许多功能来帮助您对 Vite 应用程序进行国际化。
+
+**要了解更多这些功能，请参考 [使用 Intlayer 和 Lynx 的 React 国际化 (i18n)](https://github.com/aymericzip/intlayer/blob/main/docs/zh/intlayer_with_lynx+react.md) 指南，适用于 Lynx 应用程序。**
+
+## 阅读关于 Intlayer 的信息
+
+- [Intlayer 网站](https://intlayer.org)
+- [Intlayer 文档](https://intlayer.org/doc)
+- [Intlayer GitHub](https://github.com/aymericzip/intlayer)
+
+- [向我们的智能文档提问](https://intlayer.org/docchat)

package/zh/packages/next-intlayer/index.md

@@ -0,0 +1,267 @@
+# next-intlayer: 用于国际化 (i18n) Next.js 应用程序的 NPM 包
+
+**Intlayer** 是专为 JavaScript 开发人员设计的一套包。它兼容 React、Next.js 和 Express.js 等框架。
+
+**`next-intlayer` 包** 允许您国际化您的 Next.js 应用程序。它为 Next.js 国际化提供了上下文提供者和钩子。此外，它还包括用于将 Intlayer 与 [Webpack](https://webpack.js.org/) 或 [Turbopack](https://nextjs.org/docs/app/api-reference/turbopack) 集成的 Next.js 插件，以及用于检测用户首选语言环境、管理 Cookie 和处理 URL 重定向的中间件。
+
+## 为什么要国际化您的 Next.js 应用程序？
+
+国际化您的 Next.js 应用程序对于有效服务全球受众至关重要。它使您的应用程序能够以每个用户的首选语言传递内容和消息。这种能力增强了用户体验，并通过使您的应用程序对不同语言背景的人更具可访问性和相关性，从而扩大了应用程序的覆盖范围。
+
+## 为什么要集成 Intlayer？
+
+- **JavaScript 驱动的内容管理**：利用 JavaScript 的灵活性高效地定义和管理您的内容。
+- **类型安全环境**：利用 TypeScript 确保您的所有内容定义精确且无错误。
+- **集成的内容文件**：将翻译与其各自的组件紧密结合，增强可维护性和清晰性。
+
+## 安装
+
+使用您喜欢的包管理器安装必要的包：
+
+```bash packageManager="npm"
+npm install next-intlayer
+```
+
+```bash packageManager="yarn"
+yarn add next-intlayer
+```
+
+```bash packageManager="pnpm"
+pnpm add next-intlayer
+```
+
+## 使用示例
+
+使用 Intlayer，您可以在代码库中的任何地方以结构化的方式声明您的内容。
+
+默认情况下，Intlayer 会扫描扩展名为 `.content.{json,ts,tsx,js,jsx,mjs,mjx,cjs,cjx}` 的文件。
+
+> 您可以通过在[配置文件](https://github.com/aymericzip/intlayer/blob/main/docs/zh/configuration.md)中设置 `contentDir` 属性来修改默认扩展名。
+
+```bash codeFormat="typescript"
+.
+├── intlayer.config.ts
+└── src
+    └── components
+        ├── ClientComponent
+        │   ├── index.content.ts
+        │   └── index.tsx
+        └── ServerComponent
+            ├── index.content.ts
+            └── index.tsx
+```
+
+```bash codeFormat="esm"
+.
+├── intlayer.config.mjs
+└── src
+    └── components
+        ├── ClientComponent
+        │   ├── index.content.mjs
+        │   └── index.mjx
+        └── ServerComponent
+            ├── index.content.mjs
+            └── index.mjx
+```
+
+```bash codeFormat="commonjs"
+.
+├── intlayer.config.cjs
+└── src
+    └── components
+        ├── ClientComponent
+        │   ├── index.content.cjs
+        │   └── index.cjx
+        └── ServerComponent
+            ├── index.content.cjs
+            └── index.cjx
+```
+
+### 声明您的内容
+
+`next-intlayer` 是为与 [`intlayer` 包](https://github.com/aymericzip/intlayer/blob/main/docs/zh/packages/intlayer/index.md)一起使用而设计的。`intlayer` 是一个允许您在代码中的任何地方声明内容的包。它将多语言内容声明转换为结构化字典，并无缝集成到您的应用程序中。
+
+以下是内容声明的示例：
+
+```tsx fileName="src/ClientComponent/index.content.ts" codeFormat="typescript"
+import { t, type Dictionary } from "intlayer";
+
+const clientComponentContent = {
+  key: "client-component",
+  content: {
+    myTranslatedContent: t({
+      en: "Hello World",
+      fr: "Bonjour le monde",
+      es: "Hola Mundo",
+      zh: "你好，世界",
+    }),
+    numberOfCar: enu({
+      "<-1": "少于负一辆车",
+      "-1": "负一辆车",
+      "0": "没有车",
+      "1": "一辆车",
+      ">5": "一些车",
+      ">19": "很多车",
+    }),
+  },
+} satisfies Dictionary;
+
+export default clientComponentContent;
+```
+
+```jsx fileName="src/ClientComponent/index.content.mjs" contentDeclarationFormat="esm"
+import { t } from "intlayer";
+
+/** @type {import('intlayer').Dictionary} */
+const clientComponentContent = {
+  key: "client-component",
+  content: {
+    myTranslatedContent: t({
+      en: "Hello World",
+      fr: "Bonjour le monde",
+      es: "Hola Mundo",
+      zh: "你好，世界",
+    }),
+    numberOfCar: enu({
+      "<-1": "少于负一辆车",
+      "-1": "负一辆车",
+      "0": "没有车",
+      "1": "一辆车",
+      ">5": "一些车",
+      ">19": "很多车",
+    }),
+  },
+};
+
+export default clientComponentContent;
+```
+
+```jsx fileName="src/ClientComponent/index.content.cjs" contentDeclarationFormat="commonjs"
+const { t } = require("intlayer");
+
+/** @type {import('intlayer').Dictionary} */
+const clientComponentContent = {
+  key: "client-component",
+  content: {
+    myTranslatedContent: t({
+      en: "Hello World",
+      fr: "Bonjour le monde",
+      es: "Hola Mundo",
+      zh: "你好，世界",
+    }),
+    numberOfCar: enu({
+      "<-1": "少于负一辆车",
+      "-1": "负一辆车",
+      "0": "没有车",
+      "1": "一辆车",
+      ">5": "一些车",
+      ">19": "很多车",
+    }),
+  },
+};
+
+module.exports = clientComponentContent;
+```
+
+```json fileName="src/ClientComponent/index.content.json" codeFormat="json"
+{
+  "key": "client-component",
+  "content": {
+    "myTranslatedContent": {
+      "nodeType": "translation",
+      "translation": {
+        "en": "Hello World",
+        "fr": "Bonjour le monde",
+        "es": "Hola Mundo",
+        "zh": "你好，世界"
+      }
+    },
+    "numberOfCar": {
+      "nodeType": "enumeration",
+      "enumeration": {
+        "<-1": "少于负一辆车",
+        "-1": "负一辆车",
+        "0": "没有车",
+        "1": "一辆车",
+        ">5": "一些车",
+        ">19": "很多车"
+      }
+    }
+  }
+}
+```
+
+### 在代码中使用内容
+
+声明内容后，您可以在代码中使用它。以下是如何在 React 组件中使用内容的示例：
+
+```tsx {4,7} fileName="src/components/ClientComponentExample.tsx" codeFormat="typescript"
+"use client";
+
+import type { FC } from "react";
+import { useIntlayer } from "next-intlayer";
+
+export const ClientComponentExample: FC = () => {
+  const { myTranslatedContent } = useIntlayer("client-component"); // 创建相关内容声明
+
+  return (
+    <div>
+      <p>{myTranslatedContent}</p>
+    </div>
+  );
+};
+```
+
+```jsx {3,6} fileName="src/components/ClientComponentExample.mjx" codeFormat="esm"
+"use client";
+
+import { useIntlayer } from "next-intlayer";
+
+const ClientComponentExample = () => {
+  const { myTranslatedContent } = useIntlayer("client-component"); // 创建相关内容声明
+
+  return (
+    <div>
+      <p>{myTranslatedContent}</p>
+    </div>
+  );
+};
+```
+
+```jsx {3,6} fileName="src/components/ClientComponentExample.csx" codeFormat="commonjs"
+"use client";
+
+const { useIntlayer } = require("next-intlayer");
+
+const ClientComponentExample = () => {
+  const { myTranslatedContent } = useIntlayer("client-component"); // 创建相关内容声明
+
+  return (
+    <div>
+      <p>{myTranslatedContent}</p>
+    </div>
+  );
+};
+```
+
+## 掌握 Next.js 应用程序的国际化
+
+Intlayer 提供了许多功能来帮助您国际化您的 Next.js 应用程序。以下是一些关键功能：
+
+- **服务器组件的国际化**：Intlayer 允许您以与客户端组件相同的方式国际化服务器组件。这意味着您可以为客户端和服务器组件使用相同的内容声明。
+- **语言环境检测中间件**：Intlayer 提供了用于检测用户首选语言环境的中间件。此中间件用于检测用户的首选语言环境，并将其重定向到[配置](https://github.com/aymericzip/intlayer/blob/main/docs/zh/configuration.md)中指定的适当 URL。
+- **元数据的国际化**：Intlayer 提供了一种国际化元数据（例如页面标题）的方法，使用 Next.js 提供的 `generateMetadata` 函数。您可以使用 `getTranslation` 函数翻译元数据。
+- **sitemap.xml 和 robots.txt 的国际化**：Intlayer 允许您国际化 sitemap.xml 和 robots.txt 文件。您可以使用 `getMultilingualUrls` 函数生成多语言 URL 以供 sitemap 使用。
+- **URL 的国际化**：Intlayer 允许您通过使用 `getMultilingualUrls` 函数国际化 URL。此函数为您的 sitemap 生成多语言 URL。
+
+**要了解更多关于这些功能的信息，请参阅 [Next.js 国际化 (i18n) 与 Intlayer 和 Next.js 15 应用路由器](https://github.com/aymericzip/intlayer/blob/main/docs/zh/intlayer_with_nextjs_15.md) 指南。**
+
+## `next-intlayer` 包提供的功能
+
+`next-intlayer` 包还提供了一些功能来帮助您国际化您的应用程序。
+
+- [`t()`](https://github.com/aymericzip/intlayer/blob/main/docs/zh/packages/next-intlayer/t.md)
+- [`useIntlayer()`](https://github.com/aymericzip/intlayer/blob/main/docs/zh/packages/next-intlayer/useIntlayer.md)
+- [`useDictionary()`](https://github.com/aymericzip/intlayer/blob/main/docs/zh/packages/next-intlayer/useDictionary.md)
+- [`useLocale()`](https://github.com/aymericzip/intlayer/blob/main/docs/zh/packages/next-intlayer/useLocale.md)
+- [`useIntlayerAsync()`](https://github.com/aymericzip/intlayer/blob/main/docs/zh/packages/next-intlayer/useIntlayerAsync.md)

package/zh/packages/next-intlayer/t.md

@@ -0,0 +1,338 @@
+# 文档: `t` 函数在 `next-intlayer` 中的使用
+
+`next-intlayer` 包中的 `t` 函数是一个在 Next.js 应用中进行内联国际化的基本工具。它允许您直接在组件中定义翻译，从而根据当前语言环境轻松显示本地化内容。
+
+---
+
+## 概述
+
+`t` 函数用于在组件中直接为不同的语言环境提供翻译。通过传递一个包含每个支持语言环境翻译的对象，`t` 会根据 Next.js 应用中的当前语言环境上下文返回相应的翻译。
+
+---
+
+## 主要功能
+
+- **内联翻译**: 适用于不需要单独内容声明的快速内联文本。
+- **自动语言环境选择**: 自动返回与当前语言环境对应的翻译。
+- **TypeScript 支持**: 与 TypeScript 一起使用时提供类型安全和自动补全。
+- **易于集成**: 在 Next.js 的客户端和服务端组件中无缝工作。
+
+---
+
+## 函数签名
+
+```typescript
+t<T extends string>(content: Record<LocalesValues, T>, locale?: Locales): string
+```
+
+### 参数
+
+- `translations`: 一个对象，其中键是语言环境代码（例如 `en`、`fr`、`es`），值是相应的翻译字符串。
+
+### 返回值
+
+- 表示当前语言环境翻译内容的字符串。
+
+---
+
+## 使用示例
+
+### 在客户端组件中使用 `t`
+
+在客户端组件中使用 `t` 时，请确保在组件文件顶部包含 `'use client';` 指令。
+
+```tsx codeFormat="typescript"
+"use client";
+
+import type { FC } from "react";
+import { t } from "next-intlayer";
+
+export const ClientComponentExample: FC = () => (
+  <p>
+    {t({
+      en: "This is the content of a client component example",
+      fr: "Ceci est le contenu d'un exemple de composant client",
+      es: "Este es el contenido d un ejemplo de componente cliente",
+      zh: "这是客户端组件示例的内容",
+    })}
+  </p>
+);
+```
+
+```javascript codeFormat="esm"
+import { t } from "next-intlayer";
+
+const ClientComponentExample = () => (
+  <p>
+    {t({
+      en: "This is the content of a client component example",
+      fr: "Ceci est le contenu d'un exemple de composant client",
+      es: "Este es el contenido d un ejemplo de componente cliente",
+      zh: "这是客户端组件示例的内容",
+    })}
+  </p>
+);
+```
+
+```javascript codeFormat="commonjs"
+const { t } = require("next-intlayer");
+
+const ClientComponentExample = () => (
+  <p>
+    {t({
+      en: "This is the content of a client component example",
+      fr: "Ceci est le contenu d'un exemple de composant client",
+      es: "Este es el contenido d un ejemplo de componente cliente",
+      zh: "这是客户端组件示例的内容",
+    })}
+  </p>
+);
+```
+
+### 在服务端组件中使用 `t`
+
+```tsx codeFormat="typescript"
+import type { FC } from "react";
+import { t } from "next-intlayer/server";
+
+export const ServerComponentExample: FC = () => (
+  <p>
+    {t({
+      en: "This is the content of a server component example",
+      fr: "Ceci est le contenu d'un exemple de composant serveur",
+      es: "Este es el contenido de un ejemplo de componente servidor",
+      zh: "这是服务端组件示例的内容",
+    })}
+  </p>
+);
+```
+
+```javascript codeFormat="esm"
+import { t } from "next-intlayer/server";
+
+const ServerComponentExample = () => (
+  <p>
+    {t({
+      en: "This is the content of a server component example",
+      fr: "Ceci est le contenu d'un exemple de composant serveur",
+      es: "Este es el contenido de un ejemplo de componente servidor",
+      zh: "这是服务端组件示例的内容",
+    })}
+  </p>
+);
+```
+
+```javascript codeFormat="commonjs"
+const { t } = require("next-intlayer/server");
+
+const ServerComponentExample = () => (
+  <p>
+    {t({
+      en: "This is the content of a server component example",
+      fr: "Ceci est le contenu d'un exemple de composant serveur",
+      es: "Este es el contenido de un ejemplo de componente servidor",
+      zh: "这是服务端组件示例的内容",
+    })}
+  </p>
+);
+```
+
+### 在属性中使用内联翻译
+
+`t` 函数特别适用于 JSX 属性中的内联翻译。
+在本地化 `alt`、`title`、`href` 或 `aria-label` 等属性时，可以直接在属性中使用 `t`。
+
+```jsx
+<button
+  aria-label={t({
+    en: "Submit",
+    fr: "Soumettre",
+    es: "Enviar",
+    zh: "提交",
+  })}
+>
+  {t({
+    en: "Submit",
+    fr: "Soumettre",
+    es: "Enviar",
+    zh: "提交",
+  })}
+  <img
+    src="/path/to/image"
+    alt={t({
+      en: "A beautiful scenery",
+      fr: "Un beau paysage",
+      es: "Un hermoso paisaje",
+      zh: "一幅美丽的风景",
+    })}
+  />
+</button>
+```
+
+---
+
+## 高级主题
+
+### TypeScript 集成
+
+在与 TypeScript 一起使用时，`t` 函数是类型安全的，确保提供所有必需的语言环境。
+
+```typescript codeFormat="typescript"
+import type { IConfigLocales } from "intlayer";
+import { t } from "next-intlayer";
+
+const translations: IConfigLocales<string> = {
+  en: "Welcome",
+  fr: "Bienvenue",
+  es: "Bienvenido",
+  zh: "欢迎",
+};
+
+const greeting = t(translations);
+```
+
+```javascript codeFormat="esm"
+import type { IConfigLocales } from "intlayer";
+import { t } from "next-intlayer";
+
+/** @type {import('next-intlayer').IConfigLocales<string>} */
+const translations = {
+  en: "Welcome",
+  fr: "Bienvenue",
+  es: "Bienvenido",
+  zh: "欢迎",
+};
+
+const greeting = t(translations);
+```
+
+```javascript codeFormat="commonjs"
+const { t } = require("next-intlayer");
+
+/** @type {import('next-intlayer').IConfigLocales<string>} */
+const translations = {
+  en: "Welcome",
+  fr: "Bienvenue",
+  es: "Bienvenido",
+  zh: "欢迎",
+};
+
+const greeting = t(translations);
+```
+
+### 语言环境检测和上下文
+
+在 `next-intlayer` 中，当前语言环境通过上下文提供者管理：`IntlayerClientProvider` 和 `IntlayerServerProvider`。确保这些提供者包裹您的组件并正确传递 `locale` 属性。
+
+#### 示例:
+
+```tsx codeFormat="typescript"
+import type { FC } from "react";
+import type { Locales } from "intlayer";
+import { IntlayerClientProvider } from "next-intlayer";
+import { IntlayerServerProvider } from "next-intlayer/server";
+
+const Page: FC<{ locale: Locales }> = ({ locale }) => (
+  <IntlayerServerProvider locale={locale}>
+    <IntlayerClientProvider locale={locale}>
+      {/* 您的组件 */}
+    </IntlayerClientProvider>
+  </IntlayerServerProvider>
+);
+```
+
+```javascript codeFormat="esm"
+import { IntlayerClientProvider } from "next-intlayer";
+import { IntlayerServerProvider } from "next-intlayer/server";
+
+const Page = ({ locale }) => (
+  <IntlayerServerProvider locale={locale}>
+    <IntlayerClientProvider locale={locale}>
+      {/* 您的组件 */}
+    </IntlayerClientProvider>
+  </IntlayerServerProvider>
+);
+```
+
+```javascript codeFormat="commonjs"
+const { IntlayerClientProvider } = require("next-intlayer");
+const { IntlayerServerProvider } = require("next-intlayer/server");
+
+const Page = ({ locale }) => (
+  <IntlayerServerProvider locale={locale}>
+    <IntlayerClientProvider locale={locale}>
+      {/* 您的组件 */}
+    </IntlayerClientProvider>
+  </IntlayerServerProvider>
+);
+```
+
+---
+
+## 常见错误和故障排除
+
+### `t` 返回未定义或错误的翻译
+
+- **原因**: 当前语言环境未正确设置，或当前语言环境的翻译缺失。
+- **解决方案**:
+  - 验证 `IntlayerClientProvider` 或 `IntlayerServerProvider` 是否正确设置了适当的 `locale`。
+  - 确保您的翻译对象包含所有必要的语言环境。
+
+### TypeScript 中缺少翻译
+
+- **原因**: 翻译对象未满足所需的语言环境，导致 TypeScript 错误。
+- **解决方案**: 使用 `IConfigLocales` 类型来强制翻译的完整性。
+
+```typescript codeFormat="typescript"
+const translations: IConfigLocales<string> = {
+  en: "Text",
+  fr: "Texte",
+  // es: 'Texto', // 缺少 'es' 会导致 TypeScript 错误 [!code error]
+};
+
+const text = t(translations);
+```
+
+```javascript codeFormat="esm"
+const translations = {
+  en: "Text",
+  fr: "Texte",
+  // es: 'Texto', // 缺少 'es' 会导致 TypeScript 错误 [!code error]
+};
+
+const text = t(translations);
+```
+
+```javascript codeFormat="commonjs"
+const { t } = require("next-intlayer");
+
+/** @type {import('next-intlayer').IConfigLocales<string>} */
+const translations = {
+  en: "Text",
+  fr: "Texte",
+  // es: 'Texto', // 缺少 'es' 会导致 TypeScript 错误 [!code error]
+};
+
+const text = t(translations);
+```
+
+---
+
+## 有效使用的提示
+
+1. **使用 `t` 进行简单的内联翻译**: 适用于直接在组件中翻译小段文本。
+2. **优先使用 `useIntlayer` 处理结构化内容**: 对于更复杂的翻译和内容重用，请在声明文件中定义内容并使用 `useIntlayer`。
+3. **一致提供语言环境**: 确保通过适当的提供者在整个应用中一致提供语言环境。
+4. **利用 TypeScript**: 使用 TypeScript 类型捕获缺失的翻译并确保类型安全。
+
+---
+
+## 结论
+
+`next-intlayer` 中的 `t` 函数是管理 Next.js 应用中内联翻译的强大且方便的工具。通过有效集成它，您可以增强应用的国际化能力，为全球用户提供更好的体验。
+
+有关更详细的用法和高级功能，请参阅 [next-intlayer 文档](https://github.com/aymericzip/intlayer/blob/main/docs/zh/intlayer_visual_editor.md)。
+
+---
+
+**注意**: 请确保正确设置 `IntlayerClientProvider` 和 `IntlayerServerProvider`，以确保当前语言环境正确传递到您的组件中。这对于 `t` 函数返回正确的翻译至关重要。