@intlayer/docs 9.1.3 → 9.3.0

package/docs/zh/formatters.md

@@ -46,34 +46,6 @@ author: aymericzip
 
 Intlayer 提供了一组基于原生 `Intl` API 构建的轻量级辅助工具，以及一个缓存的 `Intl` 包装器，避免重复构建重量级的格式化器。这些工具完全支持本地化，可以直接从主 `intlayer` 包中使用。
 
-### 导入
-
-```ts
-import {
-  Intl,
-  number,
-  percentage,
-  currency,
-  date,
-  relativeTime,
-  units,
-  compact,
-  list,
-  getLocaleName,
-  getLocaleLang,
-  getLocaleFromPath,
-  getPathWithoutLocale,
-  getLocalizedUrl,
-  getHTMLTextDir,
-  getContent,
-  getTranslation,
-  getIntlayer,
-  getIntlayerAsync,
-} from "intlayer";
-```
-
-如果您使用 React，也可以使用 hooks；请参见 `react-intlayer/format`。
-
 ## 缓存的 Intl
 
 导出的 `Intl` 是对全局 `Intl` 的一个轻量级缓存包装器。它会缓存 `NumberFormat`、`DateTimeFormat`、`RelativeTimeFormat`、`ListFormat`、`DisplayNames`、`Collator` 和 `PluralRules` 的实例，从而避免重复构建相同的格式化器。
@@ -110,72 +82,8 @@ pluralRules.select(1); // "one"
 pluralRules.select(2); // "other"
 ```
 
-## 额外的 Intl 工具
-
-除了格式化辅助工具外，您还可以直接使用缓存的 Intl 包装器来使用其他 Intl 功能：
-
-### `Intl.DisplayNames`
-
-用于获取语言、地区、货币和书写系统的本地化名称：
-
-```ts
-import { Intl } from "intlayer";
-
-const languageNames = new Intl.DisplayNames("en", { type: "language" });
-languageNames.of("fr"); // "French"
-
-const regionNames = new Intl.DisplayNames("fr", { type: "region" });
-regionNames.of("US"); // "États-Unis"
-```
-
-### `Intl.Collator`
-
-用于基于区域设置的字符串比较和排序：
-
-```ts
-import { Intl } from "intlayer";
-
-const collator = new Intl.Collator("de", {
-  sensitivity: "base",
-  numeric: true,
-});
-
-const words = ["äpfel", "zebra", "100", "20"];
-words.sort(collator.compare); // ["20", "100", "äpfel", "zebra"]
-```
-
-### `Intl.PluralRules`
-
-用于确定不同区域设置中的复数形式：
-
-```ts
-import { Intl } from "intlayer";
-
-const pluralRules = new Intl.PluralRules("ar");
-pluralRules.select(0); // "zero"
-pluralRules.select(1); // "one"
-pluralRules.select(2); // "two"
-pluralRules.select(3); // "few"
-pluralRules.select(11); // "many"
-```
-
 ## 区域设置工具
 
-### `getLocaleName(displayLocale, targetLocale?)`
-
-获取某个区域设置在另一种区域设置中的本地化名称：
-
-```ts
-import { getLocaleName } from "intlayer";
-
-getLocaleName("fr", "en"); // "French"
-getLocaleName("en", "fr"); // "anglais"
-getLocaleName("de", "es"); // "alemán"
-```
-
-- **displayLocale**: 要获取名称的语言环境
-- **targetLocale**: 用于显示名称的语言环境（默认为 displayLocale）
-
 ### `getLocaleLang(locale?)`
 
 从语言环境字符串中提取语言代码：
@@ -206,22 +114,6 @@ getLocaleFromPath("https://example.com/es/about"); // "es"
 - **inputUrl**：要处理的完整 URL 字符串或路径名
 - **returns**：检测到的语言环境，如果未找到语言环境则返回默认语言环境
 
-### `getPathWithoutLocale(inputUrl, locales?)`
-
-从 URL 或路径名中移除语言环境段：
-
-```ts
-import { getPathWithoutLocale } from "intlayer";
-
-getPathWithoutLocale("/en/dashboard"); // "/dashboard"
-getPathWithoutLocale("/fr/dashboard"); // "/dashboard"
-getPathWithoutLocale("https://example.com/en/about"); // "https://example.com/about"
-```
-
-- **inputUrl**：要处理的完整 URL 字符串或路径名
-- **locales**：可选的支持语言数组（默认为配置的语言）
-- **returns**：去除语言段后的 URL
-
 ### `getLocalizedUrl(url, currentLocale, locales?, defaultLocale?, prefixDefault?)`
 
 为当前语言生成本地化 URL：
@@ -330,9 +222,11 @@ const content = await getIntlayerAsync("common", "fr");
 
 以下所有辅助函数均从 `intlayer` 导出。
 
-### `number(value, options?)`
+### `percentage(value, options?)`
+
+将数字格式化为百分比字符串。
 
-使用基于区域设置的分组和小数格式化数字值。
+行为：大于 1 的值被解释为完整的百分比并进行归一化（例如，`25` → `25%`，`0.25` → `25%`）。
 
 - **value**: `number | string`
 - **options**: `Intl.NumberFormatOptions & { locale?: LocalesValues }`
@@ -340,49 +234,121 @@ const content = await getIntlayerAsync("common", "fr");
 示例：
 
 ```ts
