vietnamese-tech-writing

越南语工程与产品文案（vi-VN）

越南语技术文案与越南语营销文案的问题各不相同。营销文案的问题在于过于直译。技术文案的问题则在于越南语化过度——把越南工程师习惯保留英文的术语翻译掉，并在描述系统的文档中直接称呼读者。

这两类问题，非工程师校对人员都难以察觉，但对必须使用文档的团队来说却一目了然。

步骤 1 — 动笔前先确定文档类型

文档类型决定了两项选择，而且这两项选择都与落地页的默认做法相反。

如果你正在编写	语体	术语
RFC、设计文档、事后分析、运行手册、规范	非人称——完全不使用 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 的原因。

各类文档适用的语体，以及替代 bạn 的非人称表达：references/doc-registers.md。与其他越南语技能共用的完整代词矩阵：references/register-matrix.md。

步骤 2 — 核心规则（不可妥协，无需跳转文件）

1. 英文术语保留英文。 deploy、commit、merge、bug、server、cache、deadline、sprint、backlog、pull request。把它们翻译掉，是机器翻译最明显的痕迹。把 commit 译成 cam kết 是最严重的错误——这是一个真实存在的词，意思是承诺。
2. 环境名称绝不翻译。 production、staging、dev。没有任何越南工程师会写出 triển khai đến sản xuất 这样的句子。
3. 标识符、分支名称和提交主题行只能使用 ASCII。 绝不添加变音符号。提交正文可以使用越南语；主题行不可以。
4. 输出 NFC Unicode。 使用预组合字符 ế（U+1EBF）。NFD 会破坏字体渲染、使字符数超过平台限制，并影响搜索。
5. 越南语没有语法复数。 ICU 消息只使用 other。vi 文件中出现 one、few、many 或 zero 分支，必定是错误。=0 选择器可以使用。
6. 每份文档只选用一种声调符号风格——默认使用 kiểu mới（hoà、thuỷ）。两种风格都没有问题；混用才有问题。
7. 绝不使用同意／不同意式问卷量表。 默许偏差会使同意度虚高约 10 个百分点。应直接询问相关特征本身。
8. 错误提示要说明发生了什么，以及该怎么做。 面向开发者的界面绝不使用 quý khách，也绝不归咎于用户。

步骤 3 — 先查术语，再造新词

机器翻译痕迹明显的生硬直译词黑名单、英文和越南语形式都在使用中的术语（server / máy chủ、cache / bộ nhớ đệm——选定一种并保持一致），以及面向用户的 UI 字符串中已确定的越南语表达：

references/glossary.md——采用机器可读格式，因此每一行都是一条 lint 规则。

关于哪些词应保留英文的原因，以及用于判断边界情况的正式程度维度：references/code-switching.md。

第 4 步 — 处理国际化隐患

越南语文本比英语长 25–30%，因此固定宽度的按钮会截断文本。 变音符号会使 SMS 使用 UCS-2 编码，短信分段长度从 160 个字符降至 70 个。用户搜索时会省略变音符号，因此匹配必须忽略重音符号。字体子集如果缺少叠加变音符号（ề、ộ、ữ），会导致渲染失败，而且不会显示任何提示。

references/i18n-hazards.md — 另外，数字、日期和货币格式请参阅 references/locale-formatting.md；NFC、 排序和输入法请参阅 references/unicode-and-tone.md。

起始资源文件：assets/messages.vi.json.template — ASCII 键、NFC 值、仅使用 other 复数形式，并包含两种语域。

第 5 步 — 产品与研究写作

发行说明以收益为导向，并使用过去时（Đã sửa lỗi…、Đã thêm…）。敏捷术语保留英语（sprint、backlog、roadmap — 也可以使用 lộ trình）。用户故事格式为 Là [vai trò], tôi muốn…，绝不使用 Như một [vai trò]。

问卷最能体现这项技能的价值，因为措辞不当的越南语问卷读起来可能没问题，收集到的数据却会出错：references/survey-design.md。

第 6 步 — 核实声明

应用商店列表和产品内声明均属于《广告法》Luật Quảng cáo 16/2012/QH13 所涵盖的广告。在副标题中使用未经证实的 tốt nhất 或 số 1，属于受监管的声明，而不是宣传语。

特定内容类型的禁用词列表请参阅 references/banned-phrases.md， 越南语技能共同适用的广告、同意和个人数据规则请参阅 references/compliance.md。

第 7 步 — 验证、修正，然后发布

写完后立即运行验证器。如果报告错误，请修正并再次运行。只有通过验证后才能提交文案。 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 违规；其他规则都需要人工判断。

指定了特定 Web 字体时，请检查字形覆盖情况：

python scripts/check_font_coverage.py path/to/copy.md

第 8 步 — 学习实际案例对，然后交由人工审核

开始撰写长文之前，先阅读错误→正确案例库。每组案例都会指出所修正的问题类型，而诊断方法的适用范围比具体字符串更广。

references/examples.md

然后运行检查清单。检查器可以发现编码问题、列入黑名单的直译表达，以及由文档类型启用的结构规则。但它无法判断英语术语的新越南语译法是否自然、问卷题目是否带有引导性，或错误消息是否真的能帮助用户采取行动。这些都需要由一位会发布软件的母语者审核： references/qa-checklist.md