@intlayer/docs 9.0.0-canary.4 → 9.0.0-canary.6

package/docs/zh/intlayer_with_vite+react.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2024-03-07
-updatedAt: 2026-05-31
+updatedAt: 2026-06-23
 title: "Vite + React i18n - 翻译你的应用的完整指南"
 description: "告别 i18next。2026 年构建多语言 (i18n) Vite + React 应用的完整指南。使用 AI 代理翻译并优化包体积、SEO 和性能。"
 keywords:
@@ -473,7 +473,7 @@ Link.displayName = "Link";
 通过在整个应用中集成此 `Link` 组件，您可以维护一致且具语言感知的用户体验，同时提升 SEO 和可用性。
 </Step>
 
-<Step number={1} title="提取组件内容" isOptional={true}>
+<Step number={11} title="提取组件内容" isOptional={true}>
 
 如果您有现有的代码库，转换数千个文件可能会非常耗时。
 

package/docs/zh/intlayer_with_vite+react_compiler.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2024-03-07
-updatedAt: 2026-05-31
+updatedAt: 2026-06-23
 title: "Vite + React i18n - 翻译你的应用的完整指南"
 description: "告别 i18next。2026 年构建多语言 (i18n) Vite + React 应用的完整指南。使用 AI 代理翻译并优化包体积、SEO 和性能。"
 keywords:
@@ -91,139 +91,6 @@ author: aymericzip
 
 ---
 
-## 在 Vite 和 React 应用程序中设置 Intlayer 的分步指南
-
-### 第 1 步：安装依赖项
-
-使用 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 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 国际化提供上下文提供者和钩子。
-
-- **vite-intlayer**
-  包括用于将 Intlayer 与 [Vite 构建器](https://vite.dev/guide/why.html#why-bundle-for-production)集成的 Vite 插件，以及用于检测用户首选语言、管理 cookie 和处理 URL 重定向的中间件。
-
-### 第 2 步：配置您的项目
-
-创建一个配置文件来配置应用程序的语言：
-
-```typescript fileName="intlayer.config.ts"
-import { Locales, type IntlayerConfig } from "intlayer";
-
-const config: IntlayerConfig = {
-  internationalization: {
-    locales: [
-      Locales.ENGLISH,
-      Locales.FRENCH,
-      Locales.SPANISH,
-      Locales.CHINESE,
-    ],
-    defaultLocale: Locales.ENGLISH,
-  },
-  compiler: {
-    /**
-     * 指示是否应启用编译器。
-     */
-    enabled: true,
-
-    /**
-     * 优化字典的输出目录。
-     */
-    output: ({ locale, key }) => `compiler/${locale}/${key}.json`,
-
-    /**
-     * 仅在生成的文件中插入内容，不含键。
-     */
-    noMetadata: false,
-
-    /**
-     * 字典键前缀
-     */
-    dictionaryKeyPrefix: "", // Remove base prefix
-
-    /**
-     * 指示转换后是否应保存组件。
-     * 这样，编译器只需运行一次即可转换应用程序，然后即可将其删除。
-     */
-    saveComponents: false,
-  },
-  ai: {
-    provider: "openai",
-    model: "gpt-5-mini",
-    apiKey: process.env.OPEN_AI_API_KEY,
-    applicationContext: "这个应用是一个地图应用", // 注意：您可以自定义此应用描述
-  },
-};
-
-export default config;
-```
-
-> **注意**：请确保在环境变量中设置了 `OPEN_AI_API_KEY`。
-
-> 通过此配置文件，您可以设置本地化 URL、中间件重定向、cookie 名称、内容声明的位置和扩展名、禁用控制台中的 Intlayer 日志等。有关可用参数的完整列表，请参阅 [配置文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/configuration.md)。
-
-### 第 3 步：在 Vite 配置中集成 Intlayer
-
-将 intlayer 插件添加到您的配置中。
-
-```typescript fileName="vite.config.ts"
-import { defineConfig } from "vite";
-import react from "@vitejs/plugin-react-swc";
-import { intlayer, intlayerCompiler } from "vite-intlayer";
-
-// https://vitejs.dev/config/
-export default defineConfig({
-  plugins: [react(), intlayer(), intlayerCompiler()],
-});
-```
-
-> `intlayer()` Vite 插件用于将 Intlayer 与 Vite 集成。它确保内容声明文件的构建并在开发模式下监控它们。它在 Vite 应用程序中定义 Intlayer 环境变量。此外，它提供别名以优化性能。
-
-> `intlayerCompiler()` Vite 插件用于从组件中提取内容并编写 `.content` 文件。
-
 ### 第 4 步：编译您的代码
 
 只需使用您的默认语言在组件中编写硬编码字符串。编译器会处理剩下的工作。
@@ -363,64 +230,6 @@ export default App;
 
 - **`IntlayerProvider`** 用于向嵌套组件提供语言环境。
 
-### （可选）第 6 步：更改内容的语言
-
-要更改内容的语言，您可以使用 `useLocale` 钩子提供的 `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.CHINESE)}>将语言更改为中文</button>
-  );
-};
-```
-
-> 要了解有关 `useLocale` 钩子的更多信息，请参阅 [文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/packages/react-intlayer/useLocale.md)。
-
-### (可选) 第 7 步：填充缺失的翻译
-
-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)
-
 ### （可选）站点地图与 robots.txt（构建时生成）
 
 Intlayer 提供 `generateSitemap` 与 `getMultilingualUrls`，可将面向爬虫的多语言 `sitemap.xml` 和 `robots.txt` 格式化并自动写入 `public/`。实践中在 Vite **之前**运行小型 Node 脚本（例如 npm 的 `predev` / `prebuild`）即可在构建或开发时生成这些文件。