-import { number } from "intlayer";
+import { percentage } from "intlayer";
 
-number(123456.789); // "123,456.789"（在 en-US 中）
-number("1000000", { locale: "fr" }); // "1 000 000"
-number(1234.5, { minimumFractionDigits: 2 }); // "1,234.50"
+percentage(0.25); // "25%"
+percentage(25); // "25%"
+percentage(0.237, { minimumFractionDigits: 1 }); // "23.7%"
 ```
 
-### `percentage(value, options?)`
+### 格式化器函数
 
-将数字格式化为百分比字符串。
+#### `number(value, options?)`
 
-行为：大于 1 的值被解释为完整的百分比并进行归一化（例如，`25` → `25%`，`0.25` → `25%`）。
+使用locale感知的分组和小数格式化数值。
 
 - **value**: `number | string`
 - **options**: `Intl.NumberFormatOptions & { locale?: LocalesValues }`
 
-示例：
-
 ```ts
-import { percentage } from "intlayer";
+number(123456.789); // "123,456.789" (in en-US)
+number("1000000", { locale: "fr" }); // "1 000 000"
+number(1234.5, { minimumFractionDigits: 2 }); // "1,234.50"
+```
+
+#### `percentage(value, options?)`
+
+将数字格式化为百分比字符串。大于 1 的值会被规范化（例如，`25` → `25%`，`0.25` → `25%`）。
 
+- **value**: `number | string`
+- **options**: `Intl.NumberFormatOptions & { locale?: LocalesValues }`
+
+```ts
 percentage(0.25); // "25%"
 percentage(25); // "25%"
 percentage(0.237, { minimumFractionDigits: 1 }); // "23.7%"
 ```
 
-### `currency(value, options?)`
+#### `currency(value, options?)`
 
-将数值格式化为本地化货币。默认使用 `USD`，保留两位小数。
+将值格式化为本地化货币。默认为 `USD`。
 
 - **value**: `number | string`
 - **options**: `Intl.NumberFormatOptions & { locale?: LocalesValues }`
-  - 常用字段：`currency`（例如 `"EUR"`），`currencyDisplay`（`"symbol" | "code" | "name"`）
-
-示例：
+  - 常见: `currency`, `currencyDisplay` (`"symbol" | "code" | "name"`)
 
 ```ts
