wiki-i18n — правило для Claude Code: что делает и как установить
Правило wiki-i18n контролирует переводы статической вики на китайский, вьетнамский, корейский и испанский языки при правках HTML и скриптов проекта.
MIT ★ 1 198 обновлён 2026-10-23
.claude/rules/wiki-i18n.mdЧто делает wiki-i18n
Правило задаёт регламент обновления статической вики проекта в wiki/index.html. Английский текст служит первоисточником в DOM, а клиентские скрипты подменяют строки на лету. Любой новый видимый фрагмент должен одновременно получать переводы на упрощённый китайский (zh), вьетнамский (vi), корейский (ko) и испанский (es), иначе интерфейс останется наполовину английским.
Текст разбит на уровни: короткие метки и заголовки добавляются в словарь T внутри wiki/script.js, а основной текст страниц попадает в wiki/i18n-content.js с нормализацией пробелов в innerHTML. Атрибуты вроде alt или aria-label вынесены в ATTRIBUTE_TRANSLATIONS. Правило запрещает переводить имена файлов, CLI-флаги, переменные окружения и код.
Изменение структуры селекторов ломает тесты: client/tests/wiki-i18n.test.ts парсит файл wiki/script.js регулярными срезами исходника, поэтому менять форматирование объявлений нельзя. Для проверки разметки требуется запускать headless Chrome или Vitest.
Какие задачи решает
- синхронизировать переводы вики на четыре языка в одном коммите
- предотвратить выпадение непереведённых блоков в английский фолбэк
- сохранить разметку карточек карусели и подписей к скриншотам
- избежать поломки тестов при обновлении словарей перевода
Примеры запросов агенту
- Обнови описание модуля в wiki/index.html и добавь переводы во все словари по правилу wiki-i18n
- Добавь новую карточку в карусель фич вики с соблюдением лимитов длины текста
- Проверь покрытие переводов через тесты вики перед коммитом
Как установить wiki-i18n
Вручную: положить файлы
.claude/rules/wiki-i18n.mdПоле paths во frontmatter ограничивает файлы
AGENTS.md
Codex читает AGENTS.md: вставьте текст правила туда
Вручную: положить файлы
.cursor/rules/wiki-i18n.mdcВо frontmatter: description, globs, alwaysApply
Вручную: положить файлы
.github/instructions/wiki-i18n.instructions.mdПоле applyTo задаёт, к каким файлам применять
Вручную: положить файлы
.devin/rules/wiki-i18n.mdВручную: положить файлы
.clinerules/wiki-i18n.mdПо шагам, с командами для каждой платформы: AGENTS.md и CLAUDE.md: что это, кто читает и какой выбрать
Вопросы о wiki-i18n
Как установить правило wiki-i18n в Claude Code?
Поместите файл правила по пути .claude/rules/wiki-i18n.md.
Что делает правило wiki-i18n?
Оно следит за тем, чтобы любые правки интерфейса вики сопровождались переводами на zh, vi, ko и es, а также проверяет разметку и длину блоков.
Что нельзя переводить в тексте вики?
Правило запрещает переводить содержимое тегов <code>, пути к файлам, названия инструментов, команды терминала, флаги CLI и имена переменных окружения.
Исходный текст
wiki-i18n.md · MIT
---
paths:
- "wiki/index.html"
- "wiki/script.js"
- "wiki/i18n-content.js"
- "wiki/style.css"
- "wiki/sw.js"
---
# Wiki Internationalization Rules
The static wiki (`wiki/index.html`) is fully localized to English, Simplified
Chinese (`zh`), Vietnamese (`vi`), Korean (`ko`), and Spanish (`es`). English is
the DOM source of truth; `wiki/script.js` swaps text at runtime. **Any new or
changed user-visible wiki text MUST ship with `zh` + `vi` + `ko` + `es`
translations in the same change** — otherwise it falls back to English and the
page is half-translated.
## When you add or edit content in `wiki/index.html`
- The scannable layer — the `PLAIN` selector set in `wiki/script.js`
(`.logo-sub`, `.section-label`, `.nav-section`, `.nav-empty`, `.stat-label`,
`.t-label`, `.main-content h2/h3/h4/th`, `.hero-desc`) plus the `TEXTNODE_SEL`
trailing text nodes (`.nav-link`, `.hero-badge`) — is keyed by plain text in
the `T` dictionary inside `wiki/script.js`. Add the new English text as a key
with its `zh`, `vi`, `ko`, and `es` values there. Note `th` is matched by both
passes: as a label in `PLAIN` and as body content in `HTML_SEL`.
- Body content — `.main-content p:not(.hero-desc)`, `li`, `td`, `th`,
`.screenshot-caption`, `.callout-body > strong`, `.route-desc`, and the footer
(`.wiki-footer .footer-note / .footer-col-title / .footer-col-links a`) — is
keyed by **whitespace-normalized `innerHTML`** in `wiki/i18n-content.js`
(`window.__WIKI_CONTENT_I18N`). Add an entry to every non-English locale whose
**key is the element's `innerHTML` with every whitespace run collapsed to one
space and ends trimmed**, and whose value keeps the same complete set of
inline tags (`<code>`, `<strong>`, `<a>`, `<span>`).
- Add every new image `alt`, `aria-label`, `placeholder`, or `title` value to
`ATTRIBUTE_TRANSLATIONS` in `wiki/script.js`, and keep `META` complete for
every locale whenever page metadata changes.
- If you introduce a **new content container/class**, add its selector to
`HTML_SEL` (body prose) or `PLAIN` (scannable labels) in `wiki/script.js` so
the engine translates it at all.
- `client/tests/wiki-i18n.test.ts` extracts `T`, `ATTRIBUTE_TRANSLATIONS`, and
`META` by slicing `wiki/script.js` on literal source markers (`" const T = "`
… `"\n\n const PLAIN"`, and so on). Edit *inside* those objects; renaming,
reordering, or re-indenting the declaration lines breaks the test.
- The active wiki language is persisted in `localStorage["wiki-lang"]`; there is
no `?lang=` URL parameter. First visit falls back to a `navigator.language`
prefix ladder. Adding a locale therefore also means adding it to
`languageLabels`, to the `document.documentElement.lang` ladder in `apply()`,
and to that detection ladder — see
[`.claude/skills/i18n-parity/`](../skills/i18n-parity/SKILL.md).
## Fit the block you are writing into (length + placement)
The wiki is a designed page. Some blocks live in fixed-size boxes, so a new
entry that is 2–3x its neighbours breaks the layout rather than just reading
long. **Read the two blocks around yours and match their length, tone, markup,
and heading depth — never invent a new pattern for one entry.**
- **Feature carousel cards** (`#feature-carousel .feature-card`): one `<p>` of
~450–550 characters (~65–80 words; the 39-card group spans 209–628 with a
~494 median). No lists, no sub-headings, no exhaustive keybinding/edge-case
enumeration.
- **Screenshot captions** (`.screenshot-caption`): ~150–300 characters — emoji,
bolded screen name, em dash, one dense sentence.
- **Card order is editorial.** A newly shipped feature is inserted by
importance among the existing cards; it does not go first.
- Full detail (keyboard maps, degradation behaviour, per-group breakdowns)
belongs in a normal `<section>` further down the page with `h3` + `<ul>`.
- Measure before finishing:
`.claude/skills/update-project-docs/scripts/wiki-block-lengths.sh` must exit 0.
## Indentation and list markup
Prose lists use plain `<ul>` / `<ol>` with `<li>` children placed as **direct
children of their `<section>`**; the stylesheet's `.main-content section > ul` /
`> ol` rules supply the indent, marker, and item rhythm (the global reset zeroes
list padding, so without them a list renders its markers outside the content
column). A list nested inside a component (card, timeline step, callout) is
deliberately outside those rules and carries its own layout. Do not add ad-hoc inline
`padding-left` / `list-style` to fix indentation, and in new content keep a
`<ul>` out of a `<p>` — the browser closes the paragraph for you and the i18n
key then no longer matches the DOM.
**Never scope a rule for a block-level content element with `:not([class])`.**
The scroll-reveal pass in `script.js` adds `reveal-on-scroll` to every
below-the-fold direct child of a `<section>` at runtime, so such a rule matches
in the static file (and in jsdom, which does not run that script) and then
silently stops applying in the real browser. `a:not([class])` for inline links
is fine — only a section's own children get classed. `client/tests/wiki-i18n.test.ts`
enforces this.
**Verify wiki CSS in a browser that ran the page's JavaScript**, not against the
static HTML. Reliable local check:
```bash
python3 -m http.server 8899 # from the repo root
# CHROME_BIN defaults per platform:
# macOS /Applications/Google Chrome.app/Contents/MacOS/Google Chrome
# Linux google-chrome (or chromium / chromium-browser)
# Windows C:/Program Files/Google/Chrome/Application/chrome.exe
CHROME_BIN="${CHROME_BIN:-/Applications/Google Chrome.app/Contents/MacOS/Google Chrome}"
"$CHROME_BIN" --headless=new --virtual-time-budget=6000 \
--dump-dom http://127.0.0.1:8899/wiki/index.html \
| grep -o '<ul[^>]*>' # shows the classes script.js actually applied
```
Do not narrow the page (hiding other sections, isolating a fragment) before
checking: moving a block above the fold changes whether it gets the reveal
class, which is exactly the variable under test.
## What stays English (do NOT translate)
Anything inside `<code>`, commands, file/dir paths, URLs, env-var names, HTTP
methods/status codes, numbers + units, CLI flags, code identifiers, brand/product
names, hook event names (`PreToolUse`, `Stop`, …), and tool names (`Bash`,
`Agent`). Translate only the prose around them. A block that is entirely
code/identifier/product-name needs no entry (it correctly falls back to English).
## Verify, then bust caches
- Verify coverage against the live DOM with `jsdom` (already in
`client/node_modules`): load `index.html`, run the `HTML_SEL` selectors with
the same `norm(s) = s.replace(/\s+/g," ").trim()`, and confirm every
real-prose block matches a dictionary key. Misses that are pure
code/identifiers are fine; prose misses are bugs.
- Run `npx vitest run tests/wiki-i18n.test.ts` from `client/` to
check live-DOM prose and label coverage, metadata and assistive attributes,
inline-tag preservation, and asset-version synchronization.
- The service worker is cache-first. After editing `index.html`, `style.css`,
`script.js`, or `i18n-content.js`, bump that asset's query string
(`style.css?v=N`, `script.js?v=N`, `i18n-content.js?v=N`) in `index.html`,
bump the SAME value in the `PRECACHE` list in `wiki/sw.js`, and bump
`CACHE_NAME`. The fetch handler matches on the full URL including the query,
so a precache entry whose version differs from the page's is never served —
first load and offline silently fall back to the network for that asset.
- Run `npm run format` before committing (the static wiki files are Prettier-managed).
© hoangsonww · MIT · hoangsonww/Claude-Code-Agent-Monitor