vietnamese-drill

Cho AI agent viết tiếng Việt có flow: mượt, rõ nghĩa, giữ đúng thuật ngữ kỹ thuật.

Skill · Rule · Checker offline cho tài liệu, UI/UX, web content, notification và i18n.

Mic check · Beat drop: trước/sau · Cài 1 lệnh · Featuring: từng agent · Checker · Tracklist

🎤 Mic check

Yo. Nhờ AI viết tiếng Việt là kiểu gì cũng gặp mấy câu này:

"Đã cam kết các thay đổi và triển khai đến sản xuất."
"Thực hiện việc lưu cài đặt."
"Đã xảy ra lỗi."

Đọc thì hiểu, nhưng nghe như Google Dịch. commit biến thành "cam kết", production biến thành "sản xuất". Nút bấm dài dòng. Thông báo lỗi không nói hỏng chỗ nào, cũng không nói người dùng nên làm gì tiếp.

vietnamese-drill là bộ luật chơi cho agent khi đụng vào tiếng Việt trong phần mềm:

• Giữ chất kỹ thuật: commit, deploy, production, endpoint, cache… giữ tiếng Anh khi dân dev vẫn nói vậy.
• Đúng người đọc: tài liệu cho dev khác UI cho người dùng cuối. UI dùng "Lưu", "Đăng nhập", "Tải xuống", không đẩy jargon lên mặt người dùng.
• Không phá code: không dịch tên biến, key i18n, placeholder, path, lệnh CLI.
• Chuẩn i18n: NFC, vi-VN, không ghép mảnh câu, ICU phức tạp thì kiểm bằng compiler thật của dự án.
• Nói gọn mà không cụt: bớt filler, nhưng không bao giờ bỏ phủ định, điều kiện, số liệu hay cảnh báo.

Sao lại là "drill"?

Nhìn logo: chữ "skill" bị gạch "sk", viết đè "dr", thành "drill".

Drill là dòng nhạc nhịp chắc, flow dày, không thừa chữ nào. Tiếng Việt trong sản phẩm cũng nên vậy: gọn, rõ, đúng nhịp người đọc. Skill thì có rồi, giờ lên drill.

🔥 Beat drop: trước và sau

Ví dụ hay gặp khi agent chưa có skill so với khi đã có vietnamese-drill:

Các câu ở cột ✅ chỉ là ví dụ. Điều kiện kèm theo vẫn phải đúng thực tế: chỉ ghi "thử lại" khi app thật sự cho thử lại, chỉ ghi ngày giao khi có dữ liệu.

⚡ Cài 1 lệnh

Dùng skills CLI. Một lệnh cài được cho Claude Code, Codex, Cursor, Gemini CLI, OpenCode, GitHub Copilot, Windsurf và nhiều agent khác:

npx skills add zt-hky/vietnamese-drill

CLI tự dò agent có trên máy và hỏi cài vào đâu. Vài flag hay dùng:

npx skills add zt-hky/vietnamese-drill --list         # xem có gì trước khi cài
npx skills add zt-hky/vietnamese-drill -g             # cài global cho user, không cài theo project
npx skills add zt-hky/vietnamese-drill -g --all       # mọi skill, mọi agent, không hỏi
npx skills update                                     # kéo bản mới

Lười gõ lệnh? Đưa agent tự cài

Dán đoạn này vào agent đang dùng:

Cài bộ skill tiếng Việt ở https://github.com/zt-hky/vietnamese-drill cho agent này.
Ưu tiên chạy `npx skills add zt-hky/vietnamese-drill -g -a <agent-của-bạn> -y`.
Nếu không chạy được, copy thư mục skills/vietnamese-product và skills/vietnamese-replies
vào thư mục skills global của agent. Cài xong, liệt kê skill đã cài và đường dẫn.

🎧 Featuring: cài cho từng agent

Mỗi agent đọc skill ở một thư mục riêng. Lệnh npx bên dưới cài global (-g) cho đúng một agent (-a). Muốn cài theo project thì bỏ -g.

oh-my-pi (OMP): full combo