package/docs/zh/intlayer_with_vite+solid.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2025-04-18
-updatedAt: 2026-05-31
+updatedAt: 2026-06-23
 title: "Vite + Solid i18n - 翻译你的应用的完整指南"
 description: "告别 i18next。2026 年构建多语言 (i18n) Vite + Solid 应用的完整指南。使用 AI 代理翻译并优化包体积、SEO 和性能。"
 keywords:
@@ -53,50 +53,6 @@ author: aymericzip
 
 <TOC/>
 
-> 该包正在开发中。更多信息请参见[issue](https://github.com/aymericzip/intlayer/issues/117)。通过点赞该 issue 来表达您对 Solid 版 Intlayer 的兴趣。
-
-<!-- 请参见 GitHub 上的[应用模板](https://github.com/aymericzip/intlayer-solid-template)。 -->
-
-## 为什么选择 Inlayer 而不是替代品？
-
-与“@solid-primitives/i18n”或“i18next”等主要解决方案相比，Intlayer是一个具有集成优化的解决方案，例如：
-
-**完全固体覆盖**
-
-Intlayer 经过优化，可与 Solid 完美配合，提供**组件级内容范围**、**反应式翻译**以及​​扩展国际化 (i18n) 所需的所有功能。
-
-**捆绑尺寸**
-
-不要将大量 JSON 文件加载到页面中，而只需加载必要的内容。 Intlayer 有助于**将捆绑包和页面大小减少多达 50%**。
-
-**可维护性**
-
-确定应用程序内容的范围**有利于大型应用程序的维护**。您可以复制或删除单个功能文件夹，而无需承担检查整个内容代码库的精神负担。此外，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)** 来帮助您管理多语言内容**实时**，与译员、文案人员和其他团队成员无缝协作。内容可以本地和/或远程存储。
-
----
-
-## 在 Vite 和 Solid 应用中设置 Intlayer 的分步指南
-
-## 目录
-
-<TOC/>
-
 ### 第一步：安装依赖
 
 使用 npm 安装所需的包：
@@ -409,193 +365,6 @@ const LocaleSwitcher: Component = () => {
 };
 ```
 
-### （可选）第9步：切换 HTML 的语言和方向属性
-
-更新 `<html>` 标签的 `lang` 和 `dir` 属性以匹配当前语言环境，以便于可访问性和 SEO。
-
-```tsx fileName="src/App.tsx" codeFormat="typescript"
-import { createEffect, type Component } from "solid-js";
-import { useLocale } from "solid-intlayer";
-import { getHTMLTextDir } from "intlayer";
-
-const AppContent: Component = () => {
-  const { locale } = useLocale();
-
-  createEffect(() => {
-    document.documentElement.lang = locale();
-    document.documentElement.dir = getHTMLTextDir(locale());
-  });
-
-  return (
-    // ... 您的应用程序内容
-  );
-};
-```
-
-<Steps>
-
-<Step number={10} title="创建本地化链接组件">
-
-创建一个自定义 `Link` 组件，自动为内部 URL 添加当前语言的前缀。
-
-```tsx fileName="src/components/Link.tsx" codeFormat="typescript"
-import { type ParentComponent } from "solid-js";
-import { A, type AnchorProps } from "@solidjs/router";
-import { getLocalizedUrl } from "intlayer";
-import { useLocale } from "solid-intlayer";
-
-export const Link: ParentComponent<AnchorProps> = (props) => {
-  const { locale } = useLocale();
-
-  const isExternal = () => props.href.startsWith("http");
-  const localizedHref = () =>
-    isExternal() ? props.href : getLocalizedUrl(props.href, locale());
-
-  return <A {...props} href={localizedHref()} />;
-};
-```
-
-</Step>
-
-<Step number={11} title="渲染 Markdown">
-
-Intlayer 支持使用其自己的内部解析器直接在您的 Solid 应用程序中渲染 Markdown 内容。默认情况下，Markdown 被视为纯文本。要将其渲染为富 HTML，请用 `MarkdownProvider` 包装您的应用程序。
-
-```tsx fileName="src/index.tsx"
-import { render } from "solid-js/web";
-import { MarkdownProvider } from "solid-intlayer/markdown";
-import App from "./App";
-
-const root = document.getElementById("root");
-
-render(
-  () => (
-    <MarkdownProvider>
-      <App />
-    </MarkdownProvider>
-  ),
-  root!
-);
-```
-
-然后您可以在组件中使用它：
-
-```tsx
-import { useIntlayer } from "solid-intlayer";
-
-const MyComponent = () => {
-  const content = useIntlayer("my-content");
-
-  return (
-    <div>
-      {/* 通过 MarkdownProvider 渲染为 HTML */}
-      {content.markdownContent}
-    </div>
-  );
-};
-```
-
-</Step>
-
-<Step number={1} title="提取组件内容" isOptional={true}>
-
-如果您有现有的代码库，转换数千个文件可能会非常耗时。
-
-为了简化此过程，Intlayer 提出了 [编译器](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/compiler.md) / [提取器](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/cli/extract.md) 来转换您的组件并提取内容。
-
-要进行设置，您可以在 `intlayer.config.ts` 文件中添加 `compiler` 部分：
-
-```typescript fileName="intlayer.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
-import { type IntlayerConfig } from "intlayer";
-
-const config: IntlayerConfig = {
-  // ... 您的其他配置
-  compiler: {
-    /**
-     * 指示是否应启用编译器。
-     */
-    enabled: true,
-
-    /**
-     * 定义输出文件路径
-     */
-    output: ({ fileName, extension }) => `./${fileName}${extension}`,
-
-    /**
-     * 指示在转换后是否应保存组件。这样，编译器只需运行一次即可转换应用程序，然后即可将其删除。
-     */
-    saveComponents: false,
-
-    /**
-     * 字典键前缀
-     */
-    dictionaryKeyPrefix: "",
-  },
-};
-
-export default config;
-```
-
-<Tabs>
- <Tab value='提取命令'>
-
-运行提取器以转换组件并提取内容
-
-```bash packageManager="npm"
-npx intlayer extract
-```
-
-```bash packageManager="pnpm"
-pnpm intlayer extract
-```
-
-```bash packageManager="yarn"
-yarn intlayer extract
-```
-
-```bash packageManager="bun"
-bun x intlayer extract
-```
-
- </Tab>
- <Tab value='Babel 编译器'>
-
-更新您的 `vite.config.ts` 以包含 `intlayerCompiler` 插件：
-
-```ts fileName="vite.config.ts"
-import { defineConfig } from "vite";
-import { intlayer, intlayerCompiler } from "vite-intlayer";
-
-export default defineConfig({
-  plugins: [
-    intlayer(),
-    intlayerCompiler(), // 添加编译器插件
-  ],
-});
-```
-
-```bash packageManager="npm"
-npm run build # 或 npm run dev
-```
-
-```bash packageManager="pnpm"
-pnpm run build # 或 pnpm run dev
-```
-
-```bash packageManager="yarn"
-yarn build # 或 yarn dev
-```
-
-```bash packageManager="bun"
-bun run build # Or bun run dev
-```
-
- </Tab>
-</Tabs>
-</Step>
-
-</Steps>
-
 ### 配置 TypeScript
 
 确保您的 TypeScript 配置包含自动生成的类型。
@@ -637,80 +406,6 @@ bun run build # Or bun run dev
 
 ---
 
-### （可选）站点地图与 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 或其他步骤中调用该脚本。
-
 ### 深入了解
 
 要进一步使用，您可以实现[可视化编辑器](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)将内容外部化。