AI

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141

# 章节翻译与 Docsy/Hugo 站点生成规范

## 1. 输入与输出

- 输入源：`[源链接/文件路径]`，按左侧章节顺序识别所有章节。
- 只处理指定范围内的内容（例如“只需要 The Swift Programming Language 下的内容”“只需要 Package Manager 下的内容”），不要把导航里其他文档混进来。
- 输出目录：`[目标输出目录]`，所有新生成的文件和目录都放在该目录下。
- 所有原始下载的章节源码必须保留，不得删除或覆盖。

## 2. 总体要求

- 每个章节生成一个独立的 Markdown 文件。
- 最终文件层级必须符合 Docsy 主题要求。
- 所有目录名只能使用英文，并且不能包含空格、标点符号等特殊字符。
- 必须在 hugo 头部信息之后加上两个空行，之后再添加：`> 原文链接: [http链接](http链接)`，其中 http 链接就是该网页本身。
- 翻译时只依据英文原文，不得参考或复制任何已有中文网站翻译。
- 代码块保持原样，不翻译代码本身；代码块中的注释需要翻译为中文。
- 代码块的语言标记必须正确，不能包含 `.`、`,` 等符号。
- 注意保持 Markdown 标题层级正确。
- 处理好章节序号和图片链接、章节内的链接。
- 若大章节没有对应网页，则也必须创建 `_index.md`，但保持 `_index.md` 的内容为空，除了相关 Hugo 头部信息；切记不要把小章节的内容放到 `_index.md` 中。

## 3. Hugo 头部信息

每个 Markdown 文件开头必须添加：

```markdown
+++
title = "章节序号 章节标题"
date = <当前北京时间，格式：2026-04-03T11:12:24+08:00>
weight = <权重数字>
type = "docs"
description = ""
isCJKLanguage = true
draft = false
+++
```

要求：

- `title` 必须包含章节序号和翻译后的中文章节标题，并与正文里的一级标题一致（如 `# 3.6 声明` ↔ `title = "3.6 声明"`）。
- `date` 使用执行任务时的北京时间，并保持 `+08:00` 时区偏移。
- `weight` 按章节顺序递增，确保所属层级内顺序正确（子页面在每个父目录内从 1 开始单独递增）。
- `type` 固定为 `"docs"`。
- 头部信息之后空两行，再写 `> 原文链接: [链接](链接)`。

## 4. Docsy/Hugo 站内链接规范（务必遵守）

- 禁止在链接目标中写 `.md` 扩展名。
- 链接目标末尾必须带 `/`（目录式 URL）。
- 禁止使用以 `/` 开头的站点绝对路径（如 `/NewnewRustLearning/...`），一律用相对路径。
- 相对路径的「当前位置」是当前页面的 Hugo URL 目录，不是 `.md` 文件所在的父文件夹：
  - 普通页面 `foo/bar.md` → 当前 URL 为 `foo/bar/`
  - 章节索引 `foo/_index.md` → 当前 URL 为 `foo/`
- 计算 `../` 个数时：从当前页面 URL 出发，逐级回到共同祖先，再进入目标页面 URL。
- 同级页面（同一父目录下的两个 `.md` 页面）也要先 `../` 再写目标名，例如从 `dyn-trait/4.1-overview/` 到 `dyn-trait/4.8-dyn-any/` 应写 `../4.8-dyn-any/`，不能写 `4.8-dyn-any/`。
- 锚点写在末尾：`../4.3-coercions/#associated-types`；链接中出现锚时，`#anchor` 前面必须有 `/`，例如 `[参见链接](../../linkPage/#my-anchor)`。
- 链接目标的大小写必须与真实目录完全一致（目录用全小写，如 `swiftcommands/`、`languageguide/`）。macOS 文件系统不区分大小写，必须专门做一遍大小写敏感的检查，否则部署到 GitHub Pages 之类的服务器上会 404。

## 5. 文件组织规则

### 大章节

- 以章节英文名创建目录，目录名必须去除空格和标点符号，并统一使用小写英文。
- 在该目录下创建 `_index.md`，放置该大章节的概述或主要内容（若该大章节确有对应网页）。
- `_index.md` 同样需要添加 Hugo 头部信息。
- 若大章节没有对应网页，则也必须创建 `_index.md`，但保持其内容为空，除了相关 Hugo 头部信息；切记不要把小章节的内容放到 `_index.md` 中。

### 小章节

- 文件命名为：`<章节序号>-<章节名称>.md`（如 `2.14-Initialization.md`、`3.1.2-PackageTraits.md`）。
- 章节序号不需要有前导零。
- 如果小章节隶属于某个大章节，则将文件放入对应大章节目录下。
- 文件开头添加 Hugo 头部信息。

### 子章节

- 若章节下还有子章节，需要：
  1. 先以子章节英文名创建目录，目录名去除空格和标点符号；
  2. 在该目录下创建 `_index.md`（放该子章节自身的页面内容，有对应网页时）；
  3. 再创建相关子章节的 Markdown 文件；
  4. 保持 Docsy 的层级关系。