-import { currency } from "intlayer";
-
 currency(1234.5, { currency: "EUR" }); // "€1,234.50"
 currency("5000", { locale: "fr", currency: "CAD", currencyDisplay: "code" }); // "5 000,00 CAD"
 ```
 
+#### `date(date, optionsOrPreset?)`
+
+格式化日期/时间值。
+
+- **date**: `Date | string | number`
+- **optionsOrPreset**: `Intl.DateTimeFormatOptions & { locale?: LocalesValues }` 或预设: `"short" | "long" | "dateOnly" | "timeOnly" | "full"`
+
+```ts
+date(new Date(), "short"); // 例如 "08/02/25, 14:30"
+date("2025-08-02T14:30:00Z", { locale: "fr", month: "long", day: "numeric" }); // "2 août"
+```
+
+#### `relativeTime(from, to?, options?)`
+
+格式化两个时刻之间的相对时间。
+
+- **from**: `Date | string | number`
+- **to**: `Date | string | number` (默认值为 `new Date()`)
+- **options**: `{ locale?, unit?, numeric?, style? }`
+
+```ts
+const now = new Date();
+const in3Days = new Date(now.getTime() + 3 * 864e5);
+relativeTime(now, in3Days, { unit: "day" }); // "in 3 days"
+
+const twoHoursAgo = new Date(now.getTime() - 2 * 3600e3);
+relativeTime(now, twoHoursAgo, { unit: "hour", numeric: "auto" }); // "2 hours ago"
+```
+
+#### `units(value, options?)`
+
+使用单位格式化数值。
+
+- **value**: `number | string`
+- **options**: `Intl.NumberFormatOptions & { locale?: LocalesValues }`
+  - 常见: `unit` (例如, `"kilometer"`, `"byte"`), `unitDisplay` (`"short" | "narrow" | "long"`)
+
+```ts
+units(5, { unit: "kilometer", unitDisplay: "long", locale: "en-GB" }); // "5 kilometers"
+units(1024, { unit: "byte", unitDisplay: "narrow" }); // "1,024B"
+```
+
+#### `compact(value, options?)`
+
+使用紧凑记号法格式化数字。
+
+- **value**: `number | string`
+- **options**: `Intl.NumberFormatOptions & { locale?: LocalesValues }`
+
+```ts
+compact(1200); // "1.2K"
+compact("1000000", { locale: "fr", compactDisplay: "long" }); // "1 million"
+```
+
+#### `list(values, options?)`
+
+将数组格式化为本地化列表字符串。
+
+- **values**: `(string | number)[]`
+- **options**: `Intl.ListFormatOptions & { locale?: LocalesValues }`
+  - 常见: `type` (`"conjunction" | "disjunction" | "unit"`), `style` (`"long" | "short" | "narrow"`)
+
+```ts
+list(["apple", "banana", "orange"]); // "apple, banana, and orange"
+list(["red", "green", "blue"], { locale: "fr", type: "disjunction" }); // "rouge, vert ou bleu"
+```
+
 ## 缓存的 Intl
 
 从 `intlayer` 导出的 `Intl` 是围绕全局 `Intl` 的缓存包装器。它会缓存格式化程序实例（`NumberFormat`、`DateTimeFormat` 等），以避免重复构造它们，从而提高性能。
@@ -413,44 +379,68 @@ pluralRules.select(2); // "other"
 
 ### 额外的 Intl 功能
 
-### `date(date, optionsOrPreset?)`
+#### `Intl.DisplayNames`
 
-使用 `Intl.DateTimeFormat` 格式化日期/时间值。
+用于获取本地化的语言、地区、货币和脚本名称：
 
-- **date**: `Date | string | number`
-- **optionsOrPreset**: `Intl.DateTimeFormatOptions & { locale?: LocalesValues }` 或者以下预设之一：
-  - 预设值: `"short" | "long" | "dateOnly" | "timeOnly" | "full"`
+```ts
+import { Intl } from "intlayer";
 
-示例：
+const languageNames = new Intl.DisplayNames("en", { type: "language" });
+languageNames.of("fr"); // "French"
+
+const regionNames = new Intl.DisplayNames("fr", { type: "region" });
+regionNames.of("US"); // "États-Unis"
+```
+
+#### `Intl.Collator`
+
+用于区域感知的字符串比较和排序：
 
 ```ts
-import { date } from "intlayer";
+import { Intl } from "intlayer";
 
