@intlayer/docs 7.2.2 → 7.3.0-canary.0

package/docs/zh/cli/push.md

@@ -0,0 +1,113 @@
+---
+createdAt: 2024-08-11
+updatedAt: 2025-11-22
+title: 推送词典
+description: 了解如何将您的词典推送到 Intlayer 编辑器和 CMS。
+keywords:
+  - 推送
+  - 词典
+  - CLI
+  - Intlayer
+  - 编辑器
+  - CMS
+slugs:
+  - doc
+  - concept
+  - cli
+  - push
+---
+
+# 推送词典
+
+```bash
+npx intlayer dictionary push
+```
+
+如果已安装 [intlayer 编辑器](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_visual_editor.md)，您也可以将词典推送到编辑器。此命令将使词典可用于[编辑器](https://intlayer.org/dashboard)。通过这种方式，您可以与团队共享词典，并在不修改应用代码的情况下编辑内容。
+
+## 别名：
+
+- `npx intlayer dictionaries push`
+- `npx intlayer dictionary push`
+- `npx intlayer dic push`
+
+## 参数：
+
+**词典选项：**
+
+- **`-d`，`--dictionaries`**：要推送的词典 ID。如果未指定，则会推送所有词典。
+
+  > 示例：`npx intlayer dictionary push -d my-dictionary-id my-other-dictionary-id`
+
+- **`--dictionary`**：要推送的词典 ID（`--dictionaries` 的别名）。
+
+  > 示例：`npx intlayer dictionary push --dictionary my-dictionary-id my-other-dictionary-id`
+
+**配置选项：**
+
+- **`--base-dir`**：指定项目的基础目录。命令会在该目录中查找 `intlayer.config.{ts,js,json,cjs,mjs}` 文件以获取 intlayer 配置。
+
+  > 示例：`npx intlayer dictionary push --env-file .env.production.local`
+
+- **`--no-cache`**：禁用缓存。
+
+  > 示例：`npx intlayer build --no-cache`
+
+**环境变量选项：**
+
+- **`--env`**：指定环境（例如，`development`，`production`）。当你在 intlayer 配置文件中使用环境变量时非常有用。
+- **`--env-file`**：提供自定义环境文件以加载变量。当你在 intlayer 配置文件中使用环境变量时非常有用。
+
+  > 示例：`npx intlayer dictionary push --env-file .env.production.local`
+
+  > 示例：`npx intlayer dictionary push --env production`
+
+**输出选项：**
+
+- **`-r`，`--delete-locale-dictionary`**：跳过推送字典后询问是否删除本地化目录的问题，并删除这些目录。默认情况下，如果字典在本地定义，它将覆盖远程字典内容。
+
+  > 示例：`npx intlayer dictionary push -r`
+
+  > 示例：`npx intlayer dictionary push --delete-locale-dictionary`
+
+- **`-k`，`--keep-locale-dictionary`**：跳过推送字典后询问是否删除本地化目录的问题，并保留这些目录。默认情况下，如果字典在本地定义，它将覆盖远程字典内容。
+
+  > 示例：`npx intlayer dictionary push -k`
+
+  > 示例：`npx intlayer dictionary push --keep-locale-dictionary`
+
+**准备选项：**
+
+- **`--build`**：在推送之前构建字典以确保内容是最新的。true 将强制构建，false 将跳过构建，undefined 将允许使用构建缓存。
+
+**日志选项：**
+
+- **`--verbose`**：启用详细日志以便调试。（CLI 默认启用）
+
+**Git 选项：**
+
+- **`--git-diff`**：仅针对包含从基准（默认 `origin/main`）到当前分支（默认 `HEAD`）的更改的字典运行。
+- **`--git-diff-base`**：指定 git diff 的基准引用（默认 `origin/main`）。
+- **`--git-diff-current`**：指定 git diff 的当前引用（默认 `HEAD`）。
+- **`--uncommitted`**：包含未提交的更改。
+- **`--unpushed`**：包含未推送的更改。
+- **`--untracked`**：包含未跟踪的文件。
+
+- **`--build`**：在推送之前构建字典以确保内容是最新的。设置为 true 将强制构建，false 将跳过构建，undefined 将允许使用构建缓存。
+
+**日志选项：**
+
+- **`--verbose`**：启用详细日志以便调试。（CLI 默认启用）
+
+**Git 选项：**
+
+- **`--git-diff`**：仅对包含从基准分支（默认 `origin/main`）到当前分支（默认 `HEAD`）的更改的字典运行。
+- **`--git-diff-base`**：指定 git diff 的基准引用（默认 `origin/main`）。
+- **`--git-diff-current`**：指定 git diff 的当前引用（默认 `HEAD`）。
+- **`--uncommitted`**：包含未提交的更改。
+- **`--unpushed`**：包含未推送的更改。
+- **`--untracked`**：包含未跟踪的文件。
+
+  > 示例：`npx intlayer dictionary push --git-diff --git-diff-base origin/main --git-diff-current HEAD`
+
+  > 示例：`npx intlayer dictionary push --uncommitted --unpushed --untracked`

package/docs/zh/cli/sdk.md

@@ -0,0 +1,67 @@
+---
+createdAt: 2024-08-11
+updatedAt: 2025-11-22
+title: CLI SDK
+description: 了解如何在您自己的代码中使用 Intlayer CLI SDK。
+keywords:
+  - SDK
+  - CLI
+  - Intlayer
+  - 编程式
+slugs:
+  - doc
+  - concept
+  - cli
+  - sdk
+---
+
+# CLI SDK
+
+CLI SDK 是一个库，允许您在自己的代码中使用 Intlayer CLI。
+
+```bash packageManager="npm"
+npm install @intlayer/cli --save-dev
+```
+
+```bash packageManager="yarn"
+yarn add @intlayer/cli --save-dev
+```
+
+```bash packageManager="pnpm"
+pnpm add @intlayer/cli --save-dev
+```
+
+使用示例：
+
+```ts
+import {
+  push,
+  pull,
+  fill,
+  build,
+  listContentDeclaration,
+  testMissingTranslations,
+  docTranslate,
+  docReview,
+  transform,
+} from "@intlayer/cli";
+
+push();
+// ...
+pull();
+// ...
+fill();
+// ...
+build();
+// ...
+listContentDeclaration();
+// ...
+testMissingTranslations();
+// ...
+docTranslate();
+// ...
+docReview();
+// ...
+transform();
+// ...
+```

package/docs/zh/cli/test.md

@@ -0,0 +1,76 @@
+---
+createdAt: 2024-08-11
+updatedAt: 2025-11-22
+title: 测试缺失的翻译
+description: 学习如何测试并识别字典中缺失的翻译。
+keywords:
+  - 测试
+  - 缺失的翻译
+  - CLI
+  - Intlayer
+slugs:
+  - doc
+  - concept
+  - cli
+  - test
+---
+
+# 测试缺失的翻译
+
+```bash
+npx intlayer content test
+```
+
+## 别名：
+
+- `npx intlayer test`
+
+此命令分析您的内容声明文件，以识别所有配置的语言环境中缺失的翻译。它提供一份全面的报告，显示哪些翻译键在哪些语言环境中缺失，帮助您维护多语言内容的一致性。
+
+## 示例输出：
+
+```bash
+pnpm intlayer content test
+Missing translations:
+ - home-page                      - tr         - src/components/HomePage/homePage.content.ts
+ - server-component               - es, tr     - src/components/ServerComponent/serverComponent.content.ts
+ - client-component               - pl, tr     - src/components/ClientComponent/clientComponent.content.ts
+Locales: en, ru, ja, fr, ko, zh, es, de, ar, it, en-GB, pt, hi, tr, pl
+Required locales: en
+Missing locales: pl, tr, es
+Missing required locales: -
+Total missing locales: 3
+Total missing required locales: 0
+```
+
+## 参数：
+
+**配置选项：**
+
+- **`--env`**：指定环境（例如，`development`，`production`）。
+- **`--env-file [envFile]`**：提供自定义环境文件以加载变量。
+- **`--base-dir`**：指定项目的基础目录。
+
+  > 示例：`npx intlayer content test --base-dir ./src --env-file .env.production.local`
+
+- **`--no-cache`**：禁用缓存。
+
+  > 示例：`npx intlayer build --no-cache`
+
+**准备选项：**
+
+- **`--build`**：在推送之前构建字典以确保内容是最新的。设置为 true 将强制构建，false 将跳过构建，undefined 将允许使用构建缓存。
+
+**日志选项：**
+
+- **`--verbose`**：启用详细日志以便调试。（CLI 默认启用）
+
+  > 示例：`npx intlayer content test --verbose`
+
+## 示例：
+
+```bash
+npx intlayer content test --verbose
+```
+
+输出帮助您快速识别需要完成的翻译，以确保您的应用程序在所有配置的语言环境中正常运行。

package/docs/zh/cli/transform.md

@@ -0,0 +1,65 @@
+---
+createdAt: 2024-08-11
+updatedAt: 2025-11-22
+title: 转换组件
+description: 学习如何转换现有组件以使用 Intlayer。
+keywords:
+  - 转换
+  - 组件
+  - 迁移
+  - CLI
+  - Intlayer
+slugs:
+  - doc
+  - concept
+  - cli
+  - transform
+---
+
+# 转换组件
+
+```bash
+npx intlayer transform
+```
+
+此命令分析您的代码文件，帮助迁移现有组件以使用 Intlayer。它支持交互式文件选择或特定文件定位。
+
+## 别名：
+
+- `npx intlayer trans`
+
+## 参数：
+
+**文件选择选项：**
+
+- **`-f, --file [files...]`**：要转换的特定文件列表。如果未提供，CLI 将扫描匹配的文件（`**/*.{tsx,jsx,vue,svelte,ts,js}`）并提示您选择要转换的文件。
+
+  > 示例：`npx intlayer transform -f src/components/MyComponent.tsx`
+
+**输出选项：**
+
+- **`-o, --output-content-declarations [outputContentDeclarations]`**：保存生成的内容声明文件的目录。
+
+  > 示例：`npx intlayer transform -o src/content`
+
+- **`--code-only`**：仅转换组件代码（不写入内容声明）。
+
+  > 示例：`npx intlayer transform --code-only`
+
+- **`--declaration-only`**：仅生成内容声明（不重写组件）。
+
+  > 示例：`npx intlayer transform --declaration-only`
+
+**配置选项：**
+
+- **`--base-dir`**：指定项目的基础目录。
+- **`--env`**：指定环境。
+- **`--env-file`**：提供自定义环境文件。
+- **`--verbose`**：启用详细日志记录。
+
+**必需的插件：**
+
+transform 命令在 TypeScript / JSX 文件上无需额外插件即可工作。但对于 Vue 和 Svelte 项目，需要安装以下插件：
+
+- **`@intlayer/vue-transformer`**：用于 Vue 文件。
+- **`@intlayer/svelte-transformer`**：用于 Svelte 文件。

package/docs/zh/cli/version.md

@@ -0,0 +1,24 @@
+---
+createdAt: 2024-08-11
+updatedAt: 2025-11-22
+title: 检查 CLI 版本
+description: 了解如何检查已安装的 Intlayer CLI 版本。
+keywords:
+  - 版本
+  - CLI
+  - Intlayer
+slugs:
+  - doc
+  - concept
+  - cli
+  - version
+---
+
+# 检查 CLI 版本
+
+```bash
+npx intlayer --version
+npx intlayer version
+```
+
+这两个命令都会打印已安装的 Intlayer CLI 版本。

package/docs/zh/cli/watch.md

@@ -0,0 +1,37 @@
+---
+createdAt: 2024-08-11
+updatedAt: 2025-11-22
+title: 监视字典
+description: 学习如何监视内容声明文件的更改并自动构建字典。
+keywords:
+  - 监视
+  - 字典
+  - CLI
+  - Intlayer
+slugs:
+  - doc
+  - concept
+  - cli
+  - watch
+---
+
+# 监视字典
+
+```bash
+npx intlayer watch
+```
+
+此命令将监视内容声明文件的更改，并在 `.intlayer` 目录中构建字典。
+此命令等同于 `npx intlayer build --watch --skip-prepare`。
+
+## 别名：
+
+- `npx intlayer dictionaries watch`
+- `npx intlayer dictionary watch`
+- `npx intlayer dic watch`
+
+## 参数：
+
+- **`--with`**：与监视命令并行启动其他命令。
+
+> 示例：`npx intlayer watch --with "next dev --turbopack"`

package/docs/zh/intlayer_with_svelte_kit.md

@@ -555,8 +555,9 @@ export const load: Load = ({ params }) => {
 	let { children, data }: { children: Snippet, data: LayoutData } = $props();
 
 	// 使用路由中的 locale 初始化 Intlayer
-	setupIntlayer(data.locale);
-
+  $effect(() => {
+      setupIntlayer(data.locale);
+  });
 	// 使用布局内容字典
 	const layoutContent = useIntlayer('layout');
 </script>

package/docs/zh/packages/intlayer/getPrefix.md

@@ -0,0 +1,213 @@
+---
+createdAt: 2025-11-16
+updatedAt: 2025-11-16
+title: getPrefix 函数文档 | intlayer
+description: 查看如何使用 intlayer 包中的 getPrefix 函数
+keywords:
+  - getPrefix
+  - prefix
+  - Intlayer
+  - intlayer
+  - 国际化
+  - 文档
+  - Next.js
+  - JavaScript
+  - React
+slugs:
+  - doc
+  - packages
+  - intlayer
+  - getPrefix
+history:
+  - version: 7.1.0
+    date: 2025-11-16
+    changes: 初始文档
+---
+
+# 文档：`intlayer` 中的 `getPrefix` 函数
+
+## 描述
+
+`getPrefix` 函数根据路由模式配置确定给定 locale 的 URL 前缀。它将 locale 与默认 locale 进行比较，并返回一个包含三种不同前缀格式的对象，以实现灵活的 URL 构建。
+
+**主要特性：**
+
+- 接受一个 locale 作为第一个参数（必需）
+- 可选的 `options` 对象，包含 `defaultLocale` 和 `mode`
+- 返回一个包含 `prefix` 和 `localePrefix` 属性的对象
+- 支持所有路由模式：`prefix-no-default`、`prefix-all`、`no-prefix` 和 `search-params`
+- 轻量级工具，用于确定何时添加 locale 前缀
+
+---
+
+## 函数签名
+
+```typescript
+getPrefix(
+  locale: Locales,               // 必需
+  options?: {                    // 可选
+    defaultLocale?: Locales;
+    mode?: 'prefix-no-default' | 'prefix-all' | 'no-prefix' | 'search-params';
+  }
+): GetPrefixResult
+
+type GetPrefixResult = {
+  prefix: string;   // 例如 'fr/' 或 ''
+  localePrefix?: Locale; // 例如 'fr' 或 undefined
+}
+```
+
+---
+
+## 参数
+
+- `locale: Locales`
+  - **描述**：用于生成前缀的语言环境。如果该值为假值（undefined、null、空字符串），函数将返回空字符串。
+  - **类型**：`Locales`
+  - **必需**：是
+
+- `options?: object`
+  - **描述**：用于确定前缀的配置对象。
+  - **类型**：`object`
+  - **必需**：否（可选）
+
+  - `options.defaultLocale?: Locales`
+    - **描述**：应用程序的默认语言环境。如果未提供，则使用项目配置中设置的默认语言环境。
+    - **类型**：`Locales`
+    - **默认值**：[`项目配置`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/configuration.md#middleware)
+
+  - `options.mode?: 'prefix-no-default' | 'prefix-all' | 'no-prefix' | 'search-params'`
+
+- **描述**：用于处理本地化的 URL 路由模式。如果未提供，则使用项目配置中设置的模式。
+- **类型**：`'prefix-no-default' | 'prefix-all' | 'no-prefix' | 'search-params'`
+- **默认值**：[项目配置](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/configuration.md#middleware)
+- **模式**：
+  - `prefix-no-default`：当 locale 与默认 locale 匹配时返回空字符串
+  - `prefix-all`：为所有 locale（包括默认）返回前缀
+  - `no-prefix`：返回空字符串（URL 中无前缀）
+  - `search-params`：返回空字符串（locale 作为查询参数）
+
+### 返回值
+
+- **类型**：`GetPrefixResult`
+- **描述**：包含三种不同前缀格式的对象：
+  - `prefix`：带有尾部斜杠的路径前缀（例如，`'fr/'`，`''`）
+  - `localePrefix`：不带斜杠的语言标识符（例如，`'fr'`，`undefined`）
+
+---
+
+## 示例用法
+
+### 基本用法
+
+```typescript codeFormat="typescript"
+import { getPrefix, Locales } from "intlayer";
+
+// 检查英语语言的前缀
+getPrefix(Locales.ENGLISH, {
+  defaultLocale: Locales.ENGLISH,
+  mode: "prefix-all",
+});
+// 返回: { prefix: 'en/', localePrefix: 'en' }
+
+// 检查法语语言的前缀
+getPrefix(Locales.FRENCH, {
+  defaultLocale: Locales.ENGLISH,
+  mode: "prefix-no-default",
+});
+// 返回: { prefix: 'fr/', localePrefix: 'fr' }
+```
+
+```javascript codeFormat="esm"
+import { getPrefix, Locales } from "intlayer";
+
+getPrefix(Locales.ENGLISH, { mode: "prefix-all" });
+javascript codeFormat="commonjs"
+const { getPrefix, Locales } = require("intlayer");
+
+getPrefix(Locales.ENGLISH, { mode: "prefix-all" });
+// 返回: { prefix: '', localePrefix: undefined }
+```
+
+### 不同的路由模式
+
+```typescript
+import { getPrefix, Locales } from "intlayer";
+
+// prefix-all: 总是返回前缀
+getPrefix(Locales.ENGLISH, {
+  mode: "prefix-all",
+  defaultLocale: Locales.ENGLISH,
+});
+// 返回: { prefix: '/en', localePrefix: 'en' }
+
+// prefix-no-default: 当语言环境与默认相同时不返回前缀
+getPrefix(Locales.ENGLISH, {
+  mode: "prefix-no-default",
+  defaultLocale: Locales.ENGLISH,
+});
+// 返回: { prefix: '', localePrefix: undefined }
+
+javascript;
+// prefix-no-default: 当语言环境与默认语言不同，返回前缀
+getPrefix(Locales.FRENCH, {
+  mode: "prefix-no-default",
+  defaultLocale: Locales.ENGLISH,
+});
+// 返回: { prefix: 'fr/', localePrefix: 'fr' }
+
+// no-prefix 和 search-params: 从不返回前缀
+getPrefix(Locales.ENGLISH, { mode: "no-prefix" });
+// 返回: { prefix: '', localePrefix: undefined }
+
+getPrefix(Locales.ENGLISH, { mode: "search-params" });
+// 返回: { prefix: '', localePrefix: undefined }
+```
+
+### 实际示例
+
+```typescript
+import { getPrefix, Locales } from "intlayer";
+
+// 为特定语言环境构建带有适当前缀的 URL
+const locale = Locales.FRENCH;
+const { prefix, localePrefix } = getPrefix(locale, {
+  defaultLocale: Locales.ENGLISH,
+  mode: "prefix-no-default",
+});
+
+typescript;
+// 使用 prefix 构建路径
+const url1 = `/${prefix}about`.replace(/\/+/g, "/");
+// 结果: "/fr/about"
+
+// 使用 localePrefix 进行语言标识
+console.log(`当前语言环境: ${localePrefix}`);
+// 输出: "当前语言环境: fr"
+```
+
+---
+
+## 相关函数
+
+- [`getLocalizedUrl`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/packages/intlayer/getLocalizedUrl.md): 为特定语言环境生成本地化 URL
+- [`getMultilingualUrls`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/packages/intlayer/getMultilingualUrls.md): 为所有配置的语言环境生成 URL
+
+---
+
+## TypeScript
+
+```typescript
+type GetPrefixResult = {
+  prefix: string; // 带有尾部斜杠的路径前缀（例如 'fr/' 或 ''）
+  localePrefix?: Locale; // 不带斜杠的语言标识符（例如 'fr' 或 undefined）
+};
+
+function getPrefix(
+  locale: Locales,
+  options?: {
+    defaultLocale?: Locales;
+    mode?: "prefix-no-default" | "prefix-all" | "no-prefix" | "search-params";
+  }
+): GetPrefixResult;
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intlayer/docs",
-  "version": "7.2.2",
+  "version": "7.3.0-canary.0",
   "private": false,
   "description": "Intlayer documentation",
   "keywords": [
@@ -72,13 +72,13 @@
     "watch": "webpack --config ./webpack.config.ts --watch"
   },
   "dependencies": {
-    "@intlayer/config": "7.2.2",
-    "@intlayer/core": "7.2.1",
-    "@intlayer/types": "7.2.2"
+    "@intlayer/config": "7.3.0-canary.0",
+    "@intlayer/core": "7.3.0-canary.0",
+    "@intlayer/types": "7.3.0-canary.0"
   },
   "devDependencies": {
-    "@intlayer/api": "7.2.2",
-    "@intlayer/cli": "7.2.2",
+    "@intlayer/api": "7.3.0-canary.0",
+    "@intlayer/cli": "7.3.0-canary.0",
     "@types/node": "24.10.1",
     "@utils/ts-config": "1.0.4",
     "@utils/ts-config-types": "1.0.4",
@@ -88,7 +88,7 @@
     "tsdown": "0.16.6",
     "tsx": "^4.20.6",
     "typescript": "5.9.3",
-    "vitest": "4.0.12"
+    "vitest": "4.0.13"
   },
   "engines": {
     "node": ">=14.18"

package/src/generated/blog.entry.ts

@@ -53,6 +53,25 @@ const readLocale = (
 };
 
 export const blogEntry = {
+  './blog/en/compiler_vs_declarative_i18n.md': {
+    en: readLocale('compiler_vs_declarative_i18n.md', 'en'),
+    ru: readLocale('compiler_vs_declarative_i18n.md', 'ru'),
+    ja: readLocale('compiler_vs_declarative_i18n.md', 'ja'),
+    fr: readLocale('compiler_vs_declarative_i18n.md', 'fr'),
+    ko: readLocale('compiler_vs_declarative_i18n.md', 'ko'),
+    zh: readLocale('compiler_vs_declarative_i18n.md', 'zh'),
+    es: readLocale('compiler_vs_declarative_i18n.md', 'es'),
+    de: readLocale('compiler_vs_declarative_i18n.md', 'de'),
+    ar: readLocale('compiler_vs_declarative_i18n.md', 'ar'),
+    it: readLocale('compiler_vs_declarative_i18n.md', 'it'),
+    'en-GB': readLocale('compiler_vs_declarative_i18n.md', 'en-GB'),
+    pt: readLocale('compiler_vs_declarative_i18n.md', 'pt'),
+    hi: readLocale('compiler_vs_declarative_i18n.md', 'hi'),
+    tr: readLocale('compiler_vs_declarative_i18n.md', 'tr'),
+    pl: readLocale('compiler_vs_declarative_i18n.md', 'pl'),
+    id: readLocale('compiler_vs_declarative_i18n.md', 'id'),
+    vi: readLocale('compiler_vs_declarative_i18n.md', 'vi'),
+  } as unknown as Record<LocalesValues, Promise<string>>,
   './blog/en/i18n_using_next-i18next.md': {
     en: readLocale('i18n_using_next-i18next.md', 'en'),
     ru: readLocale('i18n_using_next-i18next.md', 'ru'),