← LeaderboardThe Skill Leaderboard

hns-oss-docs-i18n-rules

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.

Published by modu-ai ↗modu-ai/moai-adk

Try your first task

hns-oss-docs-i18n-rules

Start a fresh conversation. Replace the highlighted placeholders.

Use hns-oss-docs-i18n-rules to review [canonical documentation change] and draft compliant four-locale documentation updates, preserving Mermaid direction and URL/version rules; do not commit or push, and leave publication for human approval.

Required inputs

  • [canonical documentation change]

User-approved starter prompt based on a pinned source version; check current skill requirements before running. Task evidence ↗

SKILL.md

name: hns-oss-docs-i18n-rulesdescription: >  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.allowed-tools: Read, Grep, Glob, Bashuser-invocable: falsemetadata:   version: "1.1.0"  category: "harness"  status: "active"  updated: "2026-08-17"  tags: "oss-docs,i18n,4-locale,readme,docs-site,adk.mo.ai.kr"

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]

SurfaceCanonicalDerivation chainDerived files
docs-sitekoko → en → ja/zh, same PRdocs-site/content/{en,ja,zh}/
READMEko (README.ko.md)ko → en/ja/zh, same PRREADME.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).

3. Mermaid TD-only [HARD]

  • Allowed: flowchart TD, graph TB.
  • Forbidden: LR / RL directions (flowchart LR, graph LR, flowchart RL, graph RL).
  • Translation preserves diagram direction verbatim.

4. No emoji in body text [HARD]

  • 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 branding emoji inside MoAI orchestrator-banner example code blocks.

5. Emphasis-marker spacing [HARD]

  • Correct: **바이브코딩** (Vibe Coding) — parenthetical OUTSIDE the markers.
  • Wrong: **바이브코딩(Vibe Coding)**.

6. URL blacklist [HARD]

Only adk.mo.ai.kr is a valid docs-site domain. Forbidden (all occurrences, including link labels and translated prose):

  • docs.moai-ai.dev
  • adk.moai.com
  • adk.moai.kr

7. Version SSOT [HARD]

docs-site/hugo.toml params.version / params.releaseDate is the single version surface. Never hardcode divergent version/date strings into pages, menus, or READMEs beyond what the release process syncs.

Release-sync obligation (operator decision 2026-08-18): every release updates ALL version DISPLAYS to the release number in the same PR — hugo.toml version + releaseDate together (the file's own two-line contract), the README release badges (all 4 locales), and in-page example outputs that show the product version (statusline examples 🗿 vX.Y.Z, update-prompt examples X ⬆️ Y, version-column example values). Historical citations ("introduced in vX.Y.Z", "retired in v3.0.0", "default-on since v3.0.0") are NOT displays and stay untouched. The verify recipe's version-string check (Skill "hns-oss-docs-verify" §6) enforces this at the exit gate.

8. Moved pages need redirects [HARD]

Every docs-site page move/rename adds to docs-site/vercel.json:

  1. Locale-aware: /:locale(ko|en|ja|zh)/old-path → /:locale/new-path
  2. Non-locale fallback: /old-path → /ko/new-path

9. Vercel binding immutable [HARD]

The Vercel project binding and deployment config are never changed by this harness (redirects array excepted). Push = production deploy at adk.mo.ai.kr, which is why specialists NEVER commit/push — publishing is human-gated.

Known-Stale items in the SSOT doc

The SSOT .moai/docs/docs-site-i18n-rules.md predates the current site and carries 2 stale facts — reality wins:

  1. It says the theme is Hextra → reality: hugo-geekdoc.
  2. It says config is hugo.yaml → reality: docs-site/hugo.toml (defaultContentLanguage=ko).

Also: the scripts docs-i18n-check.sh and gen_menu.py referenced there DO NOT exist. Never shell out to them — run the inlined checks in Skill("hns-oss-docs-verify") instead.