@intlayer/docs 5.5.8

package/zh/packages/intlayer/getConfiguration.md

@@ -0,0 +1,120 @@
+# 文档: `getConfiguration` 函数在 `intlayer` 中
+
+## 描述
+
+`getConfiguration` 函数通过提取环境变量来检索 `intlayer` 应用程序的完整配置。此函数提供了在客户端和服务器端使用相同配置的灵活性，从而确保整个应用程序的一致性。
+
+---
+
+## 参数
+
+该函数不接受任何参数。相反，它使用环境变量进行配置。
+
+### 返回值
+
+- **类型**: `IntlayerConfig`
+- **描述**: 包含 `intlayer` 完整配置的对象。配置包括以下部分：
+
+  - `internationalization`: 与语言环境和严格模式相关的设置。
+  - `middleware`: 与 URL 和 Cookie 管理相关的设置。
+  - `content`: 与内容文件、目录和模式相关的设置。
+  - `editor`: 编辑器特定的配置。
+
+详见 [Intlayer 配置文档](https://github.com/aymericzip/intlayer/blob/main/docs/zh/configuration.md) 获取更多详情。
+
+---
+
+## 示例用法
+
+### 检索完整配置
+
+```typescript codeFormat="typescript"
+import { getConfiguration } from "intlayer";
+
+const config = getConfiguration();
+console.log(config);
+// 输出:
+// {
+//   internationalization: { ... },
+//   middleware: { ... },
+//   content: { ... },
+//   editor: { ... }
+// }
+```
+
+```javascript codeFormat="esm"
+import { getConfiguration } from "intlayer";
+
+const config = getConfiguration();
+console.log(config);
+// 输出:
+// {
+//   internationalization: { ... },
+//   middleware: { ... },
+//   content: { ... },
+//   editor: { ... }
+// }
+```
+
+```javascript codeFormat="commonjs"
+const { getConfiguration } = require("intlayer");
+
+const config = getConfiguration();
+console.log(config);
+// 输出:
+// {
+//   internationalization: { ... },
+//   middleware: { ... },
+//   content: { ... },
+//   editor: { ... }
+// }
+```
+
+### 提取 `availableLocales` 和 `defaultLocale`
+
+配置的 `internationalization` 部分提供了与语言环境相关的设置，例如 `locales`（可用语言环境）和 `defaultLocale`（回退语言）。
+
+```typescript codeFormat="typescript"
+import { getConfiguration } from "intlayer";
+
+const { internationalization, middleware } = getConfiguration();
+const { locales: availableLocales, defaultLocale } = internationalization;
+const { cookieName } = middleware;
+
+console.log(availableLocales); // 输出示例: ["en", "fr", "es"]
+console.log(defaultLocale); // 输出示例: "en"
+console.log(cookieName); // 输出: "INTLAYER_LOCALE"
+```
+
+```javascript codeFormat="esm"
+import { getConfiguration } from "intlayer";
+
+const { internationalization, middleware } = getConfiguration();
+const { locales: availableLocales, defaultLocale } = internationalization;
+const { cookieName } = middleware;
+
+console.log(availableLocales); // 输出示例: ["en", "fr", "es"]
+console.log(defaultLocale); // 输出示例: "en"
+console.log(cookieName); // 输出: "INTLAYER_LOCALE"
+```
+
+```javascript codeFormat="commonjs"
+const { getConfiguration } = require("intlayer");
+
+const { internationalization, middleware } = getConfiguration();
+const { locales: availableLocales, defaultLocale } = internationalization;
+const { cookieName } = middleware;
+
+console.log(availableLocales); // 输出示例: ["en", "fr", "es"]
+console.log(defaultLocale); // 输出示例: "en"
+console.log(cookieName); // 输出: "INTLAYER_LOCALE"
+```
+
+## 注意事项
+
+- 在调用此函数之前，请确保所有必需的环境变量已正确设置。缺少变量将在初始化期间导致错误。
+- 此函数可用于客户端和服务器端，使其成为统一管理配置的多功能工具。
+
+## 应用中的使用
+
+`getConfiguration` 函数是初始化和管理 `intlayer` 应用程序配置的核心工具。通过提供对语言环境、中间件和内容目录等设置的访问，它确保了多语言和内容驱动应用程序的一致性和可扩展性。

package/zh/packages/intlayer/getEnumeration.md

@@ -0,0 +1,140 @@
+# 文档: `getEnumeration` 函数在 `intlayer` 中
+
+## 描述
+
+`getEnumeration` 函数根据枚举对象中的预定义条件检索与特定数量相对应的内容。条件被定义为键，其优先级由对象中的顺序决定。
+
+## 参数
+
+- `enumerationContent: QuantityContent<Content>`
+
+  - **描述**: 一个对象，其中键表示条件（例如，`<=`，`<`，`>=`，`=`），值表示相应的内容。键的顺序定义了它们的匹配优先级。
+  - **类型**: `QuantityContent<Content>`
+    - `Content` 可以是任何类型。
+
+- `quantity: number`
+
+  - **描述**: 用于与 `enumerationContent` 中的条件匹配的数值。
+  - **类型**: `number`
+
+## 返回值
+
+- **类型**: `Content`
+- **描述**: 与 `enumerationContent` 中第一个匹配条件相对应的内容。如果没有找到匹配项，则根据实现处理（例如，错误或回退内容）。
+
+## 示例用法
+
+### 基本用法
+
+```typescript codeFormat="typescript"
+import { getEnumeration } from "intlayer";
+
+const content = getEnumeration(
+  {
+    "<=-2.3": "您有小于 -2.3",
+    "<1": "您有小于一",
+    "2": "您有二",
+    ">=3": "您有三或更多",
+  },
+  2
+);
+
+console.log(content); // 输出: "您有二"
+```
+
+```javascript codeFormat="esm"
+import { getEnumeration } from "intlayer";
+
+const content = getEnumeration(
+  {
+    "<1": "您有小于一",
+    "2": "您有二",
+    ">=3": "您有三或更多",
+  },
+  2
+);
+
+console.log(content); // 输出: "您有二"
+```
+
+```javascript codeFormat="commonjs"
+const { getEnumeration } = require("intlayer");
+
+const content = getEnumeration(
+  {
+    "<1": "您有小于一",
+    "2": "您有二",
+    ">=3": "您有三或更多",
+  },
+  2
+);
+
+console.log(content); // 输出: "您有二"
+```
+
+### 条件优先级
+
+```typescript codeFormat="typescript"
+import { getEnumeration } from "intlayer";
+
+const content = getEnumeration(
+  {
+    "<4": "您有小于四",
+    "2": "您有二",
+  },
+  2
+);
+
+console.log(content); // 输出: "您有小于四"
+```
+
+```javascript codeFormat="esm"
+import { getEnumeration } from "intlayer";
+
+const content = getEnumeration(
+  {
+    "<4": "您有小于四",
+    "2": "您有二",
+  },
+  2
+);
+
+console.log(content); // 输出: "您有小于四"
+```
+
+```javascript codeFormat="commonjs"
+const { getEnumeration } = require("intlayer");
+
+const content = getEnumeration(
+  {
+    "<4": "您有小于四",
+    "2": "您有二",
+  },
+  2
+);
+
+console.log(content); // 输出: "您有小于四"
+```
+
+## 边界情况
+
+- **没有匹配条件:**
+
+  - 如果没有条件与提供的数量匹配，函数将返回 `undefined` 或明确处理默认/回退场景。
+
+- **条件重叠:**
+
+  - 如果条件重叠，则优先匹配第一个条件（基于对象顺序）。
+
+- **无效键:**
+
+  - 函数假定 `enumerationContent` 中的所有键都是有效的并且可解析为条件。无效或格式不正确的键可能导致意外行为。
+
+- **TypeScript 强制:**
+  - 函数确保 `Content` 类型在所有键中保持一致，从而在检索内容时提供类型安全性。
+
+## 注意事项
+
+- `findMatchingCondition` 工具用于根据给定数量确定适当的条件。
+
+https://github.com/aymericzip/intlayer/blob/main/docs/zh/**/*.md

package/zh/packages/intlayer/getHTMLTextDir.md

@@ -0,0 +1,97 @@
+# 文档: `getHTMLTextDir` 函数在 `intlayer` 中
+
+## 描述
+
+`getHTMLTextDir` 函数根据提供的语言环境确定文本方向（`ltr`、`rtl` 或 `auto`）。它旨在帮助开发人员设置 HTML 中的 `dir` 属性以实现正确的文本渲染。
+
+## 参数
+
+- `locale?: Locales`
+
+  - **描述**: 用于确定文本方向的语言环境字符串（例如，`Locales.ENGLISH`，`Locales.ARABIC`）。
+  - **类型**: `Locales`（可选）
+
+## 返回值
+
+- **类型**: `Dir` (`'ltr' | 'rtl' | 'auto'`)
+- **描述**: 对应于语言环境的文本方向：
+  - `'ltr'` 表示从左到右的语言。
+  - `'rtl'` 表示从右到左的语言。
+  - `'auto'` 如果语言环境无法识别。
+
+## 示例用法
+
+### 确定文本方向
+
+```typescript codeFormat="typescript"
+import { getHTMLTextDir } from "intlayer";
+
+getHTMLTextDir(Locales.ENGLISH); // 输出: "ltr"
+getHTMLTextDir(Locales.FRENCH); // 输出: "ltr"
+getHTMLTextDir(Locales.ARABIC); // 输出: "rtl"
+```
+
+```javascript codeFormat="esm"
+import { getHTMLTextDir } from "intlayer";
+
+getHTMLTextDir(Locales.ENGLISH); // 输出: "ltr"
+getHTMLTextDir(Locales.FRENCH); // 输出: "ltr"
+getHTMLTextDir(Locales.ARABIC); // 输出: "rtl"
+```
+
+```javascript codeFormat="commonjs"
+const { getHTMLTextDir } = require("intlayer");
+
+getHTMLTextDir(Locales.ENGLISH); // 输出: "ltr"
+getHTMLTextDir(Locales.FRENCH); // 输出: "ltr"
+getHTMLTextDir(Locales.ARABIC); // 输出: "rtl"
+```
+
+## 边界情况
+
+- **未提供语言环境:**
+
+  - 当 `locale` 为 `undefined` 时，函数返回 `'auto'`。
+
+- **无法识别的语言环境:**
+  - 对于无法识别的语言环境，函数默认为 `'auto'`。
+
+## 在组件中的使用:
+
+`getHTMLTextDir` 函数可用于根据语言环境动态设置 HTML 文档中的 `dir` 属性，以实现正确的文本渲染。
+
+```tsx codeFormat="typescript"
+import type { FC } from "react";
+import { getHTMLTextDir, type Locales } from "intlayer";
+
+export const HTMLLayout: FC<PropsWithChildren<{ locale: Locales }>> = ({
+  children,
+  locale,
+}) => (
+  <html dir={getHTMLTextDir(locale)} locale={locale}>
+    <body>{children}</body>
+  </html>
+);
+```
+
+```jsx codeFormat="esm"
+import { getHTMLTextDir } from "intlayer";
+
+const HTMLLayout = ({ children, locale }) => (
+  <html dir={getHTMLTextDir(locale)} locale={locale}>
+    <body>{children}</body>
+  </html>
+);
+```
+
+```jsx codeFormat="commonjs"
+const { getHTMLTextDir } = require("intlayer");
+
+const HTMLLayout = ({ children, locale }) => (
+  <html dir={getHTMLTextDir(locale)} locale={locale}>
+    <body>{children}</body>
+  </html>
+);
+```
+
+在上述示例中，`dir` 属性是根据语言环境动态设置的。

package/zh/packages/intlayer/getLocaleLang.md

@@ -0,0 +1,57 @@
+# 文档: `getLocaleLang` 函数在 `intlayer`
+
+## 描述
+
+`getLocaleLang` 函数从区域设置字符串中提取语言代码。它支持带有或不带国家代码的区域设置。如果未提供区域设置，它默认返回一个空字符串。
+
+## 参数
+
+- `locale?: Locales`
+
+  - **描述**: 从中提取语言代码的区域设置字符串（例如，`Locales.ENGLISH_UNITED_STATES`，`Locales.FRENCH_CANADA`）。
+  - **类型**: `Locales`（可选）
+
+## 返回值
+
+- **类型**: `string`
+- **描述**: 从区域设置中提取的语言代码。如果未提供区域设置，则返回空字符串 (`''`)。
+
+## 示例用法
+
+### 提取语言代码:
+
+```typescript codeFormat="typescript"
+import { getLocaleLang, Locales } from "intlayer";
+
+getLocaleLang(Locales.ENGLISH_UNITED_STATES); // 输出: "en"
+getLocaleLang(Locales.ENGLISH); // 输出: "en"
+getLocaleLang(Locales.FRENCH_CANADA); // 输出: "fr"
+getLocaleLang(Locales.FRENCH); // 输出: "fr"
+```
+
+```javascript codeFormat="esm"
+import { getLocaleLang } from "intlayer";
+
+getLocaleLang(Locales.ENGLISH_UNITED_STATES); // 输出: "en"
+getLocaleLang(Locales.ENGLISH); // 输出: "en"
+getLocaleLang(Locales.FRENCH_CANADA); // 输出: "fr"
+getLocaleLang(Locales.FRENCH); // 输出: "fr"
+```
+
+```javascript codeFormat="commonjs"
+const { getLocaleLang } = require("intlayer");
+
+getLocaleLang(Locales.ENGLISH_UNITED_STATES); // 输出: "en"
+getLocaleLang(Locales.ENGLISH); // 输出: "en"
+getLocaleLang(Locales.FRENCH_CANADA); // 输出: "fr"
+getLocaleLang(Locales.FRENCH); // 输出: "fr"
+```
+
+## 边界情况
+
+- **未提供区域设置:**
+
+  - 当 `locale` 为 `undefined` 时，该函数返回一个空字符串。
+
+- **格式错误的区域设置字符串:**
+  - 如果 `locale` 不遵循 `language-country` 格式（例如，`Locales.ENGLISH-US`），函数会安全地返回 `'-'` 之前的部分，或者如果没有 `'-'`，则返回整个字符串。

package/zh/packages/intlayer/getLocaleName.md

@@ -0,0 +1,93 @@
+# 文档: `getLocaleName` 函数在 `intlayer` 中
+
+## 描述
+
+`getLocaleName` 函数返回在显示语言环境 (`displayLocale`) 中给定语言环境 (`targetLocale`) 的本地化名称。如果未提供 `targetLocale`，则返回 `displayLocale` 在其自身语言中的名称。
+
+## 参数
+
+- `displayLocale: Locales`
+
+  - **描述**: 显示目标语言环境名称的语言环境。
+  - **类型**: 表示有效语言环境的枚举或字符串。
+
+- `targetLocale?: Locales`
+  - **描述**: 要本地化其名称的语言环境。
+  - **类型**: 可选。表示有效语言环境的枚举或字符串。
+
+## 返回值
+
+- **类型**: `string`
+- **描述**: 在 `displayLocale` 中本地化的 `targetLocale` 名称，或者如果未提供 `targetLocale`，则返回 `displayLocale` 的自身名称。如果未找到翻译，则返回 `"Unknown locale"`。
+
+## 示例用法
+
+```typescript codeFormat="typescript"
+import { Locales, getLocaleName } from "intlayer";
+
+getLocaleName(Locales.ENGLISH); // 输出: "English"
+getLocaleName(Locales.ENGLISH, Locales.FRENCH); // 输出: "Anglais"
+getLocaleName(Locales.ENGLISH, Locales.ESPANOL); // 输出: "Inglés"
+getLocaleName(Locales.ENGLISH, Locales.ENGLISH); // 输出: "English"
+
+getLocaleName(Locales.FRENCH); // 输出: "Français"
+getLocaleName(Locales.FRENCH, Locales.FRENCH); // 输出: "Français"
+getLocaleName(Locales.FRENCH, Locales.ESPANOL); // 输出: "Francés"
+getLocaleName(Locales.FRENCH, Locales.ENGLISH); // 输出: "French"
+
+getLocaleName(Locales.CHINESE); // 输出: "中文"
+getLocaleName(Locales.CHINESE, Locales.FRENCH); // 输出: "Chinois"
+getLocaleName(Locales.CHINESE, Locales.ESPANOL); // 输出: "Chino"
+getLocaleName(Locales.CHINESE, Locales.ENGLISH); // 输出: "Chinese"
+
+getLocaleName("unknown-locale"); // 输出: "Unknown locale"
+```
+
+```javascript codeFormat="esm"
+import { Locales, getLocaleName } from "intlayer";
+
+getLocaleName(Locales.ENGLISH); // 输出: "English"
+getLocaleName(Locales.ENGLISH, Locales.FRENCH); // 输出: "Anglais"
+getLocaleName(Locales.ENGLISH, Locales.ESPANOL); // 输出: "Inglés"
+getLocaleName(Locales.ENGLISH, Locales.ENGLISH); // 输出: "English"
+
+getLocaleName(Locales.FRENCH); // 输出: "Français"
+getLocaleName(Locales.FRENCH, Locales.FRENCH); // 输出: "Français"
+getLocaleName(Locales.FRENCH, Locales.ESPANOL); // 输出: "Francés"
+getLocaleName(Locales.FRENCH, Locales.ENGLISH); // 输出: "French"
+
+getLocaleName(Locales.CHINESE); // 输出: "中文"
+getLocaleName(Locales.CHINESE, Locales.FRENCH); // 输出: "Chinois"
+getLocaleName(Locales.CHINESE, Locales.ESPANOL); // 输出: "Chino"
+getLocaleName(Locales.CHINESE, Locales.ENGLISH); // 输出: "Chinese"
+
+getLocaleName("unknown-locale"); // 输出: "Unknown locale"
+```
+
+```javascript codeFormat="commonjs"
+const { Locales, getLocaleName } = require("intlayer");
+
+getLocaleName(Locales.ENGLISH); // 输出: "English"
+getLocaleName(Locales.ENGLISH, Locales.FRENCH); // 输出: "Anglais"
+getLocaleName(Locales.ENGLISH, Locales.ESPANOL); // 输出: "Inglés"
+getLocaleName(Locales.ENGLISH, Locales.ENGLISH); // 输出: "English"
+
+getLocaleName(Locales.FRENCH); // 输出: "Français"
+getLocaleName(Locales.FRENCH, Locales.FRENCH); // 输出: "Français"
+getLocaleName(Locales.FRENCH, Locales.ESPANOL); // 输出: "Francés"
+getLocaleName(Locales.FRENCH, Locales.ENGLISH); // 输出: "French"
+
+getLocaleName(Locales.CHINESE); // 输出: "中文"
+getLocaleName(Locales.CHINESE, Locales.FRENCH); // 输出: "Chinois"
+getLocaleName(Locales.CHINESE, Locales.ESPANOL); // 输出: "Chino"
+getLocaleName(Locales.CHINESE, Locales.ENGLISH); // 输出: "Chinese"
+
+getLocaleName("unknown-locale"); // 输出: "Unknown locale"
+```
+
+## 边界情况
+
+- **未提供 `targetLocale`:**
+  - 函数默认为返回 `displayLocale` 的自身名称。
+- **缺少翻译:**
+  - 如果 `localeNameTranslations` 不包含 `targetLocale` 或特定 `displayLocale` 的条目，函数将回退到 `ownLocalesName` 或返回 `"Unknown locale"`。