Skip to content

Commit 7ce8721

Browse files
ysyneuclaude
ysyneu
and
claude
committed
feat: add translate skill for Claude Code with image-aware retranslation
Add .claude/skills/translate-zh-to-en with image handling logic that preserves English-specific screenshots when retranslating. Also add CLAUDE.md project instructions and .gitignore for generated files. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
1 parent 61b89bc commit 7ce8721

4 files changed

Lines changed: 377 additions & 0 deletions

File tree

‎.claude/skills/translate-zh-to-en/SKILL.md‎

Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
---
2+
name: translate-zh-to-en
3+
description: Translate Chinese documentation to English following the terminology glossary. Use when translating documents from zh/ to en/, or when the user mentions Chinese to English translation.
4+
---
5+
6+
# Translate Chinese to English
7+
8+
Translate documents from `zh/` directory to `en/` directory.
9+
10+
## Quick Start
11+
12+
1. Detect target files (see below)
13+
2. Read glossary: [glossary.md](glossary.md)
14+
3. Translate document content
15+
4. Save to corresponding `en/` path
16+
17+
## Target File Detection
18+
19+
**Default behavior**: Check for uncommitted changes in `zh/` directory.
20+
21+
```bash
22+
git diff --name-only HEAD -- 'zh/*.mdx'
23+
git diff --name-only --cached -- 'zh/*.mdx'
24+
```
25+
26+
If uncommitted `.mdx` files exist in `zh/`:
27+
- List the detected files
28+
- Confirm with user before proceeding
29+
30+
If no uncommitted changes:
31+
- Ask user to specify the document path(s)
32+
- Example: "Which document would you like to translate? (e.g., zh/platform/xxx.mdx)"
33+
34+
## Translation Rules
35+
36+
### Language Quality
37+
38+
- **Professional & concise**: Avoid Chinglish, use native English expressions
39+
- **Grammatically correct**: Ensure proper sentence structure
40+
- **Consistent**: Use the same terminology throughout the document
41+
42+
### Formatting
43+
44+
- **Sentence case**: Capitalize only the first letter of titles/sentences
45+
- **Punctuation**: Add proper punctuation for complete sentences
46+
- **Variables**: Keep placeholder order unchanged
47+
48+
### Structure Preservation
49+
50+
| Element | Handling |
51+
|---------|----------|
52+
| YAML frontmatter | Translate `title` and `description` |
53+
| MDX components | Keep tags unchanged, translate inner text |
54+
| Code blocks | Keep code unchanged, translate comments only |
55+
| Internal links | Update path prefix to `en/` |
56+
| Image paths | See **Image Handling** below |
57+
58+
### Image Handling
59+
60+
When translating, check whether the target `en/` file already exists:
61+
62+
- **New translation** (no existing en/ file): Keep image paths from the zh/ source as-is.
63+
- **Retranslation** (en/ file already exists): Compare image paths between the zh/ source and the existing en/ file. Some docs use **language-specific screenshots** (English UI screenshots in en/, Chinese UI screenshots in zh/) with different CDN hashes. If the existing en/ file has a different image URL at the same position, **keep the en/ version** — it is likely an English screenshot that should not be replaced with the Chinese one. Only adopt the zh/ image path if it is a newly added image with no en/ counterpart.
64+
65+
**How to check**: Before writing the translated file, read the existing en/ file and diff the image URLs. Images with identical URLs across both versions are language-neutral and safe to keep. Images with different URLs (different hash in the CDN path) are language-specific — preserve the en/ version.
66+
67+
## Example
68+
69+
**Input** `zh/on-call/escalate.mdx`:
70+
71+
```mdx
72+
---
73+
title: "配置分派策略"
74+
description: "了解如何配置分派策略来管理故障升级"
75+
---
76+
77+
## 概述
78+
79+
分派策略定义了告警如何分配给处理人员。
80+
81+
<Note>
82+
建议至少配置两个环节的分派策略。
83+
</Note>
84+
```
85+
86+
**Output** `en/on-call/escalate.mdx`:
87+
88+
```mdx
89+
---
90+
title: "Configure escalation rules"
91+
description: "Learn how to configure escalation rules to manage incident escalation"
92+
---
93+
94+
## Overview
95+
96+
Escalation rules define how alerts are assigned to responders.
97+
98+
<Note>
99+
It is recommended to configure at least two levels of escalation rules.
100+
</Note>
101+
```
102+
103+
## Key Terminology
104+
105+
Always read the full glossary before translating: [glossary.md](glossary.md)
106+
107+
**Quick reference**:
108+
109+
| Chinese | English |
110+
|---------|---------|
111+
| 协作空间 | channel |
112+
| 故障 | incident |
113+
| 告警 | alert |
114+
| 分派策略 | escalation rule |
115+
| 处理人员 | responders |
116+
| 认领 | acknowledge |
117+
| 值班表 | schedule |
118+
119+
## Checklist
120+
121+
- [ ] Check git diff for uncommitted zh/ files
122+
- [ ] Read terminology glossary
123+
- [ ] Translate frontmatter (title, description)
124+
- [ ] Use correct terminology
125+
- [ ] Preserve MDX component structure
126+
- [ ] Update internal link paths
127+
- [ ] Check existing en/ file for language-specific images before overwriting
128+
- [ ] Apply Sentence case capitalization
129+
- [ ] Verify output path mirrors source path

