localization

Use when translating, syncing, or reviewing JA/EN/ZH documentation pages, nav labels, news rows, summaries, or localized metadata.

SKILL.md

GitHub

Localization

Read First

  • /ops/style-writing.md, especially ZH translation rules.
  • The Japanese source page.
  • Existing EN/ZH sibling pages for local style.

Rules

  • JA is the source of truth.
  • Do not localize unless the owner explicitly requested it in the current task.
  • Preserve slug, navId, section, workflow paths, model filenames, node names, and code spans.
  • Sync the complete source-page state, including structured authoring data such as media markup, workflow shortcodes, shortcode options, and measurements. Do not limit the comparison to prose or to the latest Japanese diff.
  • Use the same created / updated as the JA page unless the task is a locale-only correction.
  • EN should be natural and concise, not literal.
  • ZH should be simplified Chinese, neutral, and preserve UI/model/node names in English where appropriate. Rebuild sentences as Chinese instead of mirroring Japanese word order (/ops/style-writing.md 12-5, 12-6).

Workflow

  1. Compare the complete JA source page with every locale in scope, then identify all content and authoring data that needs syncing.
  2. Update locale pages and locale nav entries together when new localized pages are requested.
  3. Preserve Gyazo and workflow links unless the owner supplied locale-specific assets.
  4. Re-read every translation side by side with the Japanese, from the top, as a separate pass after translating (/ops/style-writing.md section 13). Fix leftover literal phrasing and over-adaptation alike: keep the meaning and the owner's tone, but make it read naturally to a native reader. For ZH, also check the Japanese-pattern list in section 12-6. Tell the owner the notable fixes from this pass.
  5. Build and inspect the rendered page in every locale. Check visible and accessible strings generated by layouts, shortcodes, and client components—not only translated Markdown—including tooltips, popup headings, status text, and action labels.
  6. Check search/nav output.

Checks

  • npm run check:content
  • npm run build

Pipeline

Part of the article pipeline in article-authoring. Only run it when the owner asks for it in the current task.

After this, for a newly published page only: news-readme-update — the news row is added in every language that now has a page, not just JA. Translating an update to an existing page does not add a News row by default.

When a locale page is newly created, that locale's nav entry (src/_data/nav.en.yml or nav.zh.yml) is part of this step — only for the locales actually requested, and so is the ADR's record of localization scope if ia-nav-adr produced one.