@intlayer/docs 5.5.8

package/zh/packages/intlayer/getTranslationContent.md

@@ -0,0 +1,166 @@
+# 文档: `getTranslation` 函数在 `intlayer`
+
+## 描述
+
+`getTranslation` 函数从一组可自定义的语言内容中检索与特定语言环境对应的内容。如果未找到指定的语言环境，它将默认返回项目中配置的默认语言环境的内容。
+
+## 参数
+
+- `languageContent: CustomizableLanguageContent<Content>`
+
+  - **描述**: 包含各种语言环境翻译的对象。每个键代表一个语言环境，其值为对应的内容。
+  - **类型**: `CustomizableLanguageContent<Content>`
+    - `Content` 可以是任何类型，默认为 `string`。
+
+- `locale: Locales`
+
+  - **描述**: 要检索内容的语言环境。
+  - **类型**: `Locales`
+
+## 返回值
+
+- **类型**: `Content`
+- **描述**: 与指定语言环境对应的内容。如果未找到语言环境，则返回默认语言环境的内容。
+
+## 示例用法
+
+### 基本用法
+
+```typescript codeFormat="typescript"
+import { getTranslation, Locales } from "intlayer";
+
+const content = getTranslation(
+  {
+    en: "Hello",
+    fr: "Bonjour",
+  },
+  Locales.ENGLISH
+);
+
+console.log(content); // 输出: "Bonjour"
+```
+
+```javascript codeFormat="esm"
+import { getTranslation, Locales } from "intlayer";
+
+const content = getTranslation(
+  {
+    en: "Hello",
+    fr: "Bonjour",
+  },
+  Locales.ENGLISH
+);
+
+console.log(content); // 输出: "Bonjour"
+```
+
+```javascript codeFormat="commonjs"
+const { getTranslation, Locales } = require("intlayer");
+
+const content = getTranslation(
+  {
+    en: "Hello",
+    fr: "Bonjour",
+  },
+  Locales.ENGLISH
+);
+
+console.log(content); // 输出: "Bonjour"
+```
+
+### 缺失语言环境:
+
+```typescript codeFormat="typescript"
+import { getTranslation, Locales } from "intlayer";
+
+const content = getTranslation(
+  {
+    en: "Hello",
+    fr: "Bonjour",
+  },
+  Locales.SPANISH
+);
+
+console.log(content); // 输出: "Hello" (默认语言环境内容)
+```
+
+```javascript codeFormat="esm"
+import { getTranslation, Locales } from "intlayer";
+
+const content = getTranslation(
+  {
+    en: "Hello",
+    fr: "Bonjour",
+  },
+  Locales.SPANISH
+);
+
+console.log(content); // 输出: "Hello" (默认语言环境内容)
+```
+
+```javascript codeFormat="commonjs"
+const { getTranslation, Locales } = require("intlayer");
+
+const content = getTranslation(
+  {
+    en: "Hello",
+    fr: "Bonjour",
+  },
+  Locales.SPANISH
+);
+
+console.log(content); // 输出: "Hello" (默认语言环境内容)
+```
+
+### 使用自定义内容类型:
+
+```typescript codeFormat="typescript"
+import { getTranslation, Locales } from "intlayer";
+
+const customContent = getTranslation<Record<string, string>>(
+  {
+    en: { greeting: "Hello" },
+    fr: { greeting: "Bonjour" },
+  },
+  Locales.FRENCH
+);
+
+console.log(customContent.greeting); // 输出: "Bonjour"
+```
+
+```javascript codeFormat="esm"
+import { getTranslation, Locales } from "intlayer";
+
+const customContent = getTranslation<Record<string, string>>(
+  {
+    en: { greeting: "Hello" },
+    fr: { greeting: "Bonjour" },
+  },
+  Locales.FRENCH
+);
+
+console.log(customContent.greeting); // 输出: "Bonjour"
+```
+
+```javascript codeFormat="commonjs"
+const { getTranslation, Locales } = require("intlayer");
+
+const customContent = getTranslation<Record<string, string>>(
+  {
+    en: { greeting: "Hello" },
+    fr: { greeting: "Bonjour" },
+  },
+  Locales.FRENCH
+);
+
+console.log(customContent.greeting); // 输出: "Bonjour"
+```
+
+## 边界情况
+
+- **未找到语言环境:**
+  - 当 `locale` 在 `languageContent` 中未找到时，函数返回默认语言环境的内容。
+- **不完整的语言内容:**
+  - 如果语言环境部分定义，函数不会合并内容。它严格检索指定语言环境的值或回退到默认值。
+- **TypeScript 强制执行:**
+  - 如果 `languageContent` 中的语言环境与项目配置不匹配，TypeScript 将强制要求定义所有必需的语言环境，确保内容完整且类型安全。