-date(new Date(), "short"); // 例如，"08/02/25, 14:30"
-date("2025-08-02T14:30:00Z", { locale: "fr", month: "long", day: "numeric" }); // "2 août"
+const collator = new Intl.Collator("de", {
+  sensitivity: "base",
+  numeric: true,
+});
+
+const words = ["äpfel", "zebra", "100", "20"];
+words.sort(collator.compare); // ["20", "100", "äpfel", "zebra"]
 ```
 
-### `relativeTime(from, to = new Date(), options?)`
+#### `Intl.PluralRules`
 
-使用 `Intl.RelativeTimeFormat` 格式化两个时间点之间的相对时间。
+用于在不同的 locales 中确定复数形式：
 
-- 传入 "now" 作为第一个参数，目标时间作为第二个参数，可以获得自然的表达方式。
-- **from**: `Date | string | number`
-- **to**: `Date | string | number`（默认为 `new Date()`）
-- **options**: `{ locale?: LocalesValues; unit?: Intl.RelativeTimeFormatUnit; numeric?: Intl.RelativeTimeFormatNumeric; style?: Intl.RelativeTimeFormatStyle }`
-  - 默认 `unit` 为 `"second"`。
+```ts
+import { Intl } from "intlayer";
+
+const pluralRules = new Intl.PluralRules("ar");
+pluralRules.select(0); // "zero"
+pluralRules.select(1); // "one"
+pluralRules.select(2); // "two"
+pluralRules.select(3); // "few"
+pluralRules.select(11); // "many"
+```
+
+## 语言环境工具函数
+
+### `date(date, optionsOrPreset?)`
+
+使用 `Intl.DateTimeFormat` 格式化日期/时间值。
+
+- **date**: `Date | string | number`
+- **optionsOrPreset**: `Intl.DateTimeFormatOptions & { locale?: LocalesValues }` 或者以下预设之一：
+  - 预设值: `"short" | "long" | "dateOnly" | "timeOnly" | "full"`
 
 示例：
 
 ```ts
-import { relativeTime } from "intlayer";
-
-const now = new Date();
-const in3Days = new Date(now.getTime() + 3 * 864e5);
-relativeTime(now, in3Days, { unit: "day" }); // "in 3 days"
+import { date } from "intlayer";
 
-const twoHoursAgo = new Date(now.getTime() - 2 * 3600e3);
-relativeTime(now, twoHoursAgo, { unit: "hour", numeric: "auto" }); // "2 hours ago"
+date(new Date(), "short"); // 例如，"08/02/25, 14:30"
+date("2025-08-02T14:30:00Z", { locale: "fr", month: "long", day: "numeric" }); // "2 août"
 ```
 
 ### `units(value, options?)`
@@ -471,8 +461,6 @@ units(5, { unit: "kilometer", unitDisplay: "long", locale: "en-GB" }); // "5 kil
 units(1024, { unit: "byte", unitDisplay: "narrow" }); // "1,024B"（依赖于区域设置）
 ```
 
-## 地区工具
-
 ### `compact(value, options?)`
 
 使用紧凑表示法格式化数字（例如，`1.2K`，`1M`）。
@@ -508,12 +496,6 @@ list(["red", "green", "blue"], { locale: "fr", type: "disjunction" }); // "rouge
 list([1, 2, 3], { type: "unit" }); // "1, 2, 3"
 ```
 
-## 说明
-
-- 所有辅助函数都接受 `string` 类型的输入；它们会在内部被强制转换为数字或日期。
-- 如果未提供，区域设置默认使用您配置的 `internationalization.defaultLocale`。
-- 这些工具是轻量封装；对于高级格式化，请直接传递标准的 `Intl` 选项。
-
 ### `getPathWithoutLocale(inputUrl, locales?)`
 
 从 URL 中移除语言区域段：
@@ -525,36 +507,6 @@ getPathWithoutLocale("/en/dashboard"); // "/dashboard"
 getPathWithoutLocale("/fr/dashboard"); // "/dashboard"
 ```
 