‎.claude/skills/translate-zh-to-en/glossary.md‎

Lines changed: 165 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,165 @@
1+
# Flashduty Terminology Glossary
2+
3+
Chinese-English terminology mapping. Maintain consistency during translation.
4+
5+
## Core Concepts
6+
7+
| Chinese | English | Notes |
8+
|---------|---------|-------|
9+
| 协作空间 | channel | Team workspace |
10+
| 故障 | incident | Event requiring response |
11+
| 告警 / 报警 | alert | Monitoring system notification |
12+
| 集成来源 / 数据源 | integration | Alert data source |
13+
14+
## Incident Management
15+
16+
| Chinese | English |
17+
|---------|---------|
18+
| 分派 | assign |
19+
| 分派策略 | escalation rule |
20+
| 故障升级 | escalation |
21+
| 认领 | acknowledge |
22+
| 解决故障 | resolve the incident |
23+
| 关闭故障 | close the incident |
24+
| 新奇故障 | outlier incident |
25+
26+
## Alert Processing
27+
28+
| Chinese | English |
29+
|---------|---------|
30+
| 告警风暴 | alert storm |
31+
| 告警聚合 | alert grouping |
32+
| 静默策略 | silence rule |
33+
| 抑制策略 | inhibit rule |
34+
| 排除规则 | drop rule |
35+
| 快速静默 | quick silence |
36+
| 降噪 | reduce noise |
37+
| 抖动 | flapping |
38+
| 错误聚合 | error grouping |
39+
| 指纹 | fingerprint |
40+
41+
## Schedule & On-call
42+
43+
| Chinese | English |
44+
|---------|---------|
45+
| 值班表 | schedule |
46+
| 值班 | schedule |
47+
| 值班轮换 | On-call rotation / On-call shift |
48+
| 处理人员 / 响应人员 / 分派人员 / 值班人员 | responders |
49+
50+
## Severity Levels
51+
52+
| Chinese | English |
53+
|---------|---------|
54+
| 严重程度 / 等级 | severity |
55+
| 严重 | critical |
56+
| 一般 | warning |
57+
| 轻微 | info |
58+
59+
## Incident Status
60+
61+
| Chinese | English |
62+
|---------|---------|
63+
| 待处理 | triggered |
64+
| 处理中 | processing |
65+
| 未关闭 | open |
66+
| 已关闭 | closed |
67+
68+
## Time & Notifications
69+
70+
| Chinese | English |
71+
|---------|---------|
72+
| 暂缓 | snooze |
73+
| 取消暂缓 | unsnooze |
74+
| 触发 / 发生 | trigger |
75+
| 发生时间 / 触发时间 | triggered at |
76+
| 结束时间 | ended at |
77+
| 循环通知 | loop notification |
78+
| 中断次数 | interruption |
79+
| 通知次数 | notifications |
80+
| 时间段 | hours |
81+
| 工作时间 | work |
82+
| 睡眠时间 | sleep |
83+
| 休息时间 | rest |
84+
| 响应投入 | response effort |
85+
86+
## Subscription & Plans
87+
88+
| Chinese | English |
89+
|---------|---------|
90+
| 订阅 | plan |
91+
| 专业版 | Pro |
92+
| 标准版 | Standard |
93+
| 免费版 | Free |
94+
| 订阅升级 | plan upgrade |
95+
| 赠送金 | bonus |
96+
97+
## Account & Team
98+
99+
| Chinese | English |
100+
|---------|---------|
101+
| 主体 / 主体账号 | owner |
102+
| 成员 / 成员账号 | member |
103+
| 管理团队 | Team |
104+
| 登录 | sign in |
105+
| 登出 | sign out |
106+
| 注册 | sign up |
107+
108+
## UI & Labels
109+
110+
| Chinese | English |
111+
|---------|---------|
112+
| 属性 | attribute |
113+
| 标签 | label |
114+
| 详情 | details |
115+
| 告警列表 | Alerts |
116+
| 告警标题 | Title |
117+
| 分析看板 | insights |
118+
| 故障数量 | incidents |
119+
| 常见问题 | FAQ |
120+
| 视频教学 | watch videos |
121+
| 解决办法 | resolution |
122+
| 推送地址 | push URL |
123+
| 跳转链接 | jump link |
124+
125+
## Actions
126+
127+
| Chinese | English |
128+
|---------|---------|
129+
| 启用 / 开启 | Enable |
130+
| 禁用 | Disable |
131+
| 删除 | Delete |
132+
| 修改 | change |
133+
| 回复 | reply |
134+
| 聚合 | group |
135+
| 关联 | associated |
136+
137+
## Third-party Integrations
138+
139+
| Chinese | English |
140+
|---------|---------|
141+
| 企业微信 / 微信 | WeCom |
142+
| 飞书 | Feishu/Lark |
143+
| 钉钉 | Dingtalk |
144+
145+
## Technical Terms
146+
147+
| Chinese | English |
148+
|---------|---------|
149+
| IP段匹配 | CIDR matching |
150+
| 相同项 | equal item |
151+
| 组合规则 | composition rule |
152+
| 中文对照 | alias |
153+
| 环节 | level |
154+
| 输入不能为空 | the field is required |
155+
| 用户未关联 | user not linked |
156+
| 应用未关联 | app not linked |
157+
158+
## Regional
159+
160+
| Chinese | English |
161+
|---------|---------|
162+
| 国内 | mainland China |
163+
| 手机号 | phone |
164+
| 邮箱 | email |
165+
| 北京快猫星云科技有限公司 | Beijing Flashcat Cloud Technology Co.,Ltd. |

