i18n Standard

This standard references the i18n governance system of the momei project (translation-governance.md / i18n.md) and is adapted for dependfix, focusing on three i18n tracks: README multi-language, docs translation, and platform UI localization.

1. Goals and scope

This standard defines the collaboration rules for dependfix multilingual documentation and product strings, aiming to avoid half-complete languages where "page is translated, system chain is not wired up, quality gates are not in place".

Scope includes:

• README multilingual versions (README.md Chinese source + README.en-US.md translation etc.)
• Documentation site public pages (docs/ Chinese source + docs/i18n/<locale>/ translation)
• Management platform UI strings (apps/platform/i18n/locales/<locale>.json)
• Language-release related fallback strategies and quality gates

2. Language release tiering

New languages are admitted via tiered gating:

• draft: only local validation allowed, not exposed in public language switcher.
• ui-ready: complete core UI, language entry, fallback chain and basic quality validation, can be publicly displayed.
• seo-ready: on top of ui-ready, also covers email, SEO, sitemap and regression checks, can be used as official global language release.

Release principles:

• Default to ui-ready first, avoid pursuing full translation at once.
• Languages that fail regression validation must not be upgraded to seo-ready.
• Fast-iteration modules may temporarily fall back to Chinese source, but must explicitly mark this in docs and todo.

2.1 Documentation translation freshness tiering

Documentation translation is governed by tier based on page responsibility, not uniformly "every page must be synced within 30 days":

Tier	Freshness SLA	Allowed content form	Current typical scope
must-sync	30 days	Public entry, operation-equivalent translation	en-US home, quick start, README
summary-sync	45 days	Summary sync, keep source-of-truth back-link	Roadmap summary, core high-frequency standard pages
source-only	No day SLA, but must explicitly declare "Chinese source-of-truth priority"	Keep locale URL entry page, no commitment to continuous maintenance of body	Low-frequency design pages, low-frequency Guides, deep Standards

Supplementary constraints:

1. source-only pages must explicitly provide a Chinese source entry, never retain old bodies that look like complete translations but are actually long out-of-date.
2. source-only pages must not continue to occupy locale nav and sidebar main entries, to avoid users misjudging the maintenance commitment scope.
3. summary-sync pages may be structural-summarized, but must cover key changes that have entered quality gates, nav main entries or contribution flows in this round.

2.2 Current locale documentation scope

Locale	Current commitment scope
en-US	Public entry pages stay must-sync; roadmap, development guide and core high-frequency standard pages stay summary-sync; design pages, low-frequency Guides degrade to source-only
zh-CN	Source of truth (no freshness SLA)

3. Language publishing tiers

The locale declaration in docs/.vitepress/config.ts follows language-code keys (BCP 47 lowercase language + uppercase region, e.g. en-US, zh-CN):

// docs/.vitepress/config.ts (simplified)
locales: {
    root: { label: '简体中文', lang: 'zh-CN' },
    'en-US': { label: 'English', lang: 'en-US' },
}

The root locale is the Chinese source of truth and is always present. Other locales are added by tier when they meet their entry criteria.

4. README multilingual naming convention

Each package has only one canonical README:

• Source file: packages/<name>/README.md (Chinese source of truth)

• Translation file: packages/<name>/README.<locale>.md (e.g. README.en-US.md)

• Switching links at top: every README must contain <!-- i18n: switch --> separator and include both directions:

  <!-- i18n: switch -->
  [简体中文](./README.md) | [English](./README.en-US.md)

Packages with only the Chinese source (no translation yet) must still include the <!-- i18n: switch --> marker, with English link commented out, to make it easy to add later.

The CI pnpm check:readme-i18n validates: bidirectional links, section structure consistency (auto-compare README.md and README.en-US.md have the same heading hierarchy), and no missing <!-- i18n: switch --> markers.

5. Terminology consistency

Cross-locale technical terms must stay aligned. docs/standards/terminology.md is the source of truth for term translation pairs. Each new locale should first translate terminology.md before translating other documents.

6. Contribution flow

6.1 Discover: contributor reads the relevant Chinese source file first, confirms the Chinese is up-to-date (not lagging behind the source), then translates. 6.2 Translate: manual translation + human review (do NOT rely on AI translation tools for technical terms / code blocks / Markdown tables). 6.3 Sync check: ensure the translated version keeps the same heading hierarchy (CI auto-validates). 6.4 Submit PR: PR title uses docs(i18n): translate <file path> to <locale>, marking i18n-sync label. 6.5 Blocker matrix: <!-- i18n: blocker --> annotations in translation files are explicit blockers for merging (e.g. unfinished feature blocks translation).

8. PR recommendations

For PRs that touch multilingual docs:

• Separate Chinese source modifications and translation sync into two PRs (Chinese source first, translation sync second)
• If only the Chinese source changes, do not block translation sync PRs — let translations catch up in follow-up
• Translation sync PRs should bump last_sync: YYYY-MM-DD frontmatter (CI auto-validates freshness tier SLA)
• source-only tier pages do not require translation sync PRs; only need to confirm Chinese source is up-to-date

9. Quality gate

Gate	Trigger	Validator	Failure action
Bidirectional README link check	PR / commit	pnpm check:readme-i18n	Block merge
README section structure consistency	PR / commit	pnpm check:readme-i18n	Block merge
VitePress anchor / link check	PR / commit	pnpm run check:docs	Block merge
Locale key parity	PR / commit	pnpm i18n:audit:missing	Block merge
must-sync tier freshness	Weekly cron	pnpm i18n:audit:stale	Warning + open stale-issue
summary-sync tier freshness	Monthly cron	pnpm i18n:audit:stale	Warning

10. References

• momei translation-governance — original reference
• momei i18n.md — original standard
• docs-and-readme-i18n design — dependfix-specific design (English version pending)
• Contribution flow section 6 — contribution process (see above)