## 6. 内容翻译与处理

- 正文内容根据英文原文翻译成中文；不得直接复制中文网页版本内容。
- **标题必须翻译成中文**。只允许下列情况保留英文：
  - 语言关键字：`if`、`switch`、`while`、`repeat-while`、`for-in`、`guard`、`defer`、`break`、`continue`、`return`、`throw`、`where`；
  - 类型与系统名：`Int`、`UInt`、`nil`、`actor`、`Unicode`、`Sendable`、`NSApplicationMain` 等；
  - `@` 特性名与指令名：`objc`、`propertyWrapper`、`attached`、`available`、`header`、`config_macros` 等；
  - 命令行页的一级标题（如 `7.3.1 swift package init`）。
  - 其余描述性标题（如 “Overview”“Failable Initializers”“Add resource files”）一律译为中文，且**每次新增章节后都要复查一遍**，这是最容易漏的一项。
- 原文中的锚需要加到翻译后的标题后面，例如原文标题里有 `#my-anchor`，则写成 `## 中文标题 {#my-anchor}`，`{#...}` 要紧跟在标题同一行的末尾，不能换行。
- 代码块不翻译，仅将代码块中的注释翻译为中文。
- 链接统一使用相对路径，不要写 `.md`，并注意相对路径中应该出现多少个 `../`。
- 检查并修正章节序号，确保连续、正确。
- 检查链接和锚：
  - 外部链接确保可访问；
  - 相对路径需要根据新的目录结构调整，必须确保 Docsy Hugo 主题下相对路径正确；
  - 锚点必须在目标页面中真实存在。

## 7. 图片与其它附件的处理规则（重点）

- **每个大章节目录下都要有一个 `images` 目录**，把该大章节用到的图片全部下载/复制进各自的 `images` 目录中，不允许外链原站图片。
- 图片引用统一写成：`./images/图片名.后缀名`，例如：

  ```markdown
  ![](./images/barcode_UPC.png)
  ```

- 目录结构示意：

  ```
  languageguide/
  ├── 2.8-Enumerations.md
  ├── 2.29-AdvancedOperators.md
  └── images/
      ├── barcode_UPC.png
      └── bitwiseNOT.png
  ```

- 图片规则**不适用**站内页面链接那套「按 URL 目录算 `../`」的规则：图片按 `.md` 文件真实位置解析，同一个大章节的图片用 `./images/…` 引用即可；不要写成 `../images/…`，也不要用站点绝对路径。
- 非图片附件（yaml、json、svg、zip 等）放在 `大章节/<章节文件名>/附件名` 下，并用 `./附件名` 引用。
- 生成后逐个核对：每一条图片/附件引用都要指向真实存在的文件（并且大小写一致）。
- 站点模板 `render-image.html` 会用「当前 md 文件所在目录 + 目标路径」拼接图片地址，`../` 会被 `relURL` 丢弃，所以对共享图片目录而言 `./images/…` 才是能正常显示的写法。

## 8. 校验要求

- 建立英文中间稿（prepared），保留标题锚点、代码块、链接、图片、段落/列表结构。
- 生成后用脚本逐章比对：标题锚点与层级、代码块数量及非注释内容、链接目标、图片引用、段落与列表项数量。
- 单独做一遍**大小写敏感**的链接检查与图片存在性检查。
- 全部章节通过后，再检查一遍是否有残留英文标题或英文段落。

## 9. 执行流程

1. 读取并识别输入源中的章节顺序。
2. 按顺序为每个章节创建目录和 Markdown 文件。
3. 为每个 Markdown 文件添加符合规范的 Hugo 头部信息。
4. 翻译内容，并处理章节序号、图片链接和相关章节内链接等问题。
5. 检查全部章节是否齐备、是否还有未翻译内容，确认无误。
6. 保留所有下载的章节源码。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99

请按照以下规范处理指定的章节源码，并生成符合 Docsy Hugo 主题的 Markdown 文件。

## 1. 输入与输出
- 输入源：`[源链接/文件路径]`，按左侧章节顺序识别所有章节。
- 输出目录：`[目标输出目录]`，所有新生成的文件和目录都放在该目录下。
- 所有原始下载的章节源码必须保留，不得删除或覆盖。

## 2. 总体要求
- 每个章节生成一个独立的 Markdown 文件。
- 最终文件层级必须符合 Docsy 主题要求。
- 所有目录名只能使用英文，并且不能包含空格、标点符号等特殊字符。
- 必须在hugo头部信息之后加上两个空行,之后再添加: > 原文链接: [http链接](http链接) 其中http链接就是该网页!
- 翻译时只依据英文原文，不得参考或复制任何已有中文网站翻译。
- 代码块保持原样，不翻译代码本身；代码块中的注释需要翻译为中文。
- 注意保持 Markdown 标题层级正确。
- 处理好章节序号和图片链接、章节内的链接。
- 若大章节没有对应网页, 则也必须创建`_index.md`,但保持`_index.md`的内容为空, 除了相关Hugo头部信息, 切记不要把小章节的内容放到`_index.md`中。

