@intlayer/docs 9.0.0-canary.3 → 9.0.0-canary.5

package/docs/zh/dictionary/insertion.md

@@ -152,70 +152,6 @@ export default InsertionComponent;
 
 ## 附加资源
 
-有关配置和使用的更详细信息，请参阅以下资源：
-
-- [Intlayer CLI 文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/cli/index.md)
-  const { useIntlayer } = require("react-intlayer");
-
-const InsertionComponent = () => {
-const { myInsertion } = useIntlayer("my_key");
-
-return (
-
-<div>
-<p>
-{
-/_ 输出: "Hello, my name is John and I am 30 years old!" _/
-myInsertion({ name: "John", age: "30" })
-}
-</p>
-<p>
-{
-/_ 你可以使用不同的值重复使用相同的插入 _/
-myInsertion({ name: "Alice", age: "25" })
-}
-</p>
-</div>
-);
-};
-
-module.exports = InsertionComponent;
-
-```
-
-## 附加资源
-
-有关配置和使用的更详细信息，请参阅以下资源：
-
-- [Intlayer CLI 文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/cli/index.md)
-const { useIntlayer } = require("react-intlayer");
-
-const InsertionComponent = () => {
-  const { myInsertion } = useIntlayer("my_key");
-
-  return (
-    <div>
-      <p>
-        {
-          /* 输出: "Hello, my name is John and I am 30 years old!" */
-          myInsertion({ name: "John", age: "30" })
-        }
-      </p>
-      <p>
-        {
-          /* 你可以使用不同的值重复使用相同的插入 */
-          myInsertion({ name: "Alice", age: "25" })
-        }
-      </p>
-    </div>
-  );
-};
-
-module.exports = InsertionComponent;
-```
-
-## 附加资源
-
 有关配置和使用的更详细信息，请参考以下资源：
 
 - [Intlayer CLI 文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/cli/index.md)

package/docs/zh/dictionary/nesting.md

@@ -27,6 +27,45 @@ author: aymericzip
 
 ## 设置嵌套
 
+要在你的 Intlayer 项目中设置嵌套，你首先定义你希望重用的基础内容。然后，在一个单独的内容模块中，你使用 `nest` 函数来导入该内容。
+
+### 基础字典
+
+下面是一个基础字典的示例，用于嵌套在另一个字典中：
+
+```typescript fileName="firstDictionary.content.ts" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+import { type Dictionary } from "intlayer";
+
+const firstDictionary = {
+  key: "key_of_my_first_dictionary",
+  content: {
+    content: "content",
+    subContent: {
+      contentNumber: 0,
+      contentString: "string",
+    },
+  },
+} satisfies Dictionary;
+
+export default firstDictionary;
+```
+
+```json fileName="firstDictionary.content.json" contentDeclarationFormat="json"
+{
+  "$schema": "https://intlayer.org/schema.json",
+  "key": "key_of_my_first_dictionary",
+  "content": {
+    "content": "content",
+    "subContent": {
+      "contentNumber": 0,
+      "contentString": "string"
+    }
+  }
+}
+```
+
+## 设置嵌套
+
 <Tabs group="framework">
   <Tab label="React" value="react">
 

package/docs/zh/dictionary/translation.md