‎.gitignore‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Doc review findings (generated, human-editable before fix phase)
2+
.doc-review/
3+
4+
# Superpowers plugin docs (auto-generated)
5+
docs/

‎CLAUDE.md‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4+
5+
## Project Overview
6+
7+
Flashduty official documentation site, built with [Mintlify](https://mintlify.com/). Bilingual (Chinese `zh/` and English `en/`) with mirrored directory structures.
8+
9+
Three product modules: **On-call** (incident management), **RUM** (real user monitoring), **Monitors** (alert rules).
10+
11+
## Commands
12+
13+
```bash
14+
# Local preview
15+
mint dev
16+
17+
# Check broken links (run after any content changes)
18+
mint broken-links
19+
20+
# Upload docs to Meilisearch for AI Q&A bot
21+
MEILI_ENDPOINT=... MEILI_API_KEY=... MEILI_INDEX=... bash scripts/upload.sh
22+
```
23+
24+
Prerequisite: `npm i -g mint`
25+
26+
## Architecture
27+
28+
- **`docs.json`** — Central Mintlify config: navigation structure, tabs, theme. All new pages must be registered here under the correct language → tab → group.
29+
- **`zh/`** and **`en/`** — Mirror each other. Chinese is the source of truth; English is translated from it.
30+
- **`.cursor/skills/`** — AI agent skills for translation (`translate-zh-to-en`) and polishing (`polish-document`), with glossary and standards resources.
31+
32+
## Documentation Workflow
33+
34+
1. Create/edit Chinese docs in `zh/` as `.mdx` files
35+
2. Add the page path to `docs.json` navigation (both `zh` and `en` language sections)
36+
3. Translate to English using the glossary at `.cursor/skills/translate-zh-to-en/glossary.md`
37+
4. Run `mint broken-links` to validate
38+
39+
## Key Terminology (zh → en)
40+
41+
These are non-obvious translations that must stay consistent:
42+
43+
| Chinese | English |
44+
|---------|---------|
45+
| 协作空间 | channel |
46+
| 故障 | incident |
47+
| 分派策略 | escalation rule |
48+
| 处理人员 | responders |
49+
| 认领 | acknowledge |
50+
| 值班表 | schedule |
51+
| 新奇故障 | outlier incident |
52+
| 静默策略 | silence rule |
53+
| 抑制策略 | inhibit rule |
54+
| 排除规则 | drop rule |
55+
| 环节 | level |
56+
57+
Full glossary: `.cursor/skills/translate-zh-to-en/glossary.md`
58+
59+
## Writing Conventions
60+
61+
- Use second person ("you" / "您")
62+
- Active voice, present tense
63+
- Every `.mdx` file needs frontmatter with `title` and `description`
64+
- Sentence case for English titles (capitalize only first word)
65+
- Use Mintlify components: `<Steps>`, `<Tabs>`, `<Note>`, `<Tip>`, `<Warning>`, `<Frame>`, `<CodeGroup>`, `<Accordion>`
66+
- Component reference: `.cursor/skills/polish-document/components.md`
67+
68+
## Translation Rules
69+
70+
- Translate frontmatter `title` and `description`
71+
- Keep MDX component tags unchanged, translate inner text only
72+
- Keep code unchanged, translate comments only
73+
- Update internal link paths from `zh/` to `en/`
74+
- Keep image paths unchanged
75+
76+
## Link Validation Notes
77+
78+
`mint broken-links` may report parsing errors from `.cursor/` directory — these are safe to ignore (excluded from publishing via `.mintignore`). Only fix broken links in actual doc files.

0 commit comments

Comments
 (0)