vietnamese-tech-writing
Writes and reviews native-quality Vietnamese (vi-VN) engineering and product documentation — commit messages, PR descriptions, code review, RFCs, design docs, postmortems, runbooks, READMEs, API docs, UI and error microcopy, i18n resource files, PRDs, user stories, release notes, changelog entries, in-app notifications, help-centre articles, surveys and research guides, and app-store listings. Use when drafting or reviewing Vietnamese technical or product content, deciding which English terms stay English, choosing the impersonal register over bạn, or handling vi-VN i18n hazards like string expansion, ICU plurals, collation, and NFC. Fixes the machine-translation tells Vietnamese engineers notice immediately.
trussary · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add trussary/vietnamese-language-skill --skill vietnamese-tech-writing技能说明
name: vietnamese-tech-writing description: Writes and reviews native-quality Vietnamese (vi-VN) engineering and product documentation — commit messages, PR descriptions, code review, RFCs, design docs, postmortems, runbooks, READMEs, API docs, UI and error microcopy, i18n resource files, PRDs, user stories, release notes, changelog entries, in-app notifications, help-centre articles, surveys and research guides, and app-store listings. Use when drafting or reviewing Vietnamese technical or product content, deciding which English terms stay English, choosing the impersonal register over bạn, or handling vi-VN i18n hazards like string expansion, ICU plurals, collation, and NFC. Fixes the machine-translation tells Vietnamese engineers notice immediately. license: MIT metadata: version: "1.0.0" repository: "https://github.com/trussary/vietnamese-language-skill"
Vietnamese engineering and product writing (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
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.
Step 2 — Core rules (non-negotiable, no file hop needed)
- 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ếtforcommitis 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ấtis 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
otheronly. Aone,few,manyorzerobranch in avifile is always a bug.=0selectors 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áchin a developer-facing surface, and never blame the user.
Step 3 — Look up the term before inventing one
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.
Step 4 — Handle the i18n hazards
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.
Step 5 — Product and research writing
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.
Step 6 — Check the claims
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 or số 1 in a subtitle is a regulated claim, not a tagline.
**[references/banned-phrases.md](refer
阅读完整来源 ↗