vietnamese-tech-writing

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Vietnamese engineering and product writing (vi-VN)

越南语工程与产品文档写作（vi-VN）

Vietnamese technical writing fails differently from Vietnamese marketing writing. Marketing copy goes wrong by being too literal. Technical copy goes wrong by being too Vietnamese — translating the English terms that Vietnamese engineers keep in English, and addressing a reader in documents that describe a system.

Both defects are invisible to a non-engineer proofreader and instantly obvious to the team that has to use the document.

越南语技术文档的常见问题与营销文档不同：营销文案常因过于直译出错，而技术文档则因过度越南语化出问题——比如将越南工程师习惯保留的英文术语翻译成越南语，或是在描述系统的文档中使用称呼语。

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

Step 1 — Decide what the document is before writing a word

步骤1：动笔前先明确文档类型

Two decisions follow from the document type, and both are inverted from the landing-page defaults.

If you are writing	Register	Terms
RFC, design doc, postmortem, runbook, spec	impersonal — no `bạn` at all	Vietnamese leans formal ( `bộ nhớ đệm` , `cơ sở dữ liệu` )
README, tutorial, API docs, UI copy, release notes	`bạn`	Vietnamese for user-facing nouns
PR description, code review, standup, chat	`mình` / no address	English terms throughout
Status page (customer-facing)	`quý khách`	plain, non-technical

bạn
in an RFC is a defect. Vietnamese has natural impersonal constructions —

Hệ thống sẽ tự động retry

Cần cấu hình biến môi trường

— and English does not, which is exactly why translated text is full of

bạn

Which document takes which register, and the impersonal constructions that replace

bạn

: references/doc-registers.md. The full pronoun matrix shared with the other Vietnamese skills: references/register-matrix.md.

文档类型决定两个核心选择，且均与营销页面的默认规则相反。

文档类型	语体风格	术语使用
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。

Step 2 — Core rules (non-negotiable, no file hop needed)

步骤2：核心规则（无协商空间，无需跳转文件）

Keep the English terms English.
```
deploy
```
,
```
commit
```
,
```
merge
```
,
```
bug
```
,
```
server
```
,
```
cache
```
,
```
deadline
```
,
```
sprint
```
,
```
backlog
```
,
```
pull request
```
. Translating them is the single loudest machine-translation tell.
```
cam kết
```
for
```
commit
```
is the worst offender — it is a real word meaning to pledge.
Never translate environment names.
```
production
```
,
```
staging
```
,
```
dev
```
.
```
triển khai đến sản xuất
```
is not a sentence any Vietnamese engineer has written.
Identifiers, branch names, and commit subjects are ASCII. No diacritics, ever. The commit body may be Vietnamese; the subject line may not.
Emit NFC Unicode. Precomposed
```
ế
```
(U+1EBF). NFD breaks font rendering, inflates character counts past platform limits, and defeats search.
Vietnamese has no grammatical plural. ICU messages take
```
other
```
only. A
```
one
```
,
```
few
```
,
```
many
```
or
```
zero
```
branch in a
```
vi
```
file is always a bug.
```
=0
```
selectors are fine.
Pick one tone-mark style per document — kiểu mới (
```
hoà
```
,
```
thuỷ
```
) by default. Neither style is wrong; mixing them is.
Never use an agree/disagree survey scale. Acquiescence bias inflates agreement by roughly 10 points. Ask about the property itself.
Errors say what happened and what to do. Never
```
quý khách
```
in a developer-facing surface, and never blame the user.

英文术语保留原词：
```
deploy
```
、
```
commit
```
、
```
merge
```
、
```
bug
```
、
```
server
```
、
```
cache
```
、
```
deadline
```
、
```
sprint
```
、
```
backlog
```
、
```
pull request
```
。翻译这些术语是机器翻译最明显的痕迹，其中把
```
commit
```
翻译成
```
cam kết
```
（意为“承诺”）是最糟糕的错误。
环境名称绝不翻译：
```
production
```
、
```
staging
```
、
```
dev
```
。没有越南工程师会写出
```
triển khai đến sản xuất
```
这样的句子。
标识符、分支名称、提交主题必须为ASCII编码：绝对不能使用变音符号。提交正文可以是越南语，但主题行不行。
输出NFC标准Unicode编码：使用预合成字符
```
ế
```
（U+1EBF）。NFD编码会破坏字体渲染、使字符数超出平台限制，还会导致搜索失效。
越南语无语法复数：ICU消息仅需使用
```
other
```
分支。
```
vi
```
文件中出现
```
one
```
、
```
few
```
、
```
many
```
或
```
zero
```
分支均为错误，
```
=0
```
选择器除外。
单篇文档统一一种声调标记风格：默认使用新式标记（
```
hoà
```
、
```
thuỷ
```
）。两种风格本身无对错，但混用会出错。
绝不使用同意/不同意类调研量表：默许偏差会使同意率虚高约10个百分点，应直接询问属性本身。
错误信息需说明问题及解决方法：面向开发者的界面中绝不使用
```
quý khách
```
，且绝不指责用户。

Step 3 — Look up the term before inventing one

步骤3：先查术语再自行创造