@@ -259,87 +259,3 @@ document.getElementById("welcome-message")!.textContent = String(
 
   </Tab>
 </Tabs>
-
-## 在 React 组件中使用翻译
-
-使用 `react-intlayer`，您可以在 React 组件中使用翻译。示例如下：
-
-```jsx fileName="**/*.tsx" codeFormat={["typescript", "esm"]}
-import type { FC } from "react";
-import { useIntlayer } from "react-intlayer";
-
-const MyComponent: FC = () => {
-  const content = useIntlayer("multi_lang");
-
-  return (
-    <div>
-      <p>{content.welcomeMessage}</p>
-    </div>
-  );
-};
-
-export default MyComponent;
-```
-
-该组件根据您应用中设置的当前语言环境获取相应的翻译内容。
-
-## 自定义内容对象
-
-`intlayer` 支持用于翻译的自定义内容对象，允许您定义更复杂的结构，同时确保类型安全。以下是一个自定义对象的示例：
-
-```typescript fileName="**/*.content.ts" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
-import { t, type Dictionary } from "intlayer";
-
-interface ICustomContent {
-  title: string;
-  content: string;
-}
-
-const customContent = {
-  key: "custom_content",
-  content: {
-    profileText: t<ICustomContent>({
-      en: {
-        title: "页面标题",
-        content: "页面内容",
-      },
-      fr: {
-        title: "Titre de la Page",
-        content: "Contenu de la Page",
-      },
-      es: {
-        title: "页面标题",
-        content: "页面内容",
-      },
-    }),
-  },
-} satisfies Dictionary;
-
-export default customContent;
-```
-
-```json fileName="**/*.content.json" contentDeclarationFormat="json"
-{
-  "$schema": "https://intlayer.org/schema.json",
-  "key": "custom_content",
-  "content": {
-    "profileText": {
-      "nodeType": "translation",
-      "translation": {
-        "en": {
-          "title": "页面标题",
-          "content": "页面内容"
-        },
-        "fr": {
-          "title": "页面标题",
-          "content": "页面内容"
-        },
-        "es": {
-          "title": "页面标题",
-          "content": "页面内容"
-        }
-      }
-    }
-  }
-}
-```

package/docs/zh/formatters.md

@@ -383,6 +383,36 @@ currency(1234.5, { currency: "EUR" }); // "€1,234.50"
 currency("5000", { locale: "fr", currency: "CAD", currencyDisplay: "code" }); // "5 000,00 CAD"
 ```
 
+## 缓存的 Intl
+
+从 `intlayer` 导出的 `Intl` 是围绕全局 `Intl` 的缓存包装器。它会缓存格式化程序实例（`NumberFormat`、`DateTimeFormat` 等），以避免重复构造它们，从而提高性能。
+
+```ts
+import { Intl } from "intlayer";
+
+// 数字格式化
+const numberFormat = new Intl.NumberFormat("en-GB", {
+  style: "currency",
+  currency: "GBP",
+});
+numberFormat.format(1234.5); // "£1,234.50"
+
+// 语言、地区等的显示名称
+const displayNames = new Intl.DisplayNames("fr", { type: "language" });
+displayNames.of("en"); // "anglais"
+
+// 用于排序的排序规则
+const collator = new Intl.Collator("fr", { sensitivity: "base" });
+collator.compare("é", "e"); // 0 (相等)
+
+// 复数规则
+const pluralRules = new Intl.PluralRules("fr");
+pluralRules.select(1); // "one"
+pluralRules.select(2); // "other"
+```
+
+### 额外的 Intl 功能
+
 ### `date(date, optionsOrPreset?)`
 
 使用 `Intl.DateTimeFormat` 格式化日期/时间值。
@@ -441,6 +471,8 @@ 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`）。
@@ -482,6 +514,17 @@ list([1, 2, 3], { type: "unit" }); // "1, 2, 3"
 - 如果未提供，区域设置默认使用您配置的 `internationalization.defaultLocale`。
 - 这些工具是轻量封装；对于高级格式化，请直接传递标准的 `Intl` 选项。
 
+### `getPathWithoutLocale(inputUrl, locales?)`
+
+从 URL 中移除语言区域段：
+
+```ts
+import { getPathWithoutLocale } from "intlayer";
+
+getPathWithoutLocale("/en/dashboard"); // "/dashboard"
+getPathWithoutLocale("/fr/dashboard"); // "/dashboard"
+```
+
 ## 入口点和重新导出（`@index.ts`）
 
 格式化函数位于核心包中，并从更高级的包中重新导出，以保持跨运行时的导入简洁：
@@ -512,6 +555,20 @@ import {
 } from "intlayer";
 ```
 
+### `getHTMLTextDir(locale?)`
+
+返回一个 locale 的文本方向：
+
+```ts
+import { getHTMLTextDir } from "intlayer";
+
+getHTMLTextDir("en-US"); // "ltr"
+getHTMLTextDir("ar"); // "rtl"
+getHTMLTextDir("he"); // "rtl"
+```
+
+## 内容处理工具
+
 ### React
 
 客户端组件：
@@ -592,6 +649,20 @@ import {
 
 > 这些钩子将会从 `IntlayerProvider` 或 `IntlayerServerProvider` 中获取语言环境
 
+### `getTranslation(languageContent, locale?, fallback?)`
+
+为特定语言环境提取内容：
+
+```ts
+import { getTranslation } from "intlayer";
+
+const content = getTranslation(
+  { zh: "你好", en: "Hello", fr: "Bonjour", de: "Hallo" },
+  "fr",
+  true
+); // "Bonjour"
+```
+
 ### Vue
 
 客户端组件：
@@ -610,3 +681,9 @@ import {
 ```
 
 > 这些组合式函数将会使用注入的 `IntlayerProvider` 中的语言环境
+
+## 注意事项
+
+- 所有辅助函数接受 `string` 输入；它们在内部被强制转换为数字或日期。
+- 如果未提供 locale，则默认为你配置的 `internationalization.defaultLocale`。
+- 这些实用程序是薄包装器；对于高级格式化，请传递标准 `Intl` 选项。

package/docs/zh/how_works_intlayer.md

@@ -22,6 +22,10 @@ author: aymericzip
 
 # Intlayer 的工作原理
 
+## 目录
+
+<TOC/>
+
 ## 概述
 
 Intlayer 的核心理念是采用每个组件的内容管理。因此，Intlayer 的理念是允许您在代码库中的任何地方声明内容，例如与组件位于同一目录中。
@@ -127,8 +131,6 @@ Intlayer 由多个包组成，每个包在翻译过程中都有特定的角色
 
 ### react-intlayer
 
-### react-intlayer
-
 `react-intlayer` 包用于解释 Intlayer 字典并使其在 React 应用中可用。
 
 ### next-intlayer
@@ -157,8 +159,6 @@ Intlayer 由多个包组成，每个包在翻译过程中都有特定的角色
 
 ### angular-intlayer (开发中)
 
-### angular-intlayer (开发中)
-
 `angular-intlayer` 包用于解释 Intlayer 字典并使其在 Angular 应用中可用。
 
 ### express-intlayer

package/docs/zh/intlayer_CMS.md

@@ -40,6 +40,12 @@ Intlayer CMS 是一个应用程序，允许您将 Intlayer 项目的内容外部
 
 ![Intlayer CMS 界面](https://github.com/aymericzip/intlayer/blob/main/docs/assets/CMS.png)
 
+## 目录
+
+<TOC/>
+
+---
+
 ## 理解远程字典
 
 Intlayer 区分“本地”字典和“远程”字典。
@@ -367,3 +373,18 @@ export default config;
 - 确保项目配置已推送到 Intlayer CMS。
 
 - 可视化编辑器使用 iframe 来显示您的网站。确保您网站的内容安全策略（CSP）允许 CMS URL 作为 `frame-ancestors`（默认是 'https://intlayer.org'）。检查编辑器控制台是否有任何错误。
+
+## 调试
+
+如果您遇到 CMS 的任何问题，请检查以下内容：
+
+- 应用程序正在运行。
+
+- [`editor`](https://intlayer.org/doc/concept/configuration#editor-configuration) 配置在您的 Intlayer 配置文件中设置正确。
+  - 必需字段：
+    - 应用程序 URL 应该与您在编辑器配置中设置的 URL 相匹配（`applicationURL`）。
+    - CMS URL
+
+- 确保项目配置已推送到 Intlayer CMS。
+
+- 可视化编辑器使用 iframe 来显示您的网站。确保您的网站的内容安全策略 (CSP) 允许 CMS URL 作为 `frame-ancestors`（默认为 'https://app.intlayer.org'）。检查编辑器控制台中的任何错误。

package/docs/zh/intlayer_with_adonisjs.md

@@ -59,24 +59,40 @@ See [Application Template](https://github.com/aymericzip/intlayer-adonis-templat
 
 要开始使用 `adonis-intlayer`，请使用 npm 安装该包：
 
+```bash packageManager="npm"
+npx intlayer-cli init --interactive
+```
+
+```bash packageManager="pnpm"
+pnpm dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="yarn"
+yarn dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="bun"
+bunx intlayer-cli init --interactive
+```
+
+> `--interactive` 标志是可选的。如果您是 AI 代理，请使用 `intlayer-cli init`。
+
+> 该命令将检测您的环境并安装所需的软件包。例如：
+
 ```bash packageManager="npm"
 npm install intlayer adonis-intlayer
-npx intlayer init
 ```
 
 ```bash packageManager="pnpm"
 pnpm add intlayer adonis-intlayer
-pnpm intlayer init
 ```
 
 ```bash packageManager="yarn"
 yarn add intlayer adonis-intlayer
-yarn intlayer init
 ```
 
 ```bash packageManager="bun"
 bun add intlayer adonis-intlayer
-bun x intlayer init
 ```
 
 ### 设置

package/docs/zh/intlayer_with_analog.md

@@ -91,160 +91,6 @@ Intlayer 不仅仅是一个 i18n 解决方案，还提供了一个**自托管的
 
 ---
 
-## 在 Analog 应用中设置 Intlayer 的分步指南
-
-查看 GitHub 上的 [应用模板](https://github.com/aymericzip/intlayer-analog-template)。
-
-### 第 1 步：安装依赖项
-
-使用 npm 安装必要的软件包：
-
-```bash packageManager="npm"
-npm install intlayer angular-intlayer vite-intlayer
-npx intlayer init
-```
-
-```bash packageManager="pnpm"
-pnpm add intlayer angular-intlayer vite-intlayer
-pnpm intlayer init
-```
-
-```bash packageManager="yarn"
-yarn add intlayer angular-intlayer vite-intlayer
-yarn intlayer init
-```
-
-```bash packageManager="bun"
-bun add intlayer angular-intlayer vite-intlayer
-bun x intlayer init
-```
-
-- **intlayer**
-
-  核心软件包，提供用于配置管理、翻译、[内容声明](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/dictionary/content_file.md)、编译和 [CLI 命令](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/cli/index.md)的国际化工具。
-
-- **angular-intlayer**
-  将 Intlayer 与 Angular 应用集成的软件包。它为 Angular 国际化提供上下文提供者和 Hook。
-
-- **vite-intlayer**
-  将 Intlayer 与 Vite 集成的软件包。它提供一个插件来处理内容声明文件，并为优化性能设置别名。
-
-### 第 2 步：项目配置
-
-创建一个配置文件来配置应用的语言：
-
-```typescript fileName="intlayer.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
-import { Locales, type IntlayerConfig } from "intlayer";
-
-const config: IntlayerConfig = {
-  internationalization: {
-    locales: [
-      Locales.ENGLISH,
-      Locales.FRENCH,
-      Locales.SPANISH,
-      // 您的其他语言
-    ],
-    defaultLocale: Locales.ENGLISH,
-  },
-};
-
-export default config;
-```
-
-> 通过此配置文件，您可以设置本地化 URL、中间件重定向、Cookie 名称、内容声明的位置和扩展名、禁用控制台中的 Intlayer 日志等。有关可用参数的完整列表，请参考[配置文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/configuration.md)。
-
-### 第 3 步：在 Vite 配置中集成 Intlayer
-
-要将 Intlayer 与 Analog 集成，您需要使用 `vite-intlayer` 插件。
-
-修改您的 `vite.config.ts` 文件：
-
-```typescript fileName="vite.config.ts"
-import { defineConfig } from "vite";
-import { intlayer } from "vite-intlayer";
-import analog from "@analogjs/platform";
-
-// https://vitejs.dev/config/
-export default defineConfig(() => ({
-  plugins: [
-    analog(),
-    intlayer(), // 添加 Intlayer 插件
-  ],
-}));
-```
-
-> `intlayer()` 插件为 Vite 配置了 Intlayer。它处理内容声明文件并为优化性能设置别名。
-
-### 第 4 步：声明您的内容
-
-创建并管理您的内容声明以存储翻译：
-
-```tsx fileName="src/app/app.content.ts" contentDeclarationFormat=["typescript", "esm", "cjs"]
-import { t, type Dictionary } from "intlayer";
-
-const appContent = {
-  key: "app",
-  content: {
-    title: t({
-      en: "Hello",
-      fr: "Bonjour",
-      es: "Hola",
-      zh: "你好",
-    }),
-    congratulations: t({
-      en: "Congratulations! Your app is running. 🎉",
-      fr: "Félicitations! Votre application est en cours d'exécution. 🎉",
-      es: "¡Felicidades! Tu aplicación está en ejecución. 🎉",
-      zh: "恭喜！您的应用正在运行。 🎉",
-    }),
-  },
-} satisfies Dictionary;
-
-export default appContent;
-```
-
-> 您的内容声明可以定义在应用中的任何位置，只要它们包含在 `contentDir` 目录（默认为 `./src`）中，并且符合内容声明文件扩展名（默认为 `.content.{json,ts,tsx,js,jsx,mjs,cjs,md,mdx,yaml,yml}`）。
-
-> 有关更多详细信息，请参考[内容声明文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/dictionary/content_file.md)。
-
-### 第 5 步：在代码中使用 Intlayer
-
-要在整个 Analog 应用中使用 Intlayer 的国际化功能，您需要在应用配置中提供 Intlayer。
-
-```typescript fileName="src/app/app.config.ts"
-import { ApplicationConfig } from "@angular/core";
-import { provideIntlayer } from "angular-intlayer";
-
-export const appConfig: ApplicationConfig = {
-  providers: [
-    provideIntlayer(), // 在此处添加 Intlayer 提供者
-  ],
-};
-```
-
-然后，您可以在任何组件中使用 `useIntlayer` 函数。
-
-```typescript fileName="src/app/pages/index.page.ts"
-import { Component } from "@angular/core";
-import { useIntlayer } from "angular-intlayer";
-
-@Component({
-  selector: "app-home",
-  standalone: true,
-  template: `
-    <div class="content">
-      <h1>{{ content().title }}</h1>
-      <p>{{ content().congratulations }}</p>
-    </div>
-  `,
-})
-export default class HomeComponent {
-  content = useIntlayer("app");
-}
-```
-
-Intlayer 内容以 `Signal` 形式返回，因此您通过调用 Signal 来访问值：`content().title`。
-
 ### （可选）第 6 步：更改内容语言
 
 要更改内容的语言，您可以使用 `useLocale` 函数提供的 `setLocale` 函数。这允许您设置应用的语言环境并相应地更新内容。
@@ -351,3 +197,7 @@ Intlayer 使用模块扩充 (module augmentation) 来利用 TypeScript 的优势
 - 轻松创建和更新翻译的**快速操作**。
 
 有关如何使用该扩展的更多详细信息，请参考 [Intlayer VS Code 扩展文档](https://intlayer.org/doc/vs-code-extension)。
+
+### 进一步探索
+
+要进一步探索，你可以实现 [可视化编辑器](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_visual_editor.md) 或使用 [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_CMS.md) 外部化你的内容。