translate

英文文档目录与结构约定

基础假设
- 本仓库使用 Docusaurus 3（classic preset）+ docs/ 作为默认中文文档目录。
- 计划使用 Docusaurus 官方 i18n 机制，为英文文档使用单独目录：i18n/en/docusaurus-plugin-content-docs/current/。

i18n 配置示例（放在 docusaurus.config.js 中 i18n 字段）

i18n: {
  defaultLocale: 'zh-Hans',                  // 默认中文
  locales: ['zh-Hans', 'en'],                // 启用中/英
  localeConfigs: {
    'zh-Hans': {
      label: '简体中文',
    },
    en: {
      label: 'English',
    },
  },
},

导航栏中启用语言切换按钮（写在 themeConfig.navbar.items）：

        {
          type: 'localeDropdown',
          position: 'right',
        },

英文文档目录创建方案

中文源文档目录（已存在）
- 根目录：docs/
- 当前主要子结构（示例）：
  - docs/00.intro.md
  - docs/01.Industry-Solution-Boards/
  - docs/02.CoreBoard&AI-BOX/
  - docs/03.Dongle/
  - docs/05.guide/
  - docs/06.Software/
  - docs/90.specifications/
  - docs/91.Linux/
  - docs/92.buildsystem/
  - docs/93.Device/
  - docs/99.Other/
  - docs/images/（公共图片）
英文目标目录（建议）
- 根目录：i18n/en/docusaurus-plugin-content-docs/current/
- 结构与 docs/ 完全镜像，例如：
  - i18n/en/docusaurus-plugin-content-docs/current/00.intro.md
  - i18n/en/docusaurus-plugin-content-docs/current/01.Industry-Solution-Boards/...
  - i18n/en/docusaurus-plugin-content-docs/current/02.CoreBoard&AI-BOX/...
  - 依此类推。

一次性创建英文目录与初始文件（推荐命令）

在项目根目录执行：

# 1. 创建英文 docs 根目录
mkdir -p i18n/en/docusaurus-plugin-content-docs/current

# 2. 将现有中文 docs 结构整体拷贝一份作为英文初稿
rsync -av \
  --exclude 'images/' \
  docs/ \
  i18n/en/docusaurus-plugin-content-docs/current/

# 如需英文也直接复用图片，可额外拷贝（可选）
rsync -av docs/images/ i18n/en/docusaurus-plugin-content-docs/current/images/

这样会得到一套完全同名同结构的英文文档文件，仅内容仍为中文，方便逐篇人工翻译。
所有 _category_.json、sidebar_position、id 等元信息都会被保留，保证中英文侧边栏结构保持一致。

翻译规则与注意事项

1. 前置元数据（Front Matter）处理

保持以下字段原样不动：
- id
- slug
- sidebar_position
- 任何用于路由、锚点的技术字段
可以翻译的字段：
- title: 建议翻译成自然、简洁的英文标题
- description: 翻译为简短英文摘要

示例：

---
id: dc2290_intro
title: DC2290 产品简介        # 中文
sidebar_position: 1
---

英文版建议改为：

---
id: dc2290_intro
title: DC2290 Product Introduction
sidebar_position: 1
---

2. 文件名与路径

建议：当前阶段保持文件名与目录名不变（例如仍然使用 01.产品简介.md、02.升级准备.md），只翻译文件内容。
- 原因：
  - 避免改名导致链接失效。
  - 中英文版本通过 Docusaurus i18n 自动映射，只要相对路径一致即可。
如将来确需英文文件名，可以单独做一次“重构”，并统一调整所有内部链接。

3. 链接与图片

内部链接
- [](/docs/xxx) 这类绝对路径：不要改路径，只在需要时翻译链接文本。
- 相对链接（如 ./01.xxx.md）：若目录结构未改变，一般无需改动。
外部链接
- 不要翻译 URL 本身，只翻译说明文字。
图片与 iframe
- ![图片](...) / <img ...> / <iframe ...> 中的路径、查询参数全部保持不变。
- 仅在需要时，翻译紧挨着的说明文字或标题。

4. HTML / MDX 片段

文档中可能包含：
- <table>...</table>
- 自定义 <div class="...">
- :::note / :::tip / :::warning 等 Docusaurus 提示块
- 甚至 React 组件、MDX 语法
翻译原则：
- 只翻译可见文本，不改标签结构。
- 不要删除、修改 class=""、id=""、href="" 等属性。

