# Chinese Documentation

中文文档排版参考, , 中英文空格、全半角标点、术语保留、链接格式、中文文案排版指北约定。仅在用户显式 /chinese-documentation 时调用，不要根据上下文自动触发。

- Repository: https://github.com/jnMetaCode/superpowers-zh (8437 stars)
- Category: Writing
- License: MIT
- Last updated: 2026-10-26
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add jnMetaCode/superpowers-zh --skill chinese-documentation -g -a claude-code -y`
Codex: `npx skills add jnMetaCode/superpowers-zh --skill chinese-documentation -g -a codex -y`
Cursor: `npx skills add jnMetaCode/superpowers-zh --skill chinese-documentation -g -a cursor -y`
Gemini CLI: `npx skills add jnMetaCode/superpowers-zh --skill chinese-documentation -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add jnMetaCode/superpowers-zh`

## Description

中文文档排版参考, , 中英文空格、全半角标点、术语保留、链接格式、中文文案排版指北约定。仅在用户显式 /chinese-documentation 时调用，不要根据上下文自动触发。

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 中文技术文档写作规范

## 概述

中文技术文档最常见的问题不是内容不够，而是**读起来别扭**, , 中英文挤在一起没有空格、全角半角混用、一股机翻味。本技能提供一套完整的中文技术文档写作规范，让你的文档**专业、好读、不出戏**。

**核心原则：** 排版服务于阅读体验，规范服务于一致性，内容服务于读者。

**参考标准：** [中文文案排版指北](https://github.com/sparanoid/chinese-copywriting-guidelines)

## 中文排版规范

### 空格

**中英文之间加空格：**

```
# 好
使用 Git 进行版本管理，配合 Jenkins 实现持续集成。

# 坏
使用Git进行版本管理，配合Jenkins实现持续集成。
```

**中文与数字之间加空格：**

```
# 好
本次更新包含 3 个新功能和 12 个 Bug 修复。

# 坏
本次更新包含3个新功能和12个Bug修复。
```

**数字与单位之间加空格：**

```
# 好
文件大小不超过 5 MB，响应时间控制在 200 ms 以内。

# 坏
文件大小不超过5MB，响应时间控制在200ms以内。
```

**例外：度数、百分比等不加空格：**

```
# 好
今天气温 32°C，CPU 使用率 95%。

# 坏
今天气温 32 °C，CPU 使用率 95 %。
```

**链接前后加空格：**

```
# 好
请参考 [官方文档](https://example.com) 获取更多信息。

# 坏
请参考[官方文档](https://example.com)获取更多信息。
```

### 标点符号

**中文语境使用全角标点：**

```
# 好
注意：该接口需要鉴权，请先获取 Token。

# 坏
注意:该接口需要鉴权,请先获取 Token.
```

**全角标点与英文/数字之间不加空格：**

```
# 好
项目使用 MIT 协议，详见 LICENSE 文件。

# 坏
项目使用 MIT 协议 ，详见 LICENSE 文件 。
```

**括号的使用：**

```
# 中文语境用全角括号
请运行安装命令（详见下方说明）。

# 括号内有英文或数字时用半角括号
该项目基于 Spring Boot (v3.2.0) 开发。

# 纯英文内容用半角括号
See the documentation (README.md) for details.
```

**引号的使用：**

```
# 中文使用直角引号（推荐）
「确定」按钮触发表单提交，「取消」按钮关闭弹窗。

# 也可以使用弯引号（视团队规范而定）
"确定"按钮触发表单提交，"取消"按钮关闭弹窗。

# 嵌套引号
他说：「请点击『确定』按钮。」
```

### 数字

```
# 阿拉伯数字（技术文档中统一使用半角数字）
支持最多 100 个并发连接。

# 不要用中文数字写技术参数
# 坏：支持最多一百个并发连接。

# 数字使用半角字符
版本号 v2.1.0，端口号 8080，HTTP 状态码 200。
```

## 中英混排最佳实践

### 术语处理原则

**保留英文的情况：**

- 专有名词：React、Kubernetes、Redis、MySQL
- 行业通用缩写：API、SDK、CLI、ORM、CI/CD
- 命令和代码：`npm install`、`git commit`
- 协议和标准：HTTP、TCP/IP、JSON、REST
- 没有公认中文翻译的术语：debounce、throttle、middleware

**翻译为中文的情况：**

- 有公认翻译的通用概念：数据库、服务器、浏览器、框架
- 描述性短语：version control → 版本控制，load balancing → 负载均衡
- 文档标题和章节名（尽量中文，技术名词可保留英文）

### 首次出现标注翻译

技术术语首次出现时，标注中英对照：

```
# 好
本系统采用消息队列（Message Queue）实现异步通信，
使用死信队列（Dead Letter Queue）处理消费失败的消息。

# 后续出现直接使用
消息队列的消费者需要实现幂等性……
```

### 避免过度翻译

```
# 好：保留业界通用英文术语
在 Controller 层做参数校验，Service 层处理业务逻辑。

# 坏：强行翻译反而看不懂
在控制器层做参数校验，服务层处理业务逻辑。

# 好
使用 Redis 做 Session 缓存。

# 坏
使用"远程字典服务"做"会话"缓存。
```

The rest: https://github.com/jnMetaCode/superpowers-zh/blob/HEAD/skills/chinese-documentation/SKILL.md