Maintain i18n

Skill pikacss/pikacss/.claude/skills/maintain-i18n

Maintain the zh-TW docs locale — translate missing pages, incrementally sync stale translations against English source drift, and enforce Taiwan terminology. Use when adding or updating docs/zh-tw pages, when English docs changed and translations must catch up, or when checking translation freshness.From its SKILL.md

Install

npx -y skills add pikacss/pikacss --skill maintain-i18n

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

7 stars7 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

5.2 KB, as published. Nobody here has run it

maintain-i18n

Maintains docs/zh-tw/** as a strictly aligned translation of the English docs. English is the single source of truth; never edit English pages from this skill.

Source of Truth

Concern	Source
Content	English pages under `docs/` (excluding `docs/zh-tw/**`)
Sync state	`translation:` frontmatter block in each zh page (committed, reviewable)
Style rules	`references/translation-style.md`
Terminology	`references/terminology.md` (TW-vs-PRC) + `references/glossary.md` (PikaCSS terms)
Machine lint list	`scripts/maintain-i18n/forbidden-terms.json`
Out of scope	Generated `docs/api/*.md` (English-only by policy; only `api/index.md` is translated)

Commands

pnpm maintain-i18n:status                 # page states + freshness table; writes task files to .maintain-i18n/tasks/
pnpm maintain-i18n:status --json          # machine-readable report
pnpm maintain-i18n:status --mark-synced <docs/zh-tw/page.md ...>   # record current English blob+commit after translating
pnpm maintain-i18n:lint                   # forbidden-PRC-term scan, anchor conformity, fixture comment-only invariant
pnpm --filter @pikacss/docs test          # example tests (includes zh-tw fixtures)
pnpm docs:build                           # dead-link + twoslash gate

Workflow

Analyze. Run pnpm maintain-i18n:status. Read the task files in .maintain-i18n/tasks/. Each task carries the page state (missing / stale / orphaned / untracked), freshness %, and for stale pages the exact English diff (git diff <sourceBlob> <currentBlob>) plus the fallback verdict (incremental vs full-retranslate, see Fallback Rules below).
Translate.
- missing: translate the full current English page. Read references/translation-style.md and both terminology files FIRST. Preserve structure 1:1 (heading tree, container types, snippet includes, tables).
- stale + incremental verdict: map each diff hunk to the corresponding zh section (hunks carry heading context) and edit only the affected passages. Do not reflow or reword untouched passages.
- stale + full-retranslate verdict (task file says so): retranslate the whole page from current English, reusing established terminology.
- orphaned: the English source was deleted or renamed. For renames (task file proposes the target) git mv the zh page, then treat as stale. For deletions, delete the zh page and fix inbound links.
- Fixtures: if the diff touches files under docs/.examples/, update the mirrored docs/zh-tw/.examples/ copies — comments translated, everything else byte-identical.
Mark synced. pnpm maintain-i18n:status --mark-synced <pages...>. Refuses to run if the English source has uncommitted changes (state must anchor to committed blobs).
Validate. In order: pnpm maintain-i18n:lint → pnpm --filter @pikacss/docs test → pnpm docs:build. All three must pass before handoff.

Hard Rules

Code blocks: translate comments ONLY. Identifiers, string values, CSS output, file paths, shell commands stay byte-identical. This is stricter than MDN practice (which also translates strings/output) — do not relax it.
Every zh heading carries the English anchor: ## 安裝 {#installation}. The {#id} sequence must equal the English page's slug sequence (lint-enforced).
Internal links → /zh-tw/...; links into /api/* and external URLs unchanged.
When unsure whether to translate a term: keep English, use it consistently, and flag it for glossary addition.
Never edit docs/api/*.md (generated) or English source pages.
Never invent content absent from the English source; zh-TW is a mirror, not an editorial fork.
A translated body does not mean a synced page. Verify translation.sourceBlob separately: git diff prints index <old>..<new> on the English file's diff header, and <old> is its pre-change blob hash — if the zh-TW frontmatter still carries that hash, the body was updated by hand and --mark-synced was skipped, leaving the tracked hash stale even though the prose is current. Read it from the diff header; do not mutate the tree to find it. Both available-hooks.md and create-a-plugin.md shipped in exactly that state during #116.

Fallback Rules (full-retranslate instead of hunk-level sync)

The status script decides per page; the agent follows the task file. Full retranslation when ANY of:

changed-line ratio (added + deleted) / current-total > 0.6
English file renamed with git similarity < 50% (treated as delete + new page)
heading-id sequence LCS against the recorded source < 0.7 (section reordering — hunk mapping unreliable)
recorded sourceBlob unretrievable (git cat-file fails) and sourceCommit unknown

Runtime State

.maintain-i18n/ (gitignored) holds ephemeral task files only. Durable sync state lives in each zh page's translation: frontmatter — committed, reviewed in PRs, survives clones.