OMP nhận full set: 2 skill, rule luôn bật (2 dòng), tool vi_check + vi_lookup, subagent vietnamese-reviewer.

omp plugin install github:zt-hky/vietnamese-drill

Mở session mới để nạp rule và tool. Gỡ bằng omp plugin uninstall vietnamese-drill. Cập nhật bằng omp plugin upgrade vietnamese-drill.

Subagent mặc định chạy cùng model với session. Muốn ghim sang model rẻ (ví dụ Gemini Flash), thêm vào ~/.omp/agent/config.yml:

task:
  agentModelOverrides:
    vietnamese-reviewer: google-antigravity/gemini-3.8-flash

Chỉ cần skill thôi? npx skills add zt-hky/vietnamese-drill -g -a pi cũng chạy được, vì OMP đọc cả ~/.agents/skills.

Claude Code

Cài như plugin, có luôn subagent vietnamese-reviewer:

claude plugin marketplace add zt-hky/vietnamese-drill
claude plugin install vietnamese-drill@vietnamese-drill

Hoặc chỉ cài skill: npx skills add zt-hky/vietnamese-drill -g -a claude-code. Cài tay: copy hai thư mục trong skills/ vào ~/.claude/skills/ (theo project: .claude/skills/) và agents/vietnamese-reviewer.md vào ~/.claude/agents/.

Muốn reviewer chạy model rẻ hơn, thêm model: haiku vào frontmatter của file agent.

Codex (OpenAI)

npx skills add zt-hky/vietnamese-drill -g -a codex

Cài tay: ~/.agents/skills/ (theo project: .agents/skills/). Skill có sẵn agents/openai.yaml nên Codex tự gọi được khi gặp chuỗi UI tiếng Việt.

Subagent tuỳ chọn: copy codex/vietnamese_reviewer.toml vào ~/.codex/agents/. Không có file này thì skill vẫn chạy: Codex dùng subagent mặc định với lời nhắc trong SKILL.md. Phần Codex chưa được tác giả chạy thử trực tiếp, chỉ làm theo tài liệu chính thức.

Cursor

npx skills add zt-hky/vietnamese-drill -g -a cursor

Cài tay: ~/.cursor/skills/. Theo project thì dùng .agents/skills/.

Gemini CLI

npx skills add zt-hky/vietnamese-drill -g -a gemini-cli

Cài tay: ~/.gemini/skills/.

Antigravity

npx skills add zt-hky/vietnamese-drill -g -a antigravity

Cài tay: ~/.gemini/antigravity/skills/.

OpenCode · GitHub Copilot · Windsurf

npx skills add zt-hky/vietnamese-drill -g -a opencode
npx skills add zt-hky/vietnamese-drill -g -a github-copilot
npx skills add zt-hky/vietnamese-drill -g -a windsurf

Cài tay lần lượt vào ~/.config/opencode/skills/, ~/.copilot/skills/, ~/.codeium/windsurf/skills/.

Agent khác

Agent nào hỗ trợ chuẩn Agent Skills (<thư-mục-skills>/<tên>/SKILL.md) thì copy nguyên hai thư mục skills/vietnamese-product và skills/vietnamese-replies. Giữ cả scripts/ và references/ bên trong.

Agent chưa hỗ trợ skill: dán nội dung SKILL.md vào file rule hoặc instruction của agent đó (ví dụ AGENTS.md, .cursor/rules/). Bỏ phần frontmatter giữa hai dòng ---.

📚 Từ điển UI chuẩn

skills/vietnamese-product/assets/glossary.vi-ui.tsv: 329 thuật ngữ giao diện (Lưu, Hủy, Cài đặt, Tải xuống, Đăng nhập, Thanh toán, Thông báo…), mỗi dòng ghi từ ưu tiên, dạng chấp nhận được, dạng bị loại và nguồn.

174/329 dòng được từ hai nguồn trở lên đồng thuận, 59 dòng là quyết định biên tập (ghi rõ E). Chọn dạng ngắn, hiện đại hơn khi các hãng khác nhau.

Không nhét cả từ điển vào prompt. Agent chạy check.mjs lookup và chỉ nhận vài dòng liên quan tới chuỗi đang làm:

echo '{"strings":[{"id":"1","src":"Learn more"},{"id":"2","src":"Mute this conversation"}]}' \
  | node skills/vietnamese-product/scripts/check.mjs lookup

learn more = Tìm hiểu thêm | avoid: Học thêm | "Học thêm" is a typical machine translation
mute … conversation = Tắt thông báo | alt: Tắt tiếng | Messaging apps: Tắt thông báo

Glossary của dự án (cùng cột TSV, mẫu ở assets/project-glossary.template.tsv) luôn thắng: check.mjs lookup --glossary project.tsv.

Đã đo có hiệu quả không? Có, vừa phải. Trên 62 chuỗi mới viết sau khi chốt từ điển: độ dùng đúng thuật ngữ của Gemini Flash từ 90,2% lên 96,7%, Claude Haiku từ 94,6–95,7% lên 96,7–97,8%; giám khảo mù (Claude Sonnet) nghiêng về bản có glossary (27:19 và 38:30). Phép đo đầu tiên bị bão hoà (baseline đã 100% vì chuỗi Android/Firefox là dữ liệu công khai), và glossary trần trụi từng làm câu dịch sát chữ hơn trước khi thêm lời nhắc "tự nhiên". Toàn bộ số liệu, thất bại và cách chạy lại ở evals/README.md.

🧪 Checker offline

Kiểm những lỗi máy bắt được, khỏi tốn token LLM. Chỉ cần Node.js, không có dependency, không gọi mạng, không tự sửa gì. Chỉ đọc glossary đi kèm (và file glossary dự án nếu bạn truyền --glossary).

echo '{"text":"Xin chào {user}","sourceText":"Hello {name}"}' \
  | node skills/vietnamese-product/scripts/check.mjs

{"status":"error","findings":[{"code":"PLACEHOLDER","severity":"error","path":"$","message":"Supported placeholder names/types/counts differ from source"}],"total":1,"truncated":false,"semanticReview":"not-run"}

File i18n dạng JSON thì thêm "mode":"json": checker so từng leaf key, kiểu dữ liệu và placeholder với file nguồn.

Exit code: 0 sạch hoặc chỉ có cảnh báo · 1 lỗi contract · 2 request sai định dạng.

💿 Tracklist

vietnamese-drill/
├── skills/
│   ├── vietnamese-product/             # UI/UX, content, notification, i18n (kích hoạt khi cần)
│   │   ├── SKILL.md
│   │   ├── agents/openai.yaml          # Codex: gọi ngầm được
│   │   ├── scripts/check.mjs           # checker + lookup (CLI)
│   │   ├── scripts/glossary.mjs        # nạp, khớp, lint glossary
│   │   ├── assets/glossary.vi-ui.tsv   # 329 thuật ngữ UI
│   │   ├── assets/project-glossary.template.tsv
│   │   └── references/                 # reviewer, microsoft-vi-style, locale-and-glossary, sources
│   └── vietnamese-replies/             # cách agent trả lời bạn bằng tiếng Việt
├── agents/vietnamese-reviewer.md       # subagent dùng chung Claude Code + OMP
├── codex/vietnamese_reviewer.toml      # subagent tuỳ chọn cho Codex
├── .claude-plugin/                     # plugin + marketplace cho Claude Code
├── rules/vietnamese.md                 # OMP: rule luôn bật, 2 dòng
├── tools/vi-check.ts                   # OMP: tool vi_check + vi_lookup
├── evals/                              # bộ đo hiệu quả, kết quả và thất bại
└── package.json                        # manifest plugin OMP

🧠 Flow chạy và vì sao ít tốn token

Học từ caveman: nói ít, nhưng giữ đủ ý.

