用途
该技能面向越南语（vi-VN）工程与产品写作，用于撰写和审校 commit message、PR 描述、代码审查、RFC、设计文档、postmortem、runbook、规格书、README、教程、API 文档、UI 文案、发布说明、状态页、问卷调查等文档。
其出发点是：越南语技术写作与营销写作的失败方式不同——营销文案的常见问题是过于直译，技术文案的问题则是过于「越南化」，即把越南工程师习惯保留英文的术语翻译成越南语，并在描述系统的文档中使用人称代词称呼读者。这两类缺陷对非工程背景的校对者不可见，但对真正要使用文档的团队来说非常明显。
主要能力
第一步：写作前先确定文档类型
文档类型决定语域与人称，且与落地页默认做法相反：
- RFC、设计文档、postmortem、runbook、spec：无人称语域，完全不出现「bạn」，越南语倾向正式词汇（bộ nhớ đệm、cơ sở dữ liệu）。
- README、教程、API 文档、UI 文案、发布说明：使用「bạn」，用户侧名词使用越南语。
- PR 描述、代码审查、站会、聊天：使用「mình」或不加称呼，全程英文术语。
- 状态页（面向客户）：使用「quý khách」，措辞平实、非技术化。
在 RFC 中出现「bạn」属于缺陷。越南语有自然的无人称表达，例如「Hệ thống sẽ tự động retry」「Cần cấu hình biến môi trường」，而英语没有，这正是翻译文本中大量出现「bạn」的原因。
第二步：核心规则（不可妥协）
- 保留英语术语为英语：deploy、commit、merge、bug、server、cache、deadline、sprint、backlog、pull request。翻译这些词是最明显的机器翻译痕迹；用「cam kết」表示 commit 是最严重的问题，因为该词实际含义是「承诺」。
- 绝不翻译环境名：production、staging、dev。「triển khai đến sản xuất」不是越南工程师会写的句子。
- 标识符、分支名、commit 标题使用 ASCII，绝不带音调符号。commit 正文可以是越南语，标题行不可以。
- 输出 NFC Unicode，例如预组合的 ế（U+1EBF）。NFD 会破坏字体渲染、使字符数超过平台限制并影响搜索。
- 越南语没有语法复数，ICU 消息只使用 other 分支。vi 文件中出现 one、few、many、zero 分支都是 bug；=0 选择器可以使用。
- 每篇文档统一一种声调符号风格，默认使用 kiểu mới（hoà、thuỷ）。两种风格本身都不算错，混用才是错误。
- 绝不使用同意/不同意式调查量表，默认同意偏差会使同意率虚高约 10 个百分点；应询问属性本身。
- 错误信息说明发生了什么以及该做什么。面向开发者的界面绝不使用「quý khách」，也绝不将责任归咎于用户。
第三步：先查术语再自创新词
参考文件覆盖标记机器翻译的仿译词黑名单、英文与越南语形式并存的术语（server/máy chủ、cache/bộ nhớ đệm，需择一并保持一致），以及用户界面文案中已定型的越南语表达。术语表为机器可读格式，每一行都对应一条 lint 规则。
第四步：处理 i18n 风险
- 越南语文本比英语长 25–30%，固定宽度按钮会被截断。
- 音调符号会使短信进入 UCS-2 编码，单条短信从 160 字符缩短到 70 字符。
- 用户搜索时不带音调符号，因此匹配需要对抗音调不敏感。
- 丢弃叠置音调符号（ề、ộ、ữ）的字体子集会导致渲染静默失败。
相关参考还包括数字、日期与货币的本地化格式，以及 NFC、排序和输入法说明。起始资源文件 assets/messages.vi.json.template 提供 ASCII 键、NFC 值、仅 other 复数分支与两种语域。
第五步：产品与研究写作
发布说明以收益为导向、使用过去时（Đã sửa lỗi…、Đã thêm…）。敏捷术语保留英文（sprint、backlog、roadmap，lộ trình 也可以）。用户故事写作格式为「Là [vai trò], tôi muốn…」，绝不使用「Như một [vai trò]」。
问卷调查是本技能发挥价值的重点场景，因为措辞不当的越南语问卷读起来通顺却会返回错误数据。
第六步：核查宣称
应用商店列表与产品内宣称受《Luật Quảng cáo 16/2012/QH13》广告法约束。副标题中未经证实的「tốt nhất」或「số 1」属于受监管的宣称，而非广告标语。相关参考文件列出按文体区分的禁用短语，以及广告、同意和个人数据方面的通用规则。
第七步：校验、修正、再交付
写作完成后立即运行校验器。若报告错误，修正后再次运行。只有通过后才展示文案。NFC 违规与 ICU 复数问题通过阅读无法发现。
python scripts/validate_copy.py path/to/doc.md --register eng-impersonal
python scripts/validate_copy.py .git/COMMIT_EDITMSG --doctype commit
python scripts/validate_copy.py messages/vi.json --doctype identifier
python scripts/validate_copy.py survey.md --doctype survey
--register eng-impersonal|eng-readme|saas|re|formal|consult|...启用 PRO002。--list-rules打印本技能可输出的全部规则。--doctype启用结构规则。不指定时结构规则保持静默，因为 30 字符上限适合应用商店副标题，对设计文档毫无意义。可选值包括：commit、branch、identifier、rfc、postmortem、runbook、survey、app-store-title、app-store-subtitle、app-store-short-description、consent。- 退出码 0 表示干净或仅有警告；退出码 1 表示必须修正的错误。
--json输出机器可读结果；--strict使警告也导致失败。--fix就地重写 NFC 违规；其他规则均需人工判断。
指定具体网页字体时检查字形覆盖：
python scripts/check_font_coverage.py path/to/copy.md
第八步：参考示例对照，再交由人工审阅
在撰写较长内容前先阅读 bad→good 对照语料，每一组都会指出其修正的失败模式，这种诊断比具体字符串更具泛化价值。随后运行检查清单：linter 能捕获编码问题、黑名单仿译词以及按文档类型启用的结构规则，但无法判断某个英文术语的新越南语译法是否自然、问卷题目是否有引导性、错误信息是否真正可操作——这些需要一位在真实项目中交付软件的母语者来判断。
适用场景
适用于越南语工程与产品文档的撰写与审校，包括技术文档、代码协作文本、产品文案、发布说明、用户故事、调查问卷、应用商店列表与合规宣称核查等。
限制
校验器只能覆盖编码、仿译词与按文档类型启用的结构规则；译法自然度、问卷引导性、错误信息可操作性等仍需母语者人工判断。关于本技能的收费、价格、平台支持范围等信息暂未提供。