示例：

:::note[信息]

带有超链接的平台名称表明该产品的 Wiki 已上线。

:::

英文版推荐：

:::note[Info]

Platform names with hyperlinks indicate that the product Wiki is already online.

:::

5. 技术术语与产品名

产品型号、板卡名称（如 DC2290、IM2290、GT865-RB5）——完全保留原样。
芯片型号、协议、标准名：QCM6125、Android 14、Wi‑Fi 6、RJ45 等，均不翻译。
中文修饰语可以翻译，例如：
- 高通性价比 → Qualcomm cost-effective
- 4K 闺蜜机 → 4K Companion Machine
- AI 解决方案主板 → AI solution board

建议在整个站点中，对相同中文术语保持统一英文译法，可以在后续维护一个对照表（术语表）。

6. 表格与列表

Markdown 表格：
- 只翻译单元格内的中文文案。
- 不增加、不减少行列，避免表格错位。
列表：
- 保持列表结构（- / 1.）不变，仅翻译文本。

7. 代码块与命令

代码块（如 ```bash、 ```json）中的内容一般不翻译：
- 命令、路径、参数保持原样。
- 如有注释，可适当翻译注释部分。

示例：

# 烧录镜像
fastboot flash system system.img

英文版可以改为：

# Flash the system image
fastboot flash system system.img

8. 翻译流程建议

推荐流程
1. 执行前文的 rsync 命令，生成英文文档目录的初始拷贝。
2. 约定一个翻译顺序（例如从 00.intro.md → 各产品 preface → 常用指南 → 规格文档）。
3. 每翻译完一篇：
  - 自查：格式是否完整、链接是否正常。
  - 在浏览器中通过语言切换对比中英文效果。
4. 重要页面（官网入口、首页、关键产品页）建议二次人工审校。
协作建议
- 若多人协作：
  - 每人认领一部分路径（例如某几个产品目录）。
  - 使用 Git 分支 + PR，将翻译审核后再合并。

检查与预览

本地开发时，在项目根目录执行：

npm install              # 或 yarn
npm run start            # 或 yarn start（默认按 defaultLocale=中文 启动）

仅预览英文版本

Docusaurus 支持通过 --locale 参数只启动某个语言版本，例如只看英文：

# 等价于你脚本 start.sh 里注释掉的那一行
npm run start -- --locale en --host 0.0.0.0 --port 8000

英文版图片不想复制一份怎么处理（推荐）

当英文内容放到 i18n/en/docusaurus-plugin-content-docs/current/ 后，很多文档里使用了类似：

![xxx](../../../../images/rv1126/RV1126_port01.png)

这种相对路径图片引用。如果 i18n/en/.../current/ 下没有 images/ 目录，Docusaurus 在编译英文文档时会把路径解析到英文目录里，从而报错 “couldn't be resolved to an existing local image file”。

如果你不希望复制一份 images，最省事且推荐的做法是创建一个软链接：

mkdir -p i18n/en/docusaurus-plugin-content-docs/current
ln -s docs/images i18n/en/docusaurus-plugin-content-docs/current/images

这样英文文档仍然可以用原来的相对路径引用 images/...，但实际读取的是中文 docs/images/ 下的同一份图片资源。

浏览器中：
- 默认以 zh-Hans（中文）显示。
- 使用右上角语言切换菜单选择 English，即可预览英文文档。
- 若某篇文档尚未提供英文版本，Docusaurus 会自动回退显示默认语言（中文）。

以上约定保证：

中文 docs/ 作为单一事实源（Single Source of Truth）。
英文文档在 i18n/en/... 内，与中文结构一一对应，易于维护。
不破坏现有路由、侧边栏与链接的前提下，逐步补齐英文内容。

英文文档目录与结构约定​

英文文档目录创建方案​

翻译规则与注意事项​

1. 前置元数据（Front Matter）处理​

2. 文件名与路径​

3. 链接与图片​

4. HTML / MDX 片段​

5. 技术术语与产品名​

6. 表格与列表​

7. 代码块与命令​

8. 翻译流程建议​

检查与预览​

英文版图片不想复制一份怎么处理（推荐）​