1. Chỉ kích hoạt khi cần. Description hẹp: chỉ chuỗi UI/product copy tiếng Việt, không phải chat. Việc khác không tốn token nào ngoài dòng mô tả.
2. Agent chính không nạp glossary. Với 3 chuỗi trở lên, nó giao một batch cho subagent kèm đường dẫn skill. Subagent đọc playbook (660 token), chạy lookup, trả về các dòng đã đổi. Harness không có subagent thì agent tự làm đúng các bước đó.
3. Chỉ lấy phần liên quan. 116 token cho 10 chuỗi thay vì 5.110 token cho cả từ điển. Đo được: dán cả từ điển còn cho kết quả kém hơn lát cắt.
4. Checker local chạy sau: placeholder, key, NFC, dạng bị loại bằng code, không bằng LLM.
5. Gọn nhưng không cụt. Lát cắt luôn kèm một dòng nhắc "phần còn lại phải tự nhiên, bỏ 'của bạn' khi đã rõ". Thiếu dòng này, model dịch sát chữ hơn (đã đo).

Glossary của dự án luôn thắng. Dự án đã chọn "máy chủ" thay vì "server" thì agent theo dự án.

🛡️ Dữ liệu đi đâu

• check.mjs / vi_check: chạy 100% trên máy, không gửi gì ra ngoài.
• vietnamese-reviewer: gửi batch chuỗi cần review tới provider của model mà subagent đang dùng (Claude, OpenAI, Google…). Skill yêu cầu bỏ secret và dữ liệu khách hàng trước khi gửi, nhưng bạn vẫn nên tự kiểm tra.

🗺️ Giới hạn

• Rule và skill là hướng dẫn cho agent, không phải hook chặn output. Agent vẫn có thể làm sai, nên review vẫn cần.
• Checker không thay compiler i18n của dự án. ICU, HTML, Markdown phức tạp vẫn phải chạy công cụ thật.
• Mẫu đo nhỏ (44–62 chuỗi, 2 lượt, một giám khảo), tiêu chí "dùng đúng thuật ngữ" do chính glossary định nghĩa. Cải thiện có thật nhưng vừa phải; xem evals/README.md.
• Glossary chỉ phủ thuật ngữ giao diện phổ biến. Từ chuyên ngành (y tế, luật, tài chính) cần glossary của dự án.
• Codex chưa được chạy thử trực tiếp.

🤝 Vào cypher

Gặp câu agent viết sai hoặc nghe "văn dịch"? Mở issue gồm:

1. Câu gốc (nếu có) và câu agent viết.
2. Ngữ cảnh: UI, docs, noti, commit, chat…; người đọc là ai.
3. Câu bạn thấy đúng và lý do.

PR sửa rule nhớ kèm các cặp câu trước/sau. Đừng thêm luật cấm cứng một từ nếu từ đó vẫn có chỗ dùng đúng.

📼 Liner notes

Rule do repo tự viết. Ý tưởng tham khảo từ:

• trussary/vietnamese-language-skill: thuật ngữ kỹ thuật, xưng hô, rủi ro i18n.
• abm-dungtq/viet-pro: nhận diện văn dịch theo ngữ cảnh.
• luongnv89/claude-howto: TRANSLATION_NOTES: glossary, không dịch code.
• Microsoft Vietnamese Localization Style Guide (PDF 60 trang): giọng văn, từ ngữ hiện đại, viết hoa câu, dấu câu, mẫu thông báo lỗi, ngôn ngữ trung tính về giới. Đã đọc hết và rút thành references/microsoft-vi-style.md; bản gốc vẫn thuộc Microsoft. Tham khảo thêm Microsoft Localization Style Guides.
• Nguyen LNP: Vietnamese Localization Style Guide: style guide khác glossary, ngữ cảnh cần đính kèm, quy trình có AI và người duyệt.
• GTE Localize: Vietnamese Localization: định dạng ngày giờ, tên, địa chỉ, đại từ, phương ngữ, SEO. Chỉ lấy phần kiểm chứng được; phần mâu thuẫn hoặc chưa kiểm chứng được ghi rõ ở references/sources.md.
• JuliusBrussee/caveman: nói ít, giữ payload nguyên văn.

Logo dùng font Pricedown (Typodermic, bản free cho thiết kế tĩnh), Mr Dafoe và Be Vietnam Pro (SIL OFL). Logo chỉ lấy cảm hứng từ không khí Vice City, không liên quan tới Rockstar Games hay GTA. File thiết kế nằm ở design/logo.html. Repo không chứa file font.

License: MIT.