## 3. Hugo 头部信息
每个 Markdown 文件开头必须添加以下 Hugo 头部信息：

```markdown
+++
title = "章节序号 章节标题"
date = <当前北京时间，格式：2026-04-03T11:12:24+08:00>
weight = <权重数字>
type = "docs"
description = ""
isCJKLanguage = true
draft = false
+++
```

要求：
- `title` 必须包含章节序号和翻译后的中文章节标题。
- `date` 使用执行任务时的北京时间，并保持 `+08:00` 时区偏移。
- `weight` 按章节顺序递增，确保所属层级内顺序正确。
- `type` 固定为 `"docs"`。


## Docsy/Hugo 站内链接规范（务必遵守）：

- 禁止在链接目标中写 `.md` 扩展名。
- 链接目标末尾必须带 `/`（目录式 URL）。
- 禁止使用以 `/` 开头的站点绝对路径（如 `/NewnewRustLearning/...`），一律用相对路径。
- 相对路径的「当前位置」是当前页面的 Hugo URL 目录，不是 .md 文件所在的父文件夹：
	- 普通页面 `foo/bar.md` → 当前 URL 为 `foo/bar/`
	- 章节索引 `foo/_index.md` → 当前 URL 为 `foo/`
- 计算 `../` 个数时：从当前页面 URL 出发，逐级回到共同祖先，再进入目标页面 URL。
- 同级页面（同一父目录下的两个 `.md` 页面）也要先 `../` 再写目标名，例如从 `dyn-trait/4.1-overview/` 到 `dyn-trait/4.8-dyn-any/` 应写 `../4.8-dyn-any/`，不能写 `4.8-dyn-any/`。
- 锚点写在末尾：`../4.3-coercions/#associated-types`。

## 4. 文件组织规则

### 大章节
- 以章节英文名创建目录，目录名必须去除空格和标点符号。
- 在该目录下创建 `_index.md`，放置该大章节的概述或主要内容。
- `_index.md` 同样需要添加 Hugo 头部信息。
- 若大章节没有对应网页, 则也必须创建`_index.md`,但保持`_index.md`的内容为空, 除了相关Hugo头部信息, 切记不要把小章节的内容放到`_index.md`中。
- 若大章节没有对应网页, 则也必须创建`_index.md`,但保持`_index.md`的内容为空, 除了相关Hugo头部信息, 切记不要把小章节的内容放到`_index.md`中。
- 若大章节没有对应网页, 则也必须创建`_index.md`,但保持`_index.md`的内容为空, 除了相关Hugo头部信息, 切记不要把小章节的内容放到`_index.md`中。


### 小章节
- 文件命名为：`<章节序号><章节名称>.md`。
- 章节序号不需要有前导零。
- 如果小章节隶属于某个大章节，则将文件放入对应大章节目录下。
- 文件开头添加 Hugo 头部信息。

### 子章节
- 若章节下还有子章节，需要：
  1. 先以子章节英文名创建目录，目录名去除空格和标点符号。
  2. 在该目录下创建 `_index.md`。
  3. 再创建相关子章节的 Markdown 文件。
  4. 保持 Docsy 的层级关系。


## 5. 内容翻译与处理
- 正文内容根据英文原文翻译成中文。
- 不得直接复制中文网页版本内容。
- 代码块不翻译，仅将代码块中的注释翻译为中文。
- 代码块的类型必须正确, 不能包含`.`和`,`等符号。
- 保持原有标题层级结构，并根据 Markdown 规范调整。
- 原文中的锚需要加到翻译后的相关标题后面, 例如原文中标题中存在有#my-anchor的锚, 则需要将{#my-anchor} 加到对应翻译后标题的后面,注意不是紧邻翻译后的标题的后面, 而不是换行之后的后面。
- 链接中使用相对路径, 需要注意若引用的是其他文件中的内容, 则实际本文件是放在一个目录中的
- 链接使用相对路径时,不能也不要写 `.md`, 并且需要注意相对路径中应该出现多少个`../`。
- 链接中出现锚, 则类似: [参见链接](../../linkPage/#my-anchor) 才是正确写法, 也就是在`#my-anchor`前面需要有`/`。
- 检查并修正章节序号，确保连续、正确。
- 检查链接和锚：
  - 外部链接确保可访问；
  - 相对路径需要根据新的目录结构调整，注意我使用的是Docsy Hugo主题! 必须确保相对路径正确；
  - 如有本地图片资源，放入合适目录并更新引用路径。

## 6. 执行流程
1. 读取并识别输入源中的章节顺序。
2. 按顺序为每个章节创建目录和 Markdown 文件。
3. 为每个 Markdown 文件添加符合规范的 Hugo 头部信息。
4. 翻译内容，并处理章节序号、图片链接和相关章节内链接等问题。
5. 保留所有下载的章节源码。