-## 入口点和重新导出（`@index.ts`）
-
-格式化函数位于核心包中，并从更高级的包中重新导出，以保持跨运行时的导入简洁：
-
-示例：
-
-```ts
-// 应用代码（推荐）
-import {
-  number,
-  currency,
-  date,
-  relativeTime,
-  units,
-  compact,
-  list,
-  Intl,
-  getLocaleName,
-  getLocaleLang,
-  getLocaleFromPath,
-  getPathWithoutLocale,
-  getLocalizedUrl,
-  getHTMLTextDir,
-  getContent,
-  getTranslation,
-  getIntlayer,
-  getIntlayerAsync,
-} from "intlayer";
-```
-
 ### `getHTMLTextDir(locale?)`
 
 返回一个 locale 的文本方向：

package/docs/zh/intlayer_CMS.md

@@ -244,12 +244,176 @@ bun x intlayer dictionary push -d my-first-dictionary-key --env production
 
 然后，您将能够在 [Intlayer CMS](https://app.intlayer.org/content) 中查看和管理您的字典。
 
+## 使用 `@intlayer/api` SDK 进行编程访问
+
+除了 CLI 和可视化编辑器，Intlayer 在 [`@intlayer/api`](https://www.npmjs.com/package/@intlayer/api) 包中提供了一个类型化的 SDK。它让你可以将 CMS 视为一个**无头内容数据库**：你可以直接从自己的应用程序、脚本或 CI 流水线中获取项目、获取字典，以及推送或更新它们。
+
+SDK 为你处理身份验证。只要你的 `clientId` 和 `clientSecret` 可用（在你的 Intlayer 配置或环境中），它就会自动获取和刷新 OAuth2 访问令牌，并对每个请求进行签名。
+
+### 安装
+
+```bash packageManager="npm"
+npm install @intlayer/api
+```
+
+```bash packageManager="yarn"
+yarn add @intlayer/api
+```
+
+```bash packageManager="pnpm"
+pnpm add @intlayer/api
+```
+
+```bash packageManager="bun"
+bun add @intlayer/api
+```
+
+### 工作原理：身份验证器 + 端点
+
+SDK 被拆分为**两个独立的导入**，目的是保持您的包体积小：
+
+1. `createIntlayerCMS` — 创建一个轻量级**身份验证器**。它只携带凭证和托管的访问令牌；对任何特定的域一无所知。
+2. `dictionaryEndpoint`、`projectEndpoint` 等 — 按域名的**端点绑定器**，每个都从自己的子路径导入（`@intlayer/api/dictionary`、`@intlayer/api/project` 等）。您将身份验证器传递给您需要的端点。
+
+因为每个端点都是单独导入的，您的包只包含您实际使用的域 — 导入 `dictionaryEndpoint` 永远不会拉入项目、AI 或任何其他域客户端。
+
+```typescript fileName="cms.ts" codeFormat="typescript"
+import { createIntlayerCMS } from "@intlayer/api";
+
+// 配置是可选的：当省略时，凭证从
+// `@intlayer/config/built` 读取，该配置解析 INTLAYER_CLIENT_ID 和
+// INTLAYER_CLIENT_SECRET 环境变量。
+export const cmsAuthenticator = createIntlayerCMS();
+```
+
+> [!WARNING]
+> CMS 凭证（`clientId` / `clientSecret`）授予您的内容**写入访问权限**。只在**服务器端**创建身份验证器（服务器操作、路由处理程序、脚本、CI）。永远不要将其导入客户端代码或向浏览器暴露您的凭证。
+
+如果您更倾向于不依赖构建时配置，请显式传递凭证：
+
+```typescript fileName="cms.ts" codeFormat="typescript"
+import { createIntlayerCMS } from "@intlayer/api";
+
+export const cmsAuthenticator = createIntlayerCMS({
+  editor: {
+    clientId: process.env.INTLAYER_CLIENT_ID,
+    clientSecret: process.env.INTLAYER_CLIENT_SECRET,
+    // 可选的，用于自托管后端：
+    // backendURL: process.env.INTLAYER_BACKEND_URL,
+  },
+});
+```
+
+> 通过在 [Intlayer 仪表板 - 项目](https://app.intlayer.org/projects)中创建新的访问密钥来获取您的凭证。
+
+### 获取项目
+
+```typescript fileName="projects.ts" codeFormat="typescript"
+import { createIntlayerCMS } from "@intlayer/api";
+import { projectEndpoint } from "@intlayer/api/project";
+
+const cmsAuthenticator = createIntlayerCMS();
+
+// 列出您的凭证可访问的项目
+const { data: projects } =
+  await projectEndpoint(cmsAuthenticator).getProjects();
+
+// 读取所选项目的聚合本地化见解
+const { data: insights } =
+  await projectEndpoint(cmsAuthenticator).getProjectInsights();
+```
+
+### 获取字典
+
+```typescript fileName="read-dictionaries.ts" codeFormat="typescript"
+import { createIntlayerCMS } from "@intlayer/api";
+import { dictionaryEndpoint } from "@intlayer/api/dictionary";
+
+const cmsAuthenticator = createIntlayerCMS();
+
+// 列出项目的所有远程字典
+const { data: dictionaries } =
+  await dictionaryEndpoint(cmsAuthenticator).getDictionaries();
+
+// 或按 key 获取单个字典
+const { data: dictionary } = await dictionaryEndpoint(
+  cmsAuthenticator
+).getDictionary("my-first-dictionary-key");
+```
+
+### 推送和更新字典
+
+使用 CMS 作为数据库来写回内容：
+
+```typescript fileName="write-dictionaries.ts" codeFormat="typescript"
+import { createIntlayerCMS } from "@intlayer/api";
+import { dictionaryEndpoint } from "@intlayer/api/dictionary";
+
+const cmsAuthenticator = createIntlayerCMS();
+
+// 创建一个新的字典
+await dictionaryEndpoint(cmsAuthenticator).addDictionary({
+  key: "my-first-dictionary-key",
+  content: { title: "Hello world" },
+});
+
+// 批量插入字典（在一次调用中创建或更新它们）
+await dictionaryEndpoint(cmsAuthenticator).pushDictionaries([
+  { key: "home", content: { title: "Home" } },
+  { key: "about", content: { title: "About" } },
+]);
+
+// 更新现有字典
+await dictionaryEndpoint(cmsAuthenticator).updateDictionary({
+  id: "<dictionary-id>",
+  key: "home",
+  content: { title: "Updated title" },
+});
+```
+
+> 提示：重复使用绑定的端点以避免重复代码：
+>
+> ```typescript codeFormat="typescript"
+> const dictionary = dictionaryEndpoint(cmsAuthenticator);
+> await dictionary.pushDictionaries([myDictionary]);
+> const { data } = await dictionary.getDictionaries();
+> ```
+
+### 提取单个方法
+
+每个端点方法都已经过身份验证且独立（它包含自己的令牌处理），因此您可以提取一个并将其传递——例如将其注入作为依赖项：
+
+```typescript fileName="push.ts" codeFormat="typescript"
+import { createIntlayerCMS } from "@intlayer/api";
+import { dictionaryEndpoint } from "@intlayer/api/dictionary";
+
+const dictionary = dictionaryEndpoint(createIntlayerCMS());
+
+// 已认证 — 每次调用时自动刷新令牌
+export const pushDictionaries = dictionary.pushDictionaries;
+
+// 使用示例
+await pushDictionaries([{ key: "home", content: { title: "Home" } }]);
+```
+
 ## 实时同步
 
 实时同步让您的应用在运行时反映 CMS 内容的更改。无需重新构建或重新部署。启用后，更新会被流式传输到实时同步服务器，刷新您的应用读取的字典。
 
 完整的设置指南（启用方式、启动 Live Sync 服务器、本地开发工作流程和限制条件）请参阅 [Live Sync 文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/live-sync.md)。
 
+## 自托管
+
+Intlayer 可以完全在您自己的基础设施上运行。一条命令可以使用 Docker Compose 启动完整的堆栈（仪表板、API、数据库、对象存储和电子邮件）：
+
+```sh
+curl -fsSL https://intlayer.org/install.sh | sh
+```
+
+有关完整的设置指南、环境变量参考、升级说明和备份/恢复过程，请参阅[自托管指南](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/self_hosting.md)。
+
+---
+
 ## 调试
 
 如果您遇到 CMS 的任何问题，请检查以下内容：