HARD i18n rules digest for the oss-docs harness specialists working on moai-adk-go README 4-locale set and the docs-site (adk.mo.ai.kr). Covers the canonical-locale chains, the 4-locale same-PR obligation, Mermaid TD-only, the no-emoji + icon-shortcode rule, emphasis-marker spacing, the URL blacklist, version SSOT, vercel.json redirect pattern, and the immutable Vercel binding. Loaded FIRST by every oss-docs specialist before any edit.
SkillScore86Maintained
Automatic
◆Translation & Localization pack
Last verified 8/27/2026
What it changes
Passed 16 of 19 test cases with the skill, and 4 of 19 without it.
Without skill23%
With skill86%
Checks it passed that the model alone missed
The response identifies hugo-geekdoc as the active theme.
The response identifies flowchart LR direction as forbidden.
The response identifies adk.mo.ai.kr as the single valid domain.
and 11 more in the full report
14 fixed5 passed either way3 still failing0 broke
Pass-rate lift
+64 pp
Tokens
+13%
Agent turns
0%
Response time
-48%
Model gemini-3.6-flashMeasured 8/27/2026v219 of 22 cases passed with skill · 19 comparable
Tokens, turns and time describe resource use, not a dollar price.
See it in action
One of 14 test cases the skill fixed. Same model, same prompt, with and without the skill.
1 of 14
Prompt
Review this Markdown line for formatting compliance: '**바이브코딩(Vibe Coding)**은 AI 기반 개발 방식입니다.' Provide the corrected line.
What was checked, without and with the skill
Checked
Without skill
With skill
The response places the parenthetical outside the bold markers as **바이브코딩** (Vibe Coding).
Missed
Passed
case-12 · gemini-3.6-flash · 8/27/2026 · answers are capped and redacted
What's inside
The instructions your model reads when the skill loads.
SKILL.md98 linessingle file
oss-docs HARD i18n Rules
SSOT: .moai/docs/docs-site-i18n-rules.md (+ CLAUDE.local.md §17.1 for the
design/icon regime). This skill is the working digest; on conflict, the SSOT
wins — EXCEPT the two stale items in § Known-Stale below, where reality wins.
1. Canonical-locale chains [HARD]
Surface
Canonical
Derivation chain
Derived files
docs-site
ko
ko → en → ja/zh, same PR
docs-site/content/{en,ja,zh}/
README
ko (README.ko.md)
ko → en/ja/zh, same PR
README.md, README.ja.md, README.zh.md
README canonical flipped en → ko by card t47 (operator decision 2026-08-17):
the ko new-skeleton (12-section feature-oriented structure) was promoted to
canonical, and en/ja/zh are re-derived from it. Both surfaces are now
ko-canonical — the surface chains agree.
Author in the canonical locale only; derive the rest. Never "fix" canonical
content inside a translation — report the discrepancy back instead.
2. 4-locale simultaneous-update obligation [HARD]
Every canonical content change MUST land in all 4 locales in the same PR.
A canonical edit without its 3 derived counterparts is a locale-parity FAIL
(sprint contract locale-parity threshold 1.0, must_pass).
Use the icon shortcode instead: {{</* icon <name> [variant] */>}}
(defined in docs-site/layouts/shortcodes/icon.html; variants:
ok|warn|danger|primary|muted).
Preserved (NOT emoji — do not strip): typographic symbols → ← ↓ ✓ ✗, and