@intlayer/docs 9.4.4 → 9.5.0

package/docs/zh/intlayer_with_vite+react_compiler.md

@@ -1,655 +0,0 @@
----
-createdAt: 2024-03-07
-updatedAt: 2026-08-30
-title: "Vite + React i18n - 翻译你的应用的完整指南"
-description: "告别 i18next。2026 年构建多语言 (i18n) Vite + React 应用的完整指南。使用 AI 代理翻译并优化包体积、SEO 和性能。"
-keywords:
-  - 国际化
-  - 文档
-  - Intlayer
-  - Vite
-  - React
-  - 编译器
-  - AI
-slugs:
-  - doc
-  - environment
-  - vite-and-react
-  - compiler
-applicationTemplate: https://github.com/aymericzip/intlayer-vite-react-template
-applicationShowcase: https://intlayer-vite-react-template.vercel.app
-youtubeVideo: https://www.youtube.com/watch?v=dS9L7uJeak4
-history:
-  - version: 8.9.0
-    date: 2026-05-04
-    changes: "更新 Solid useIntlayer API 用法以直接访问属性"
-  - version: 8.2.0
-    date: 2026-03-09
-    changes: "Update compiler options, add FilePathPattern support"
-  - version: 8.1.6
-    date: 2026-02-23
-    changes: "首次发布"
-author: aymericzip
----
-
-# 如何将现有的 Vite 和 React 应用程序转换为多语言 (i18n) 应用（2026年 i18n 指南）
-
-<Tabs defaultTab="video">
-  <Tab label="视频" value="video">
-
-<iframe title="Vite 和 React 的最佳 i18n 解决方案？探索 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/dS9L7uJeak4?si=VaKmrYMmXjo3xpk2"/>
-
-  </Tab>
-  <Tab label="代码" value="code">
-
-<iframe
-  src="https://ide.intlayer.org/aymericzip/intlayer-vite-react-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-vite-react-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-vite-react-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-vite-react-template)。
-
-## 目录
-
-<TOC/>
-
-## 为什么国际化现有应用程序很困难？
-
-如果您曾经尝试为仅针对一种语言构建的应用添加多种语言，您就会明白那种痛苦。这不仅仅是“困难”，而是繁琐。您必须梳理每一个文件，搜寻每一个文本字符串，并将它们移动到单独的字典文件中。
-
-然后是风险部分：用代码钩子替换所有这些文本，而不破坏您的布局或逻辑。这种工作会使新功能的开发停滞数周，感觉像是无休止的重构。
-
-## 什么是 Intlayer 编译器？
-
-**Intlayer 编译器** 旨在跳过那些手动的琐事。编译器为您完成字符串提取，而不是由您手动提取。它扫描您的代码，找到文本，并使用 AI 在幕后生成字典。
-然后，它在构建期间修改您的代码以注入必要的 i18n 钩子。基本上，您继续像编写单语言应用一样编写应用，编译器会自动处理多语言转换。
-
-> 编译器文档：[https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/compiler.md](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/compiler.md)
-
-### 局限性
-
-由于编译器在 **编译时** 执行代码分析 and 转换（插入钩子并生成字典），它可能会 **减慢应用程序的构建过程**。
-
-为了减轻开发期间的影响，您可以将编译器配置为以 [`'build-only'`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/configuration.md) 模式运行，或在不需要时将其禁用。
-
----
-
-## 在 Vite 和 React 应用中设置 Intlayer 的分步指南
-
-<Steps>
-
-<Step number={1} title="安装依赖">
-
-使用 npm 安装必要的包：
-
-```bash packageManager="npm"
-npx intlayer init --interactive
-```
-
-```bash packageManager="pnpm"
-pnpm dlx intlayer init --interactive
-```
-
-```bash packageManager="yarn"
-yarn dlx intlayer init --interactive
-```
-
-```bash packageManager="bun"
-bunx intlayer init --interactive
-```
-
-> `--interactive` 标志是可选的。如果你是 AI 代理，请使用 `intlayer-cli init`。
-
-> 此命令将检测你的环境并安装所需的包。例如：
-
-```bash packageManager="npm"
-npm install intlayer react-intlayer
-npm install vite-intlayer --save-dev
-```
-
-```bash packageManager="pnpm"
-pnpm add intlayer react-intlayer
-pnpm add vite-intlayer --save-dev
-```
-
-```bash packageManager="yarn"
-yarn add intlayer react-intlayer
-yarn add vite-intlayer --save-dev
-```
-
-```bash packageManager="bun"
-bun add intlayer react-intlayer
-bun add vite-intlayer --dev
-```
-
-- **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)。
-
-- **react-intlayer**
-  将 Intlayer 与 React 应用集成的包。它为 React 国际化提供上下文提供程序和 hooks。
-
-- **vite-intlayer**
-  包含用于将 Intlayer 与 [Vite bundler](https://vite.dev/guide/why.html#why-bundle-for-production) 集成的 Vite 插件，以及用于检测用户首选语言环境、管理 cookie 和处理 URL 重定向的中间件。
-
-</Step>
-
-<Step number={2} title="配置你的项目">
-
-创建配置文件以配置应用程序的语言：
-
-```typescript fileName="intlayer.config.ts"
-import { Locales, type IntlayerConfig } from "intlayer";
-
-const config: IntlayerConfig = {
-  internationalization: {
-    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
-    defaultLocale: Locales.ENGLISH,
-  },
-  compiler: {
-    /**
-     * 指示编译器是否应启用。
-     */
-    enabled: true,
-
-    /**
-     * 优化字典的输出目录。
-     */
-    output: ({ locale, key }) => `compiler/${locale}/${key}.json`,
-
-    /**
-     * 仅在生成的文件中插入内容，不包含键。
-     */
-    noMetadata: false,
-
-    /**
-     * 字典键前缀
-     */
-    dictionaryKeyPrefix: "", // 移除基础前缀
-
-    /**
-     * 指示转换后的组件是否应保存。
-     *
-     * - 如果为 `true`，编译器将在磁盘上重写组件文件。因此转换将是永久的，编译器将在下一个过程中跳过转换。这样，编译器可以转换应用，然后可以将其移除。
-     *
-     * - 如果为 `false`，编译器将仅在构建输出中注入 `useIntlayer()` 函数调用，保持基础代码库完整。转换仅在内存中进行。
-     */
-    saveComponents: false,
-  },
-  ai: {
-    provider: "openai",
-    model: "gpt-5-mini",
-    apiKey: process.env.OPEN_AI_API_KEY,
-    applicationContext: "This app is an map app", // 注意：你可以自定义此应用描述
-  },
-};
-
-export default config;
-```
-
-> **注意**：确保你的 `OPEN_AI_API_KEY` 已在环境变量中设置。
-
-> 通过此配置文件，你可以设置本地化 URL、中间件重定向、cookie 名称、内容声明的位置和扩展名、禁用 Intlayer 控制台日志等。有关可用参数的完整列表，请参阅[配置文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/configuration.md)。
-
-</Step>
-
-<Step number={3} title="在你的 Vite 配置中集成 Intlayer">
-
-将 intlayer 插件添加到你的配置中。
-
-```typescript fileName="vite.config.ts"
-import { defineConfig } from "vite";
-import react from "@vitejs/plugin-react-swc";
-import { intlayer } from "vite-intlayer";
-
-// https://vitejs.dev/config/
-export default defineConfig({
-  plugins: [
-    react(),
-    intlayer({
-      proxy: {
-        ignore: (req) => req.url?.startsWith("/api"),
-      },
-    }),
-  ],
-});
-```
-
-> `intlayer()` Vite 插件用于将 Intlayer 与 Vite 集成。它确保构建内容声明文件并在开发模式下监视它们。它在 Vite 应用中定义 Intlayer 环境变量。此外，它提供别名以优化性能。
-
-> `intlayerCompiler()` Vite 插件用于从组件提取内容并写入 `.content` 文件。
-
-> 从 Intlayer v9 开始，编译器直接捆绑到 `intlayer()` 插件中，一旦设置了 `compiler.enabled` 和 `compiler.output` 路径，就会自动激活。如下所示单独注册 `intlayerCompiler()` 现在是可选的——如果也添加了它，它会自动去重。请参阅 [v9 发布说明](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/releases/v9.md)。
-
-</Step>
-
-<Step number={4} title="编译你的代码">
-
-仅需使用默认语言中的硬编码字符串编写组件。编译器会处理其余部分。
-
-你的页面可能看起来的示例：
-
-<Tabs>
- <Tab value="Code">
-
-```tsx fileName="src/App.tsx"
-import { useState, type FC } from "react";
-import reactLogo from "./assets/react.svg";
-import viteLogo from "/vite.svg";
-import "./App.css";
-import { IntlayerProvider } from "react-intlayer";
-
-const AppContent: FC = () => {
-  const [count, setCount] = useState(0);
-
-  return (
-    <>
-      <div>
-        <a href="https://vitejs.dev" target="_blank">
-          <img src={viteLogo} className="logo" alt="Vite logo" />
-        </a>
-        <a href="https://react.dev" target="_blank">
-          <img src={reactLogo} className="logo react" alt="React logo" />
-        </a>
-      </div>
-      <h1>Vite + React</h1>
-      <div className="card">
-        <button onClick={() => setCount((count) => count + 1)}>
-          count is {count}
-        </button>
-        <p>
-          Edit <code>src/App.tsx</code> and save to test HMR
-        </p>
-      </div>
-      <p className="read-the-docs">
-        Click on the Vite and React logos to learn more
-      </p>
-    </>
-  );
-};
-
-const App: FC = () => (
-  <IntlayerProvider>
-    <AppContent />
-  </IntlayerProvider>
-);
-
-export default App;
-```
-
- </Tab>
- <Tab value="Output">
-
-```ts fileName="i18n/app-content.content.json"
-{
-  key: "app-content",
-  content: {
-    nodeType: "translation",
-    translation: {
-      en: {
-        viteLogo: "Vite logo",
-        reactLogo: "React logo",
-        title: "Vite + React",
-        countButton: "count is",
-        editMessage: "Edit",
-        hmrMessage: "and save to test HMR",
-        readTheDocs: "Click on the Vite and React logos to learn more",
-      },
-      fr: {
-        viteLogo: "Logo Vite",
-        reactLogo: "Logo React",
-        title: "Vite + React",
-        countButton: "compte est",
-        editMessage: "Modifier",
-        hmrMessage: "et enregistrer pour tester HMR",
-        readTheDocs: "Cliquez sur les logos Vite et React pour en savoir plus",
-      },
-    }
-  }
-}
-```
-
-```tsx fileName="src/App.tsx"
-import { useState, type FC } from "react";
-import reactLogo from "./assets/react.svg";
-import viteLogo from "/vite.svg";
-import "./App.css";
-import { IntlayerProvider, useIntlayer } from "react-intlayer";
-
-const AppContent: FC = () => {
-  const [count, setCount] = useState(0);
-  const content = useIntlayer("app-content");
-
-  return (
-    <>
-      <div>
-        <a href="https://vitejs.dev" target="_blank">
-          <img src={viteLogo} className="logo" alt={content.viteLogo.value} />
-        </a>
-        <a href="https://react.dev" target="_blank">
-          <img
-            src={reactLogo}
-            className="logo react"
-            alt={content.reactLogo.value}
-          />
-        </a>
-      </div>
-      <h1>{content.title}</h1>
-      <div className="card">
-        <button onClick={() => setCount((count) => count + 1)}>
-          {content.countButton} {count}
-        </button>
-        <p>
-          {content.editMessage} <code>src/App.tsx</code> {content.hmrMessage}
-        </p>
-      </div>
-      <p className="read-the-docs">{content.readTheDocs}</p>
-    </>
-  );
-};
-
-const App: FC = () => (
-  <IntlayerProvider>
-    <AppContent />
-  </IntlayerProvider>
-);
-
-export default App;
-```
-
- </Tab>
-</Tabs>
-
-- **`IntlayerProvider`** 用于向嵌套组件提供语言环境。
-
-</Step>
-
-<Step number={6} title="更改内容的语言" isOptional={true}>
-
-要更改内容的语言，你可以使用 `useLocale` hook 提供的 `setLocale` 函数。此函数允许你设置应用程序的语言环境并相应地更新内容。
-
-```tsx fileName="src/components/LocaleSwitcher.tsx"
-import type { FC } from "react";
-import { Locales } from "intlayer";
-import { useLocale } from "react-intlayer";
-
-const LocaleSwitcher: FC = () => {
-  const { setLocale } = useLocale();
-
-  return (
-    <button onClick={() => setLocale(Locales.English)}>
-      Change Language to English
-    </button>
-  );
-};
-```
-
-> 要了解更多关于 `useLocale` hook 的信息，请参阅[文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/packages/react-intlayer/useLocale.md)。
-
-</Step>
-
-<Step number={7} title="填充缺失的翻译" isOptional={true}>
-
-Intlayer 提供了一个 CLI 工具来帮助你填充缺失的翻译。你可以使用 `intlayer` 命令来测试和填充代码中缺失的翻译。
-
-```bash packageManager="npm"
-npx intlayer test         # 测试是否有缺失的翻译
-```
-
-```bash packageManager="yarn"
-yarn intlayer test         # 测试是否有缺失的翻译
-```
-
-```bash packageManager="pnpm"
-pnpm intlayer test         # 测试是否有缺失的翻译
-```
-
-```bash packageManager="bun"
-bun x intlayer test         # 测试是否有缺失的翻译
-```
-
-```bash packageManager="npm"
-npx intlayer fill         # 填充缺失的翻译
-```
-
-```bash packageManager="yarn"
-yarn intlayer fill         # 填充缺失的翻译
-```
-
-```bash packageManager="pnpm"
-pnpm intlayer fill         # 填充缺失的翻译
-```
-
-```bash packageManager="bun"
-bun x intlayer fill         # 填充缺失的翻译
-```
-
-> 有关更多详细信息，请参阅 [CLI 文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/cli/ci.md)
-
-</Step>
-
-</Steps>
-
-### （可选）站点地图与 robots.txt（构建时生成）
-
-Intlayer 提供 `generateSitemap` 与 `getMultilingualUrls`，可将面向爬虫的多语言 `sitemap.xml` 和 `robots.txt` 格式化并自动写入 `public/`。实践中在 Vite **之前**运行小型 Node 脚本（例如 npm 的 `predev` / `prebuild`）即可在构建或开发时生成这些文件。
-
-#### 站点地图
-
-Intlayer 的站点地图生成会尊重你的语言配置，并包含爬虫所需的元数据。
-
-> 生成的站点地图支持 `xhtml:link`（hreflang）。与只列出扁平 URL 不同，Intlayer 会在各语言版本之间建立双向关联（例如 `/about`、`/fr/about` 或 `/about?lang=fr`，取决于路由模式）。
-
-#### Robots.txt
-
-使用 `getMultilingualUrls`，使 `Disallow` 覆盖敏感路径的每一种本地化写法。
-
-#### 1. 在项目根目录添加 `generate-seo.mjs`
-
-```javascript fileName="generate-seo.mjs"
-import fs from "fs";
-import path from "path";
-import { fileURLToPath } from "url";
-import { generateSitemap, getMultilingualUrls } from "intlayer";
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-
-const SITE_URL = (process.env.SITE_URL || "http://localhost:5173").replace(
-  /\/$/,
-  ""
-);
-
-const pathList = [
-  { path: "/", changefreq: "daily", priority: 1.0 },
-  { path: "/about", changefreq: "monthly", priority: 0.7 },
-];
-
-const sitemapXml = generateSitemap(pathList, { siteUrl: SITE_URL });
-fs.writeFileSync(path.join(__dirname, "public", "sitemap.xml"), sitemapXml);
-
-const getAllMultilingualUrls = (urls) =>
-  urls.flatMap((url) => Object.values(getMultilingualUrls(url)));
-
-const disallowedPaths = getAllMultilingualUrls(["/admin", "/private"]);
-
-const robotsTxt = [
-  "User-agent: *",
-  "Allow: /",
-  ...disallowedPaths.map((path) => `Disallow: ${path}`),
-  "",
-  `Sitemap: ${SITE_URL}/sitemap.xml`,
-].join("\n");
-
-fs.writeFileSync(path.join(__dirname, "public", "robots.txt"), robotsTxt);
-
-console.log("SEO files generated successfully.");
-```
-
-需已安装 `intlayer` 以便脚本导入。生产环境请设置环境变量 `SITE_URL`（例如在 CI 中）。
-
-> 建议在 Node 中使用 `generate-seo.mjs`（ESM）。若使用 `generate-seo.js`，请在 `package.json` 中设置 `"type": "module"` 或以其他方式启用 ESM。
-
-#### 2. 在运行 Vite 之前执行脚本
-
-```json fileName="package.json"
-{
-  "scripts": {
-    "dev": "vite",
-    "prebuild": "node generate-seo.mjs",
-    "build": "vite build",
-    "preview": "vite preview"
-  }
-}
-```
-
-若使用 pnpm 或 yarn，请相应调整命令；也可在 CI 或其他步骤中调用该脚本。
-
-### Git 配置
-
-建议忽略 Intlayer 生成的文件。这可以避免将它们提交到您的 Git 仓库。
-
-为此，您可以将以下指令添加到 `.gitignore` 文件中：
-
-```plaintext fileName=".gitignore"
-# 忽略 Intlayer 生成的文件
-.intlayer
-```
-
-### VS Code 扩展
-
-为了提升您使用 Intlayer 的开发体验，您可以安装官方的 **Intlayer VS Code 扩展**。
-
-[从 VS Code 市场安装](https://marketplace.visualstudio.com/items?itemName=intlayer.intlayer-vs-code-extension)
-
-此扩展提供：
-
-- 翻译键的 **自动补全**。
-- 缺失翻译的 **实时错误检测**。
-- 翻译内容的 **内联预览**。
-- 轻松创建和更新翻译的 **快速操作**。
-
-有关如何使用该扩展的更多详细信息，请参阅 [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) 外置您的内容。
-
-## 常见问题
-
-<FAQ>
-
-<Question title="国际化 Vite + React 应用有哪些不同的解决方案？">
-
-- **`react-i18next` / `i18next`**：在运行时加载 JSON 命名空间，在每个调用处手动编写键名。
-- **`react-intl`** 与 **`Lingui`**：ICU 消息格式，需要您自行运行提取步骤。
-- **`Intlayer`**：在构建时直接从组件中提取编译内容，完全类型安全，并配有 AI 翻译、可视化编辑器和 CMS。
-
-本指南采用编译器方案，您可以继续在组件中编写普通的字符串，字典会自动为您生成。请参阅 [为什么选择 Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/interest_of_intlayer.md) 和 [性能基准](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/benchmark/index.md)。
-
-</Question>
-
-<Question title="i18n 会给我的 Vite bundle 体积增加多少？">
-
-远少于基于命名空间的方案，因为页面永远不会下载它不渲染的语言目录。构建时编译器将 `useIntlayer` 调用替换为组件使用的确切字典条目，因此未使用的键和未使用的语言都会被自动丢弃，并且 [动态字典](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/dynamic_dictionaries/index.md) 会按语言环境拆分剩余内容。与常规替代方案相比，Intlayer 可将 bundle 和页面体积减少高达 50%。请参阅 [Bundle 体积优化](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/bundle_optimization.md) 和 [性能基准](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/benchmark/index.md)。
-
-</Question>
-
-<Question title="我可以从 react-i18next 或 react-intl 迁移而无需重写组件吗？">
-
-可以，有两条迁移路径。您可以使用 [react-i18next 迁移指南](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/migration_from_react-i18next_to_intlayer.md) 或 [i18next 迁移指南](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/migration_from_i18next_to_intlayer.md) 逐步迁移内容。或者，您可以完全保留当前的 API：[兼容性适配器](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/compat/index.md) 公开与 `react-i18next`、`react-intl` 和 `i18next` 完全相同的 API，但底层由 Intlayer 字典驱动，因此只需更改导入语句，组件代码完全无需修改。
-
-</Question>
-
-<Question title="我可以保留现有的 JSON 翻译文件吗？">
-
-可以。[JSON 同步插件](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/plugins/sync-json.md) 将您的 `/messages/{locale}/{namespace}.json` 文件作为单一真实来源（source of truth），并双向生成 Intlayer 字典。[PO 同步插件](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/plugins/sync-po.md) 对 gettext 目录执行相同的操作，而 [按语言环境组织的文件](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/per_locale_file.md) 允许您按语言拆分内容，而不是将所有语言打包到一个文件中。
-
-</Question>
-
-<Question title="我必须逐个键迁移我的内容吗？">
-
-不需要，这正是本指南所配置的内容。您只需在默认语言环境中使用普通文本编写组件，[Intlayer Compiler](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/compiler.md) 会在每次构建时扫描源码，提取面向用户的文本并生成字典，因此无需手动创建或维护任何键。
-
-有两个限制值得了解：编译器通过静态分析工作，因此仅在运行时存在的字符串（如 API 错误代码或 CMS 字段）无法被捕获，仍需显式声明字典；此外它需要区分用户文本和应用程序逻辑（如 `className="active"` 或状态代码），在大型代码库中需要少量注解。
-
-如果您希望保留完全掌控权，`npx intlayer extract` 可以对您选定的文件执行单次提取，并在每个组件旁边生成 `.content` 文件供您审查。请参阅 [extract 命令](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/cli/extract.md)。
-
-</Question>
-
-<Question title="有哪些可用的编辑器和 AI 代理工具？">
-
-共有 5 个工具，均为可选：
-
-- **[VS Code 扩展](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/vs_code_extension.md)**：从 `useIntlayer` 键跳转到声明它的内容文件，从组件中提取内容，并从命令面板或专属的 Intlayer 选项卡运行 build、fill、test、push 和 pull。
-- **[LSP 服务器](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/lsp.md)**：在任何支持 LSP 的编辑器中提供相同的感知能力，支持跳转到定义、查找所有引用、悬停预览翻译值、键和字段的自动补全，以及在键未声明时发出警告。它还可以解析 `i18next`、`react-i18next`、`next-intl` 和 `use-intl` 调用，助力平滑迁移。
-- **[MCP 服务器](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/mcp_server.md)**：向 Cursor、VS Code、Claude Desktop、Claude Code 和 ChatGPT 公开 Intlayer 文档与 CLI，使 AI 助手能够基于最新文档进行准确回答，并能自行运行 `intlayer fill` 等命令。
-- **[Agent Skills](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/agent_skills.md)**：针对特定领域的技能（如 `intlayer-config`、`intlayer-cli` 和 `intlayer-content`，以及每个框架对应的专属技能），教导 AI 代理您的路由配置和内容节点类型。
-- **[ESLint 插件](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/eslint.md)**：`no-raw-text` 规则标记硬编码字符串，并提供针对静态字典键和未使用内容的额外规则。
-
-</Question>
-
-<Question title="我应该使用编译器还是自己声明内容？">
-
-当您希望以最低成本为现有代码库添加 i18n 时，请使用编译器：组件保持原样，字典自动生成。当您需要对键名、结构和跨组件复用拥有明确掌控时，请按照 [标准 Vite + React 指南](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_with_vite+react.md) 手动声明内容。两者可以共存：编译内容和声明内容共享同一字典层。
-
-</Question>
-
-<Question title="编译器无法看到的字符串会怎样？">
-
-由于编译器依赖静态分析，这些字符串将保持未翻译状态。任何在运行时组装的内容（例如 API 错误信息、CMS 字段或通过字符串拼接生成的内容）都必须按照常规方式在内容文件中显式声明。运行 `npx intlayer test` 可检测缺失的内容。
-
-</Question>
-
-<Question title="编译器如何判断哪些是面向用户的文本？">
-
-通过对 JSX 进行启发式分析，这也是为什么可能会出现双向偏差：`className` 的值或状态代码可能被误认为文案，而不常见的模式可能会被遗漏。在大型代码库中，您可以通过注解纠正极端边缘用例。如果您不希望出现这种折衷，`npx intlayer extract` 可以执行单次提取并输出 diff 供您审查。请参阅 [extract 命令](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/cli/extract.md)。
-
-</Question>
-
-<Question title="如何填充缺失的翻译？">
-
-第 7 步介绍了此内容。`npx intlayer fill` 将提取的内容发送给您选择的 LLM（使用您自己的提供商和 API 密钥），`--git-diff` 可将范围限制在当前分支修改的内容。请参阅 [fill 命令](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/cli/fill.md) 和 [CI/CD 集成](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/CI_CD.md)。
-
-</Question>
-
-<Question title="如何在运行时切换语言？">
-
-第 6 步介绍了此内容。`useLocale` 公开当前语言环境、声明的语言环境列表以及用于持久化选择的设置函数，读取编译内容的组件会在新语言下重新渲染，而无需刷新页面。
-
-</Question>
-
-<Question title="Intlayer 是否支持复数、性别和富文本？">
-
-支持：包括 [复数形式](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/dictionary/plurial.md)、[基于性别的内容](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/dictionary/gender.md)、条件渲染、插值用的 [插入内容 (insertions)](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/dictionary/insertion.md)、用于长文本的 [Markdown](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/dictionary/markdown.md)，以及用于数字、日期和货币的 [格式化工具](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/formatters.md)。
-
-</Question>
-
-<Question title="翻译人员如何无需接触代码即可编辑内容？">
-
-可以通过在您自己的基础设施上运行的 [可视化编辑器](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) 进行无需重新部署的内容外部化更新。
-
-</Question>
-
-<Question title="Intlayer 是免费且开源的吗？">
-
-是的，基于 Apache 2.0 许可证开源，包含商业用途。托管版 CMS 是可选的付费服务，同时完全支持 [自托管](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/self_hosting.md)。
-
-</Question>
-
-</FAQ>