The blocklist of calques that mark machine translation, the terms where both an English and a Vietnamese form are live (

server

máy chủ

cache

bộ nhớ đệm

— pick one and hold it), and the settled Vietnamese for user-facing UI strings:

references/glossary.md — machine-readable, so every row is a lint rule.

The reasoning behind which words stay English, and the formality axis that decides the borderline cases: references/code-switching.md.

机器翻译常见的直译禁用词表、同时存在英文和越南语形式的术语（如

server

máy chủ

、

cache

bộ nhớ đệm

——需统一选一种）、以及面向用户的UI字符串标准越南译法，可参考：

references/glossary.md——该文件为机器可读格式，每一行可作为一条lint规则。

关于哪些词汇需保留英文、以及如何通过正式程度边界判断的依据：references/code-switching.md。

Step 4 — Handle the i18n hazards

步骤4：处理国际化风险

Vietnamese text runs 25–30% longer than English, so fixed-width buttons truncate. Diacritics force SMS into UCS-2, cutting the segment from 160 characters to 70. Users search without diacritics, so matching must be accent-insensitive. Font subsets that drop stacked diacritics (

ề

ộ

ữ

) break rendering silently.

references/i18n-hazards.md — plus references/locale-formatting.md for numbers, dates and currency, and references/unicode-and-tone.md for NFC, collation, and input methods.

For a starter resource file: assets/messages.vi.json.template — ASCII keys, NFC values,

other

-only plurals, both registers.

越南语文本长度比英文长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

分支的复数规则，同时支持两种语体风格。

Step 5 — Product and research writing

步骤5：产品与调研文档写作

Release notes are benefit-led and past-tense (

Đã sửa lỗi…

Đã thêm…

). Agile terms stay English (

sprint

backlog

roadmap

—

lộ trình

is also fine). User stories are

Là [vai trò], tôi muốn…

, never

Như một [vai trò]

Surveys are where this skill earns its keep, because a badly worded Vietnamese survey reads fine and returns wrong numbers: references/survey-design.md.

发布说明需以收益为导向、使用过去时态（如

Đã 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。

Step 6 — Check the claims

步骤6：核查合规性声明

App-store listings and in-product claims are advertising under Luật Quảng cáo 16/2012/QH13. An unproven

tốt nhất

số 1

in a subtitle is a regulated claim, not a tagline.

references/banned-phrases.md for the genre-specific list, references/compliance.md for the cross-cutting advertising, consent, and personal-data rules every Vietnamese skill shares.

应用商店列表和产品内声明属于《2012年第16号广告法》（Luật Quảng cáo 16/2012/QH13）管辖范围。副标题中未经证实的

tốt nhất

（最佳）或

số 1

（第一）属于受监管的声明，而非宣传语。

特定品类的禁用短语列表：references/banned-phrases.md，跨品类的广告、同意条款和个人数据规则：references/compliance.md（所有越南语技能共享）。

Step 7 — Validate, fix, then ship

步骤7：验证、修复后再发布

Run the validator immediately after writing. If it reports errors, fix them and run again. Only present the copy once it passes. NFC violations and ICU plural bugs are invisible to reading.

bash

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|...

enables

PRO002

--list-rules

prints every rule this skill can emit.

--doctype
is what turns on the structural rules. They stay silent without it, because a 30-character limit is right for an app-store subtitle and nonsense for a design doc:
```
commit
```
,
```
branch
```
,
```
identifier
```
,
```
rfc
```
,
```
postmortem
```
,
```
runbook
```
,
```
survey
```
,
```
app-store-title
```
,
```
app-store-subtitle
```
,
```
app-store-short-description
```
,
```
consent
```
.
Exit
```
0
```
= clean or warnings only. Exit
```
1
```
= errors that must be fixed.
```
--json
```
for machine-readable findings;
```
--strict
```
to fail on warnings too.
```
--fix
```
rewrites NFC violations in place; every other rule is a human judgement call.

Check glyph coverage when a specific web font is specified:

bash

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

写完后立即运行验证工具。若报告错误，修复后重新运行，直到验证通过再提交。 NFC违规和ICU复数错误无法通过人工阅读发现。

bash

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违规问题；其他规则需人工判断修正。

若指定了特定网页字体，需检查字符覆盖情况：

bash

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

Step 8 — Learn from the worked pairs, then hand it to a human

步骤8：参考示例后交给人工审核

Read the bad→good corpus before writing anything long. Each pair names the failure mode it fixes, and the diagnosis generalizes further than the string does.

references/examples.md

Then run the checklist. The linter catches encoding, blocklisted calques, and the doctype-gated structural rules. It cannot tell you whether a new Vietnamese rendering of an English term reads natural, whether a survey item is leading, or whether an error message is actually actionable. Those need a native speaker who ships software: references/qa-checklist.md

撰写长篇内容前，先阅读错误→正确的示例 corpus。每一组示例都会标注修复的问题类型，其诊断逻辑可推广到更多场景。

references/examples.md

之后运行检查清单。Linter可检测编码问题、禁用直译词、以及文档类型相关的结构规则，但无法判断英文术语的越南语新译法是否自然、调研问题是否存在诱导性、错误信息是否具备可操作性。这些问题需要有软件开发经验的母语人士审核：references/qa-checklist.md