package/zh/packages/intlayer/index.md

@@ -0,0 +1,360 @@
+# intlayer: 管理多语言词典的NPM包 (i18n)
+
+**Intlayer** 是专为JavaScript开发者设计的一套工具包。它兼容React、Next.js和Express.js等框架。
+
+**`intlayer`包** 允许您在代码中的任何地方声明内容。它将多语言内容声明转换为结构化词典，能够无缝集成到您的应用程序中。通过TypeScript，**Intlayer** 提供更强大、更高效的开发工具。
+
+## 为什么要集成Intlayer？
+
+- **基于JavaScript的内容管理**：利用JavaScript的灵活性高效地定义和管理内容。
+- **类型安全的环境**：利用TypeScript确保所有内容定义的精确性和无错误。
+- **集成的内容文件**：将翻译与其相关组件保持紧密联系，提高可维护性和清晰度。
+
+## 安装
+
+使用您喜欢的包管理器安装必要的包：
+
+```bash packageManager="npm"
+npm install intlayer
+```
+
+```bash packageManager="pnpm"
+pnpm add intlayer
+```
+
+```bash packageManager="yarn"
+yarn add intlayer
+```
+
+### 配置Intlayer
+
+Intlayer提供了一个配置文件来设置您的项目。将此文件放置在项目的根目录中。
+
+```typescript fileName="intlayer.config.ts" codeFormat="typescript"
+// 配置文件示例
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: Locales.ENGLISH,
+  },
+};
+
+export default config;
+```
+
+```javascript fileName="intlayer.config.mjs" codeFormat="esm"
+// 配置文件示例
+import { Locales } from "intlayer";
+
+/** @type {import('intlayer').IntlayerConfig} */
+const config = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: Locales.ENGLISH,
+  },
+};
+
+export default config;
+```
+
+```javascript fileName="intlayer.config.cjs" codeFormat="commonjs"
+// 配置文件示例
+const { Locales } = require("intlayer");
+
+/** @type {import('intlayer').IntlayerConfig} */
+const config = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: Locales.ENGLISH,
+  },
+};
+
+module.exports = config;
+```
+
+> 有关可用参数的完整列表，请参阅[配置文档](https://github.com/aymericzip/intlayer/blob/main/docs/zh/configuration.md)。
+
+## 使用示例
+
+通过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
+    ├── ClientComponent
+    │   ├── index.content.ts
+    │   └── index.tsx
+    └── ServerComponent
+        ├── index.content.ts
+        └── index.tsx
+```
+
+```bash codeFormat="esm"
+.
+├── intlayer.config.mjs
+└── src
+    ├── ClientComponent
+    │   ├── index.content.mjs
+    │   └── index.mjx
+    └── ServerComponent
+        ├── index.content.mjs
+        └── index.mjx
+```
+
+```bash codeFormat="commonjs"
+.
+├── intlayer.config.cjs
+└── src
+    ├── ClientComponent
+    │   ├── index.content.cjs
+    │   └── index.cjx
+    └── ServerComponent
+        ├── index.content.cjs
+        └── index.cjx
+```
+
+### 声明您的内容
+
+以下是内容声明的示例：
+
+```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": "很多车"
+      }
+    }
+  }
+}
+```
+
+### 构建您的词典
+
+您可以使用[intlayer-cli](https://github.com/aymericzip/intlayer/blob/main/packages/intlayer-cli/readme.md)构建词典。
+
+```bash packageManager="npm"
+npx intlayer dictionaries build
+```
+
+```bash packageManager="yarn"
+yarn intlayer build
+```
+
+```bash packageManager="pnpm"
+pnpm intlayer build
+```
+
+此命令扫描所有`*.content.*`文件，编译它们，并将结果写入**`intlayer.config.ts`**中指定的目录（默认是`./.intlayer`）。
+
+典型输出可能如下所示：
+
+```bash
+.
+└── .intlayer
+    ├── dictionary  # 包含内容的词典
+    │   ├── client-component.json
+    │   └── server-component.json
+    ├── main  # 包含应用程序中使用的词典入口点
+    │   ├── dictionary.cjs
+    │   └── dictionary.mjs
+    └── types  # 包含词典的自动生成类型定义
+        ├── intlayer.d.ts  # 包含Intlayer的自动生成类型定义
+        ├── client-component.d.ts
+        └── server-component.d.ts
+```
+
+### 构建i18next资源
+
+Intlayer可以配置为为[i18next](https://www.i18next.com/)构建词典。为此，您需要在`intlayer.config.ts`文件中添加以下配置：
+
+```typescript fileName="intlayer.config.ts" codeFormat="typescript"
+// 配置文件示例
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  /* ... */
+  content: {
+    // 告诉Intlayer生成i18next的消息文件
+    dictionaryOutput: ["i18next"],
+
+    // Intlayer将写入消息JSON文件的目录
+    i18nextResourcesDir: "./i18next/resources",
+  },
+};
+```
+
+```typescript fileName="intlayer.config.mjs" codeFormat="esm"
+// 配置文件示例
+import { Locales } from "intlayer";
+
+/** @type {import('intlayer').IntlayerConfig} */
+const config = {
+  /* ... */
+  content: {
+    // 告诉Intlayer生成i18next的消息文件
+    dictionaryOutput: ["i18next"],
+
+    // Intlayer将写入消息JSON文件的目录
+    i18nextResourcesDir: "./i18next/resources",
+  },
+};
+
+export default config;
+```
+
+```javascript fileName="intlayer.config.cjs" codeFormat="commonjs"
+// 配置文件示例
+const { Locales } = require("intlayer");
+
+/** @type {import('intlayer').IntlayerConfig} */
+const config = {
+  /* ... */
+  content: {
+    // 告诉Intlayer生成i18next的消息文件
+    dictionaryOutput: ["i18next"],
+
+    // Intlayer将写入消息JSON文件的目录
+    i18nextResourcesDir: "./i18next/resources",
+  },
+};
+
+module.exports = config;
+```
+
+> 有关可用参数的完整列表，请参阅[配置文档](https://github.com/aymericzip/intlayer/blob/main/docs/zh/configuration.md)。
+
+输出：
+
+```bash
+.
+└── i18next
+    └── resources
+        ├── en
+        │   ├── client-component.json
+        │   └── server-component.json
+        ├── es
+        │   ├── client-component.json
+        │   └── server-component.json
+        └── fr
+            ├── client-component.json
+            └── server-component.json
+```
+
+例如，**en/client-component.json**可能如下所示：
+
+```json fileName="intlayer/dictionary/en/client-component.json"
+{
+  "myTranslatedContent": "Hello World",
+  "zero_numberOfCar": "No cars",
+  "one_numberOfCar": "One car",
+  "two_numberOfCar": "Two cars",
+  "other_numberOfCar": "Some cars"
+}
+```

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

@@ -0,0 +1,41 @@
+# intlayer-cli: 用于 Intlayer CLI 的 NPM 包
+
+**Intlayer** 是专为 JavaScript 开发人员设计的一套工具包。它兼容如 React、React 和 Express.js 等框架。
+
+**`intlayer-cli`** 包是一个 NPM 包，它使用 `@intlayer/cli` 包并将其提供给 `intlayer` 命令行接口。
+
+> 请注意，如果已安装 [`intlayer`](https://github.com/aymericzip/intlayer/tree/main/docs/zh/packages/intlayer/index.md) 包，则不需要此包。与 `intlayer` 包相比，`intlayer-cli` 包是一个更轻量的包，仅包含 CLI 工具，而没有 `@intlayer/core` 依赖项。
+
+## 安装
+
+使用您喜欢的包管理器安装必要的包：
+
+```bash packageManager="npm"
+npm install intlayer-cli -g
+```
+
+```bash packageManager="pnpm"
+pnpm add intlayer-cli -g
+```
+
+```bash packageManager="yarn"
+yarn add intlayer-cli -g
+```
+
+## 使用方法
+
+以下是如何使用 `intlayer-cli` 包的示例：
+
+```bash
+npx intlayer dictionaries build
+```
+
+## CLI 命令
+
+Intlayer 提供了一个 CLI 工具来：
+
+- 审核您的内容声明并完成缺失的翻译
+- 从您的内容声明中构建字典
+- 从您的 CMS 推送和拉取远程字典到您的本地项目
+
+请查阅 [intlayer-cli](https://github.com/aymericzip/intlayer/blob/main/docs/zh/intlayer_cli.md) 了解更多信息。

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

@@ -0,0 +1,113 @@
+# intlayer-editor: 用于 Intlayer 可视化编辑器的 NPM 包
+
+**Intlayer** 是专为 JavaScript 开发人员设计的一套软件包。它兼容 React、React 和 Express.js 等框架。
+
+**`intlayer-editor`** 包是一个 NPM 包，可将 Intlayer 可视化编辑器集成到您的 React 项目中。
+
+## Intlayer 编辑器如何工作
+
+Intlayer 编辑器允许与 Intlayer 远程字典交互。它可以安装在客户端，将您的应用程序转变为类似 CMS 的编辑器，以管理您网站的所有配置语言的内容。
+
+![Intlayer 编辑器界面](https://github.com/aymericzip/intlayer/blob/main/docs/assets/intlayer_editor_ui.png)
+
+## 安装
+
+使用您喜欢的包管理器安装必要的包：
+
+```bash packageManager="npm"
+npm install intlayer-editor
+```
+
+```bash packageManager="pnpm"
+pnpm add intlayer-editor
+```
+
+```bash packageManager="yarn"
+yarn add intlayer-editor
+```
+
+### 配置
+
+在您的 Intlayer 配置文件中，您可以自定义编辑器设置：
+
+```typescript
+const config: IntlayerConfig = {
+  // ... 其他配置设置
+  editor: {
+    enabled: process.env.INTLAYER_ENABLED === "true", // 如果为 false，编辑器将处于非活动状态且无法访问。
+    // 客户端 ID 和客户端密钥是启用编辑器所必需的。
+    // 它们允许识别正在编辑内容的用户。
+    // 它们可以通过在 Intlayer 仪表板 - 项目 (https://intlayer.org/dashboard/projects) 中创建新客户端来获取。
+    clientId: process.env.INTLAYER_CLIENT_ID,
+    clientSecret: process.env.INTLAYER_CLIENT_SECRET,
+  },
+};
+```
+
+> 如果您没有客户端 ID 和客户端密钥，可以通过在 [Intlayer 仪表板 - 项目](https://intlayer.org/dashboard/projects) 中创建新客户端来获取。
+
+> 要查看所有可用参数，请参阅[配置文档](https://github.com/aymericzip/intlayer/blob/main/docs/zh/configuration.md)
+
+`intlayer-editor` 包基于 Intlayer，可用于 JavaScript 应用程序，例如 React (Create React App)、Vite + React 和 Next.js。
+
+有关如何安装该包的更多详细信息，请参阅以下相关部分：
+
+### 与 Next.js 集成
+
+有关与 Next.js 集成的内容，请参阅[设置指南](https://github.com/aymericzip/intlayer/blob/main/docs/zh/intlayer_with_nextjs_15.md)。
+
+### 与 Create React App 集成
+
+有关与 Create React App 集成的内容，请参阅[设置指南](https://github.com/aymericzip/intlayer/blob/main/docs/zh/intlayer_with_create_react_app.md)
+
+### 与 Vite + React 集成
+
+有关与 Vite + React 集成的内容，请参阅[设置指南](https://github.com/aymericzip/intlayer/blob/main/docs/zh/intlayer_with_vite+react.md)
+
+### 集成示例
+
+要将 Intlayer 可视化编辑器集成到您的 React 项目中，请按照以下步骤操作：
+
+- 将 Intlayer 编辑器组件导入到您的 React 应用程序中：
+
+  ```tsx fileName="src/App.jsx"
+  import { IntlayerEditorProvider } from "intlayer-editor";
+  import { IntlayerProvider } from "react-intlayer";
+
+  export default function App() {
+    return (
+      <IntlayerProvider>
+        <IntlayerEditorProvider>
+          <IntlayerEditor>{/* 在此处放置您的应用内容 */}</IntlayerEditor>
+        </IntlayerEditorProvider>
+      </IntlayerProvider>
+    );
+  }
+  ```
+
+- 将 Intlayer 编辑器样式导入到您的 Next.js 应用程序中：
+
+  ```tsx fileName="src/app/[locale]/layout.jsx"
+  import { IntlayerEditorStyles } from "intlayer-editor";
+
+  export default async function RootLayout({ children, params }) {
+    const { locale } = await params;
+    return (
+      <IntlayerClientProvider locale={locale}>
+        <IntlayerEditorProvider>
+          <html lang={locale}>
+            <body className={IntlayerEditorStyles}>{children}</body>
+          </html>
+        </IntlayerEditorProvider>
+      </IntlayerClientProvider>
+    );
+  }
+  ```
+
+## 使用编辑器
+
+当编辑器安装、启用并启动后，您可以通过将光标悬停在内容上查看由 Intlayer 索引的每个字段。
+
+![悬停在内容上](https://github.com/aymericzip/intlayer/blob/main/docs/assets/intlayer_editor_hover_content.png)
+
+如果您的内容被框选，您可以长按它以显示编辑抽屉。