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

package/docs/zh/intlayer_with_nuxt.md

@@ -70,152 +70,6 @@ Intlayer 不仅仅是一个 i18n 解决方案，还提供了一个**自托管的
 
 ---
 
-## 在 Nuxt 应用中设置 Intlayer 的分步指南
-
-<Tabs defaultTab="video">
-  <Tab label="视频" value="video">
-  
-<iframe title="如何使用 Intlayer 翻译你的 Nuxt 和 Vue 应用？探索 Intlayer" class="m-auto aspect-16/9 w-full overflow-hidden rounded-lg border-0" allow="autoplay; gyroscope;" loading="lazy" width="1080" height="auto" src="https://www.youtube.com/embed/nhUcUAVQ6eQ?autoplay=0&amp;origin=https://intlayer.org&amp;controls=0&amp;rel=1"/>
-
-  </Tab>
-  <Tab label="代码" value="code">
-
-<iframe
-  src="https://ide.intlayer.org/aymericzip/intlayer-nuxt-4-template?file=intlayer.config.ts"
-  className="m-auto overflow-hidden rounded-lg border-0 max-md:size-full max-md:h-[700px] md:aspect-16/9 md:w-full"
-  title="演示 CodeSandbox - 如何使用 Intlayer 实现应用国际化"
-  sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
-  loading="lazy"
-/>
-
-  </Tab>
-  <Tab label="演示" value="demo">
-
-<iframe
-  src="https://intlayer-nuxt-4-template.vercel.app"
-  className="m-auto overflow-hidden rounded-lg border-0 max-md:size-full max-md:h-[700px] md:aspect-16/9 md:w-full"
-  title="演示 - intlayer-nuxt-4-template"
-  sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
-  loading="lazy"
-/>
-
-  </Tab>
-</Tabs>
-
-### 第一步：安装依赖
-
-查看 GitHub 上的[应用模板](https://github.com/aymericzip/intlayer-nuxt-4-template)。
-
-使用 npm 安装必要的包：
-
-```bash packageManager="npm"
-npm install intlayer vue-intlayer
-npm install --save-dev nuxt-intlayer
-npx intlayer init
-```
-
-```bash packageManager="pnpm"
-pnpm add intlayer vue-intlayer
-pnpm add --save-dev nuxt-intlayer
-pnpm intlayer init
-```
-
-```bash packageManager="yarn"
-yarn add intlayer vue-intlayer
-yarn add --save-dev nuxt-intlayer
-yarn intlayer init
-```
-
-```bash packageManager="bun"
-bun add intlayer vue-intlayer
-bun add --dev nuxt-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)。
-
-- **vue-intlayer**
-  将 Intlayer 集成到 Vue 应用中的包。它提供了 Vue 组件的组合式函数。
-
-- **nuxt-intlayer**
-  集成 Intlayer 与 Nuxt 应用的 Nuxt 模块。它提供自动设置、用于语言环境检测的中间件、Cookie 管理和 URL 重定向。
-
-### 第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)。
-
-### 第三步：在您的 Nuxt 配置中集成 Intlayer
-
-将 intlayer 模块添加到您的 Nuxt 配置中：
-
-```typescript fileName="nuxt.config.ts"
-import { defineNuxtConfig } from "nuxt/config";
-
-export default defineNuxtConfig({
-  // ... 您现有的 Nuxt 配置
-  modules: ["nuxt-intlayer"],
-});
-```
-
-> `nuxt-intlayer` 模块会自动处理 Intlayer 与 Nuxt 的集成。它设置内容声明的构建，监控开发模式下的文件，提供用于语言环境检测的中间件，并管理本地化路由。
-
-### 第4步：声明您的内容
-
-创建并管理您的内容声明以存储翻译：
-
-```tsx fileName="content/home-page.content.ts" contentDeclarationFormat=["typescript", "esm", "cjs"]
-import { type Dictionary, t } from "intlayer";
-
-const content = {
-  key: "home-page",
-  content: {
-    title: t({
-      en: "Hello world",
-      fr: "Bonjour le monde",
-      es: "Hola mundo",
-    }),
-    metaTitle: t({
-      en: "Welcome | My Application",
-      fr: "Bienvenue | Mon Application",
-      es: "Bienvenido | Mi Aplicación",
-    }),
-    metaDescription: t({
-      en: "Discover your multilingual Nuxt app homepage powered by Intlayer.",
-      fr: "Découvrez la page d'accueil multilingue de votre application Nuxt propulsée par Intlayer.",
-      es: "Descubre la página de inicio multilingüe de tu aplicación Nuxt impulsada por Intlayer.",
-    }),
-  },
-} satisfies Dictionary;
-
-export default content;
-```
-
-> 您的内容声明可以定义在应用程序中的任何位置，只要它们包含在 `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
 
 在整个 Nuxt 应用中使用 `useIntlayer` 组合式函数访问您的内容字典：
@@ -578,9 +432,7 @@ export default aboutPageContent;
 
 </Step>
 
-</Steps>
-
-### （可选）步骤 6b：创建带导航的布局
+<Step number="6b" title="创建带导航的布局" isOptional={true}>
 
 Nuxt 布局允许您为页面定义一个通用结构。创建一个包含语言切换器和导航的默认布局：
 
@@ -607,6 +459,10 @@ import LocaleSwitcher from "~/components/LocaleSwitcher.vue";
 
 `Links` 组件（如下所示）确保内部导航链接会自动本地化。
 
+</Step>
+
+</Steps>
+
 ### Git 配置
 
 建议忽略 Intlayer 生成的文件。这样可以避免将它们提交到您的 Git 仓库中。

package/docs/zh/intlayer_with_react_native+expo.md

@@ -58,167 +58,61 @@ author: aymericzip
 
 请参阅 GitHub 上的[应用模板](https://github.com/aymericzip/intlayer-react-native-template)。
 
-## 为什么选择 Inlayer 而不是替代品？
-
-与“react-native-localize”或“i18next”等主要解决方案相比，Intlayer 是一个具有集成优化的解决方案，例如：
-
-**完整的 React Native 覆盖**
-
-Intlayer 经过优化，可与 React Native 和 Expo 完美配合，提供**组件级内容范围**、**TypeScript 支持**以及移动应用中扩展国际化 (i18n) 所需的所有功能。
-
-**可维护性**
-
-确定应用程序内容的范围**有利于大型应用程序的维护**。您可以复制或删除单个功能文件夹，而无需承担检查整个内容代码库的精神负担。此外，Intlayer 具有**完全类型化 (fully typed)**，以确保您的内容的准确性。
-
-**人工智能代理**
-
-共置内容**减少大型语言模型 (LLM) 所需的上下文**。 Intlayer 还附带了一套工具，例如用于测试缺失翻译的 **CLI**、**[LSP](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/lsp.md)**、**[MCP](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/mcp_server.md)** 和 **[agent技能](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/agent_skills.md)**，使 AI 代理的开发者体验 (DX) 更加流畅。
-
-**自动化**
-
-使用您选择的法学硕士，通过自动化在 CI/CD 管道中进行翻译，而费用由您的 AI 提供商承担。 Intlayer 还提供了一个**编译器**来自动提取内容，以及一个[网络平台](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_CMS.md)来帮助**在后台翻译**。
-
-**表现**
-
-将大量 JSON 文件连接到组件可能会导致性能和反应性问题。 Intlayer 可在构建时 (build time)优化您的内容加载。
-
-**无需开发即可扩展**
+### 套餐
 
-Intlayer 不仅仅是一个 i18n 解决方案，还提供了一个**自托管的[可视化编辑器](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_visual_editor.md)**和一个**[完整的 CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_CMS.md)** 来帮助您管理多语言内容**实时**，与译员、文案人员和其他团队成员无缝协作。内容可以本地和/或远程存储。
+- **内层**  
+  用于配置、字典内容、类型生成和 CLI 命令的核心 i18n 工具包。
 
-**捆绑尺寸**
+- **反应内层**  
+  React 集成提供了上下文提供程序和 React 挂钩，您将在 React Native 中使用它们来获取和切换语言环境。
 
-不要将大量 JSON 文件加载到页面中，而只需加载必要的内容。 Intlayer 有助于**将捆绑包和视图大小减少多达 50%**。
+- **react-native-intlayer**  
+  React Native 集成提供了 Metro 插件，用于将 Intlayer 与 React Native 捆绑器集成。
 
-## 第 1 步：安装依赖项
+---
 
-请参阅 GitHub 上的[应用程序模板](https://github.com/aymericzip/intlayer-react-native-template)。
+## 第一步：安装依赖
 
-从您的 React Native 项目中，安装以下软件包：
+在你的 React Native 项目中，安装以下包：
 
-```bash packageManager =“npm”
-npm install intlayer React-intlayer
-npm install --save-dev react-native-intlayer
-npx 层初始化
+```bash packageManager="npm"
+npx intlayer-cli init --interactive
 ```
 
 ```bash packageManager="pnpm"
-pnpm 添加 intlayer 反应 inlayer
-pnpm add --save-dev react-native-intlayer
-pnpm 内层初始化
+pnpm dlx intlayer-cli init --interactive
 ```
 
-```bash packageManager =“纱线”
-纱线添加内层反应内层
-纱线添加--save-dev反应-native-intlayer
-纱线内层初始化
+```bash packageManager="yarn"
+yarn dlx intlayer-cli init --interactive
 ```
 
-```bash packageManager =“bun”
-面包添加内层反应内层
-Bun 添加 --dev React-Native-intlayer
-面包x内层初始化
+```bash packageManager="bun"
+bunx intlayer-cli init --interactive
 ```
 
-### 套餐
-
-- **内层**  
-  用于配置、字典内容、类型生成和 CLI 命令的核心 i18n 工具包。
-
-- **反应内层**  
-  React 集成提供了上下文提供程序和 React 挂钩，您将在 React Native 中使用它们来获取和切换语言环境。
-
-- **react-native-intlayer**  
-  React Native 集成提供了 Metro 插件，用于将 Intlayer 与 React Native 捆绑器集成。
-
----
+> `--interactive` 标志是可选的。如果您是 AI 代理，请使用 `intlayer-cli init`。
 
-## 第一步：安装依赖
-
-在你的 React Native 项目中，安装以下包：
+> 该命令将检测您的环境并安装所需的软件包。例如：
 
 ```bash packageManager="npm"
 npm install intlayer react-intlayer
 npm install --save-dev react-native-intlayer
-npx intlayer init
 ```
 
 ```bash packageManager="pnpm"
 pnpm add intlayer react-intlayer
 pnpm add --save-dev react-native-intlayer
-pnpm intlayer init
 ```
 
 ```bash packageManager="yarn"
 yarn add intlayer react-intlayer
 yarn add --save-dev react-native-intlayer
-yarn intlayer init
 ```
 
 ```bash packageManager="bun"
 bun add intlayer react-intlayer
 bun add --dev react-native-intlayer
-bun x intlayer init
-```
-
-### 包说明
-
-- **intlayer**  
-  核心的国际化工具包，用于配置、词典内容、类型生成和命令行工具。
-
-- **react-intlayer**  
-  React 集成，提供上下文提供者和 React 钩子，供你在 React Native 中获取和切换语言环境。
-
-- **react-native-intlayer**  
-  React Native 集成，提供 Metro 插件，用于将 Intlayer 集成到 React Native 打包工具中。
-
----
-
-## 第二步：创建 Intlayer 配置文件
-
-在你的项目根目录（或任何方便的位置），创建一个 **Intlayer 配置** 文件。它可能看起来像这样：
-
-```ts fileName="intlayer.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
-/**
- * 如果 Locales 类型不可用，尝试在你的 tsconfig.json 中将 moduleResolution 设置为 "bundler"
- */
-import { Locales, type IntlayerConfig } from "intlayer";
-
-const config: IntlayerConfig = {
-  internationalization: {
-    locales: [
-      Locales.ENGLISH,
-      Locales.FRENCH,
-      Locales.SPANISH,
-      // ... 添加你需要的其他语言环境
-    ],
-    defaultLocale: Locales.ENGLISH,
-  },
-};
-
-export default config;
-```
-
-在此配置中，您可以：
-
-- 配置您的**支持语言列表**。
-- 设置一个**默认**语言环境。
-- 以后，您可以添加更高级的选项（例如，日志、自定义内容目录等）。
-- 更多信息请参见[Intlayer 配置文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/configuration.md)。
-
-## 第3步：添加 Metro 插件
-
-Metro 是 React Native 的打包工具。它是通过 `react-native init` 命令创建的 React Native 项目的默认打包工具。要在 Metro 中使用 Intlayer，您需要将插件添加到您的 `metro.config.js` 文件中：
-
-```js fileName="metro.config.js"
-const { getDefaultConfig } = require("expo/metro-config");
-const { configMetroIntlayer } = require("react-native-intlayer/metro");
-
-module.exports = (async () => {
-  const defaultConfig = getDefaultConfig(__dirname);
-
-  return await configMetroIntlayer(defaultConfig);
-})();
 ```
 
 ## 第4步：添加 Intlayer 提供者
@@ -268,6 +162,14 @@ export default RootLayout;
 
 ## 第5步：声明您的内容
 
+> **Expo Router (web): 请将 `.content.*` 文件保留在 `app/` 目录之外。** Expo Router 会将 `app/` 内的每个 JavaScript/TypeScript 文件视为一个路由。在 web 上，它的路由发现会直接扫描文件系统，并且 **不** 遵循 Metro 的 `resolver.blockList`，因此同位置的 `*.content.ts` 会被注册为一个路由。像 `app/(tabs)/_layout.content.ts` 这样的文件甚至会被解析为布局（`.content` 部分被读取为平台后缀），这会与实际的 `_layout.tsx` 发生冲突并抛出错误：
+>
+> ```
+> The layouts "./(tabs)/_layout.content.ts" and "./(tabs)/_layout.tsx" conflict on the route "/(tabs)/_layout.content". Remove or rename one of these files.
+> ```
+>
+> 请将您的声明放置在 `app/` 之外的目录中（例如 `content/` 或 `src/content/`）。Intlayer 会发现项目中任意位置的 `.content.*` 文件，字典通过它们的 `key` 进行引用，因此不需要进行任何导入更改。在原生端这不是必需的（Metro 的 `blockList` 已经隐藏了它们），但使用非 `app/` 目录可确保这两个平台都能正常工作。
+
 ````
 
 ```jsx fileName="app/_layout.cjx" codeFormat="commonjs"
@@ -292,71 +194,6 @@ const RootLayout = () => {
 module.exports = RootLayout;
 ````
 
-## 第5步：声明您的内容
-
-在项目中的任意位置（通常在 `src/` 目录下）创建**内容声明**文件，使用 Intlayer 支持的任何扩展名格式：
-
-- `.content.json`
-- `.content.ts`
-- `.content.tsx`
-- `.content.js`
-- `.content.jsx`
-- `.content.mjs`
-- `.content.mjx`
-- `.content.cjs`
-- `.content.cjx`
-- 等等。
-
-示例（使用带有 React Native TSX 节点的 TypeScript）：
-
-```tsx fileName="src/app.content.tsx" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
-import { t, type Dictionary } from "intlayer";
-import type { ReactNode } from "react";
-
-/**
- * 我们的 "app" 域的内容字典
- */
-import { t, type Dictionary } from "intlayer";
-
-const homeScreenContent = {
-  key: "home-screen",
-  content: {
-    title: t({
-      en: "Welcome!",
-      fr: "Bienvenue!",
-      es: "¡Bienvenido!",
-    }),
-  },
-} satisfies Dictionary;
-
-export default homeScreenContent;
-```
-
-```json fileName="src/app.content.json" contentDeclarationFormat="json"
-{
-  "$schema": "https://intlayer.org/schema.json",
-  "key": "app",
-  "content": {
-    "title": {
-      "nodeType": "translation",
-      "translation": {
-        "en": "Welcome!",
-        "fr": "Bienvenue!",
-        "es": "¡Bienvenido!"
-      }
-    }
-  }
-}
-```
-
-> 有关内容声明的详细信息，请参阅 [Intlayer 内容文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/dictionary/content_file.md)。
-
----
-
-## 第4步：在组件中使用 Intlayer
-
-在子组件中使用 `useIntlayer` 钩子以获取本地化内容。
-
 ### 示例
 
 ```tsx fileName="app/(tabs)/index.tsx" codeFormat={["typescript", "esm"]}
@@ -525,3 +362,31 @@ Intlayer 会在一个隐藏文件夹中（默认是 `.intlayer`）生成类型
 享受通过 **Intlayer** 为您的 **React Native** 应用构建强大国际化支持的乐趣！
 
 ---
+
+### 调试
+
+React Native 的稳定性不如 React Web，因此要特别注意版本对齐。
+
+Intlayer 主要针对 Web Intl API；在 React Native 上，你必须包含适当的 polyfills。
+
+检查清单：
+
+- 使用最新版本的 `intlayer`、`react-intlayer` 和 `react-native-intlayer`。
+- 启用 Intlayer polyfill。
+- 如果你使用 `getLocaleName` 或其他基于 Intl-API 的工具，请提前导入这些 polyfills（例如在 `index.js` 或 `App.tsx` 中）：
+
+```ts
+import "intl";
+import "@formatjs/intl-getcanonicallocales/polyfill";
+import "@formatjs/intl-locale/polyfill";
+import "@formatjs/intl-pluralrules/polyfill";
+import "@formatjs/intl-displaynames/polyfill";
+import "@formatjs/intl-listformat/polyfill";
+import "@formatjs/intl-numberformat/polyfill";
+import "@formatjs/intl-relativetimeformat/polyfill";
+import "@formatjs/intl-datetimeformat/polyfill";
+```
+
+- 如果模块无法解析，请验证你的 Metro 配置（resolver 别名、asset 插件、`tsconfig` 路径）。
+
+---