Skip to content

Turn any idea, plan, or codebase into a beautiful interactive diagram. An agent skill for Claude Code, Codex, and more.

feat(i18n): select bundled Viewer catalogs by locale with per-key overrides

uygnoeybfd3a96cb8b7
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 451f85cd..29e44690 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,11 @@ All notable changes are documented here. Format loosely follows [Keep a Changelo
> Development identity: `v3.0.2-dev.1`. Not a stable release.
+### Changed
+- **Bundled Viewer catalogs selected by `meta.locale`.** `archify/locales/manifest.json` enrolls package-owned catalogs (`en`, `zh-CN`, `es`, `ko`); English and Simplified Chinese moved from renderer tuples into the same data. Each message resolves as valid `meta.translations` value → selected bundled catalog → English, so a one-key override keeps the rest of the language. Enrolling another language is a data-only change. Catalogs load relative to the installed package, never from the working directory, and standalone HTML still embeds only the resolved Viewer messages. (#588)
+- **Intentional differences from 3.0.1.** Locale-only `es`/`ko` now render Spanish/Korean UI instead of English. A partial `meta.translations` (including for `zh-CN`) now falls through to the same-language bundled catalog before English; in 3.0.1 every unsupplied key became English. Equivalent tag casing such as `zh-cn` selects the bundled catalog and emits its canonical tag; region and script variants such as `zh-Hant` still fall back to English. An unbundled tag whose translations are all unusable now falls back to English `lang` as well. Omitted-locale, `en`, `zh-CN`, and complete-catalog inputs render unchanged.
+- **Locale diagnostics.** `i18n/translation-coverage` now reports the final resolved coverage and lists missing keys with their English source text; rejected overrides (unknown keys, placeholder mismatches) are reported separately as `i18n/invalid-translation` and keep the lower-priority message.
+
## [3.0.1] — 2026-09-28
### Changed
diff --git a/README.md b/README.md
index 262a6c92..91e7698f 100644
--- a/README.md
+++ b/README.md
@@ -343,7 +343,7 @@ Settings:
}
```
-`meta.locale` localizes page title, Legend, states/errors, a11y, HTML/SVG `lang`—never authored content. `en`/`zh-CN` are built in; other languages, including Spanish (`es`), need `meta.translations` (canonical message key → translated string; see `examples/locales/es.json`), or the renderer falls back to English and discloses it. Static omits `animation`; `classic` defaults.
+`meta.locale` localizes page title, Legend, states/errors, a11y, HTML/SVG `lang`—never authored content. `en`, `zh-CN`, `es`, and `ko` are bundled and need only `meta.locale`; `meta.translations` (canonical message key → translated string) overrides individual keys and keeps the rest of the language. Other languages supply their catalog there (see `archify/examples/locales/`), or the renderer falls back to English and discloses it. Static omits `animation`; `classic` defaults.
</details>
diff --git a/README_EN.md b/README_EN.md
index 262a6c92..91e7698f 100644
--- a/README_EN.md
+++ b/README_EN.md
@@ -343,7 +343,7 @@ Settings:
}
```
-`meta.locale` localizes page title, Legend, states/errors, a11y, HTML/SVG `lang`—never authored content. `en`/`zh-CN` are built in; other languages, including Spanish (`es`), need `meta.translations` (canonical message key → translated string; see `examples/locales/es.json`), or the renderer falls back to English and discloses it. Static omits `animation`; `classic` defaults.
+`meta.locale` localizes page title, Legend, states/errors, a11y, HTML/SVG `lang`—never authored content. `en`, `zh-CN`, `es`, and `ko` are bundled and need only `meta.locale`; `meta.translations` (canonical message key → translated string) overrides individual keys and keeps the rest of the language. Other languages supply their catalog there (see `archify/examples/locales/`), or the renderer falls back to English and discloses it. Static omits `animation`; `classic` defaults.
</details>
diff --git a/README_JA.md b/README_JA.md
index 11cc405c..87e6c2ad 100644
--- a/README_JA.md
+++ b/README_JA.md
@@ -333,7 +333,7 @@ node bin/archify.mjs deliver workflow examples/agent-tool-call.workflow.json /tm
}
```
-`meta.locale=en|zh-CN` はページタイトル、Legend、状態/エラー、アクセシビリティ、HTML/SVG の `lang` をローカライズします(記述された内容自体は変更しません)。該当しない場合は省略し、要求された言語の文言はそのまま維持し、英語へフォールバックした場合はその旨を明示してください。静止出力では `animation` は省略され、`classic` が既定になります。
+`meta.locale=en|zh-CN|es|ko` はページタイトル、Legend、状態/エラー、アクセシビリティ、HTML/SVG の `lang` をローカライズします(記述された内容自体は変更しません)。該当しない場合は省略し、要求された言語の文言はそのまま維持し、英語へフォールバックした場合はその旨を明示してください。静止出力では `animation` は省略され、`classic` が既定になります。
</details>
diff --git a/README_ZH.md b/README_ZH.md
index 87bb22cd..e622a54e 100644
--- a/README_ZH.md
+++ b/README_ZH.md
@@ -344,7 +344,7 @@ node bin/archify.mjs deliver workflow examples/agent-tool-call.workflow.json /tm
}
```
-不设置 `animation` 时结果完全静态;`classic` 始终是默认视觉预设。设计评审、发布说明和技术文档可以显式选择 `editorial`,获得暖纸张与深墨色的编辑风格,同时保持几何完全不变。将 `meta.locale` 设为任意合法语言标签,可选择 `<html lang>`、默认图例、无障碍文案和所有固定 Viewer UI。`en` 与 `zh-CN` 已内置;西班牙语等其他语言需同时提供 `meta.translations`(规范消息键到译文字符串的映射,`examples/locales/es.json` 是完整示例),否则渲染器回退为英文并在 stderr 中说明。作者编写的标题、节点、关系和卡片不会被机器翻译。未带该字段的旧文件仍然有效,并默认使用英文。对于既未内置也未提供 `meta.translations` 的创作语言,应省略 `meta.locale`、保持 authored content 使用用户要求的语言,并主动告知用户固定 Viewer UI 与 `<html lang>` 回退为英文,因此该成品不属于完整本地化。
+不设置 `animation` 时结果完全静态;`classic` 始终是默认视觉预设。设计评审、发布说明和技术文档可以显式选择 `editorial`,获得暖纸张与深墨色的编辑风格,同时保持几何完全不变。将 `meta.locale` 设为任意合法语言标签,可选择 `<html lang>`、默认图例、无障碍文案和所有固定 Viewer UI。`en`、`zh-CN`、`es` 与 `ko` 已内置,只需设置 `meta.locale`;`meta.translations`(规范消息键到译文字符串的映射)可逐键覆盖,其余文案保持所选语言。其他语言需在该字段中提供完整目录(参见 `archify/examples/locales/`),否则渲染器回退为英文并在 stderr 中说明。作者编写的标题、节点、关系和卡片不会被机器翻译。未带该字段的旧文件仍然有效,并默认使用英文。对于既未内置也未提供 `meta.translations` 的创作语言,应省略 `meta.locale`、保持 authored content 使用用户要求的语言,并主动告知用户固定 Viewer UI 与 `<html lang>` 回退为英文,因此该成品不属于完整本地化。
</details>
diff --git a/archify.zip b/archify.zip
index be5cde98..1a8347eb 100644
Binary files a/archify.zip and b/archify.zip differ
diff --git a/archify/locales/README.md b/archify/locales/README.md
new file mode 100644
index 00000000..267a1fd1
--- /dev/null
+++ b/archify/locales/README.md
@@ -0,0 +1,32 @@
+# Bundled Viewer catalogs
+
+`manifest.json` enrolls the catalogs that `meta.locale` selects automatically.
+The renderer reads only the files listed there, relative to this installed
+directory. It never scans this directory, the working directory, or anywhere
+else for language files.
+
+`en.json` is the canonical message set and the final fallback. Every other
+catalog is validated against it per key: a missing, unknown, or
+placeholder-mismatched entry falls back to English and is reported when that
+locale is rendered. A new UI key may therefore ship in English first.
+
+Each message resolves as: valid `meta.translations` value → selected bundled
+catalog → English. See [the authoring contract](../references/authoring-contract.md).
+
+To enroll a language, add its complete catalog here and one manifest entry.
+No renderer or schema change is needed. Locale tags match case-insensitively;
+region and script variants (for example `zh-Hant`) are distinct tags and are
+never collapsed onto another catalog.
+
+| Locale | Origin | Review status |
+| --- | --- | --- |
+| `en` | Archify source strings | Canonical |
+| `zh-CN` | #108 | Maintained with the renderer |
+| `es` | Juan Pablo Tamayo (#457, moved to data in #586) | Complete; not independently native-reviewed |
+| `ko` | uygnoey (#457) | Complete; not independently native-reviewed |
+
+Completeness checks prove key and placeholder coverage, not native wording,
+plural grammar, right-to-left layout, or glyph coverage.
+
+Other reusable, unenrolled examples live in `../examples/locales/`; supply
+them through `meta.translations`.
diff --git a/archify/locales/en.json b/archify/locales/en.json
new file mode 100644
index 00000000..9685e310
--- /dev/null
+++ b/archify/locales/en.json
@@ -0,0 +1,440 @@
+{
+ "page.title": "{title} Diagram",
+ "diagram.description.architecture": "An architecture diagram generated by Archify.",
+ "diagram.description.workflow": "A workflow diagram generated by Archify.",
+ "diagram.description.sequence": "A sequence diagram generated by Archify.",
+ "diagram.description.dataflow": "A data-flow diagram generated by Archify.",
+ "diagram.description.lifecycle": "A lifecycle diagram generated by Archify.",
+ "node.focus": "Focus {label}",
+ "node.focus.detail": "Focus {label}, {detail}",
+ "node.context.architecture": "Architecture component",
+ "node.context.workflow": "Workflow node",
+ "node.context.sequence": "Sequence participant",
+ "node.context.dataflow": "Data-flow node",
+ "node.context.lifecycle": "Lifecycle state",
+ "legend.title": "Legend",
+ "legend.architecture.frontend": "Frontend",
+ "legend.architecture.backend": "Backend",
+ "legend.architecture.database": "Database",
+ "legend.architecture.cloud": "Cloud",
+ "legend.architecture.security": "Security",
+ "legend.architecture.messagebus": "Message bus",
+ "legend.architecture.external": "External",
+ "legend.workflow.frontend": "User UI",
+ "legend.workflow.backend": "Agent logic",
+ "legend.workflow.security": "Policy",
+ "legend.workflow.messagebus": "Tool action",
+ "legend.workflow.database": "Context / trace",
+ "legend.workflow.cloud": "Cloud service",
+ "legend.workflow.external": "External system",
+ "legend.sequence.emphasis": "main request",
+ "legend.sequence.return": "return",
+ "legend.sequence.security": "security",
+ "legend.sequence.dashed": "async trace",
+ "legend.sequence.default": "message",
+ "legend.dataflow.emphasis": "primary data",
+ "legend.dataflow.security": "policy / PII",
+ "legend.dataflow.dashed": "async batch",
+ "legend.dataflow.database": "data store",
+ "legend.dataflow.default": "data flow",
+ "legend.lifecycle.start": "initial state",
+ "legend.lifecycle.active": "active",
+ "legend.lifecycle.waiting": "waiting",
+ "legend.lifecycle.decision": "decision",
+ "legend.lifecycle.success": "success",
+ "legend.lifecycle.failure": "failure / exit",
+ "legend.lifecycle.neutral": "neutral",
+ "legend.lifecycle.external": "external",
+ "legend.lifecycle.final": "final state",
+ "viewer.kind.frontend": "Frontend",
+ "viewer.kind.backend": "Backend",
+ "viewer.kind.database": "Database",
+ "viewer.kind.cloud": "Cloud",
+ "viewer.kind.security": "Security",
+ "viewer.kind.messagebus": "Message bus",
+ "viewer.kind.external": "External",
+ "viewer.kind.neutral": "Neutral",
+ "viewer.kind.node": "Node",
+ "viewer.kind.start": "Start",
+ "viewer.kind.active": "Active",
+ "viewer.kind.waiting": "Waiting",
+ "viewer.kind.decision": "Decision",
+ "viewer.kind.success": "Success",
+ "viewer.kind.failure": "Failure",
+ "viewer.toolbar.actions": "Diagram actions",
+ "viewer.theme.toggle.title": "Toggle theme (T)",
+ "viewer.theme.toggle": "Toggle color theme",
+ "viewer.theme.dark": "Dark",
+ "viewer.theme.light": "Light",
+ "viewer.preset.choose.title": "Choose visual style (S cycles)",
+ "viewer.preset.choose": "Choose visual style",
+ "viewer.preset.style": "Style",
+ "viewer.preset.menu": "Visual style",
+ "viewer.preset.identity": "Visual identity",
+ "viewer.preset.cycles": "to cycle",
+ "viewer.preset.classic": "Classic",
+ "viewer.preset.classic.short": "Classic",
+ "viewer.preset.classic.hint": "Stable technical default",
+ "viewer.preset.flow": "Signal Flow",
+ "viewer.preset.flow.short": "Flow",
+ "viewer.preset.flow.hint": "Motion-forward presentation",
+ "viewer.preset.blueprint": "Blueprint",
+ "viewer.preset.blueprint.hint": "Engineering review",
+ "viewer.preset.editorial": "Editorial",
+ "viewer.preset.editorial.hint": "Publication and launch notes",
+ "viewer.preset.badge.signalFlow": "SIGNAL FLOW",
+ "viewer.preset.badge.blueprint": "BLUEPRINT / REV 01",
+ "viewer.preset.badge.editorial": "EDITORIAL / FIELD NOTE",
+ "viewer.preset.badge.editorialPlate": "ARCHIFY / PLATE 04",
+ "viewer.preset.current": "Visual style: {style}. Choose visual style",
+ "viewer.motion.live": "Live",
+ "viewer.motion.still": "Still",
+ "viewer.motion.pause": "Pause motion",
+ "viewer.motion.resume": "Resume motion",
+ "viewer.motion.reduced": "Motion paused by reduced-motion preference",
+ "viewer.motion.hidden": "Motion paused while this page is hidden",
+ "viewer.motion.yielding": "Pause motion; currently yielding to {owner}",
+ "viewer.motion.yielding.title": "Live preview enabled · yielding to {owner}",
+ "viewer.owner.route": "Route Probe",
+ "viewer.owner.lens": "Semantic Lens",
+ "viewer.owner.relationship": "Relationship Preview",
+ "viewer.owner.intent": "Intent Trace",
+ "viewer.owner.focus": "semantic focus",
+ "viewer.owner.legend": "legend preview",
+ "viewer.owner.reader": "reader interaction",
+ "viewer.present.enter": "Enter presentation stage",
+ "viewer.present.enter.title": "Presentation stage (F)",
+ "viewer.present.exit": "Exit presentation stage",
+ "viewer.present.exit.title": "Exit presentation stage (F or Escape)",
+ "viewer.present.present": "Present",
+ "viewer.present.exit.label": "Exit",
+ "viewer.export.button": "Export",
+ "viewer.export.button.title": "Export diagram (E)",
+ "viewer.export.diagram": "Export diagram",
+ "viewer.export.menu": "Export",
+ "viewer.export.subtitle": "Portable, clean outputs",
+ "viewer.export.share": "Share",
+ "viewer.export.shareCard": "Share Card",
+ "viewer.export.routeShareCard": "Route Share Card",
+ "viewer.export.reachShareCard": "Reach Share Card",
+ "viewer.export.copyDiagram": "Copy diagram",
+ "viewer.export.clipboardPng": "PNG to clipboard",
+ "viewer.export.raster": "Raster images",
+ "viewer.export.image": "Image",
+ "viewer.export.lossless": "Lossless image",
+ "viewer.export.compact": "Compact image",
+ "viewer.export.modern": "Modern image",
+ "viewer.export.vectorMotion": "Vector and motion",
+ "viewer.export.vectorMotion.heading": "Vector & motion",
+ "viewer.export.editable": "Editable vector",
+ "viewer.export.svg.auto": "SVG · Auto",
+ "viewer.export.svg.auto.hint": "Matches host theme",
+ "viewer.export.svg.light": "SVG · Light",
+ "viewer.export.svg.light.hint": "Always light",
+ "viewer.export.svg.dark": "SVG · Dark",
+ "viewer.export.svg.dark.hint": "Always dark",
+ "viewer.export.motion6s": "6s motion",
+ "viewer.export.unsupported": "Not supported by this browser",
+ "viewer.export.clipboardUnsupported": "Clipboard image write not supported by this browser",
+ "viewer.export.clipboardUnsupported.short": "Clipboard image write not supported in this browser.",
+ "viewer.export.motionUnavailable": "Motion capture unavailable in this browser",
+ "viewer.export.webmUnavailable": "WebM unavailable in this browser",
+ "viewer.export.failed": "Export failed: {message}",
+ "viewer.export.unknownVariant": "Unknown Share Card variant: {variant}",
+ "viewer.export.routeRequired": "Trace a route before exporting a Route Share Card",
+ "viewer.export.reachRequired": "Trace authored reach before exporting a Reach Share Card",
+ "viewer.export.unknown": "unknown",
+ "viewer.export.routeFailed": "Route Share Card export failed: {message}",
+ "viewer.export.reachFailed": "Reach Share Card export failed: {message}",
+ "viewer.export.copyFailed": "Copy failed: {message}",
+ "viewer.export.copiedPng": "Copied PNG to clipboard",
+ "viewer.export.downloadedRoute": "Downloaded Route Share Card",
+ "viewer.export.downloadedReach": "Downloaded Reach Share Card",
+ "viewer.export.downloadedWebm": "Downloaded WebM",
+ "viewer.export.recording": "Recording 6 seconds of motion…",
+ "viewer.export.card.routeSummary.one": "Path: {source} → {target} · {count} step",
+ "viewer.export.card.routeSummary.other": "Path: {source} → {target} · {count} steps",
+ "viewer.export.card.reachSummary": "Authored {direction} from {origin} · {nodes} · {links} · max {hops}",
+ "viewer.export.card.node.one": "{count} node",
+ "viewer.export.card.node.other": "{count} nodes",
+ "viewer.export.card.link.one": "{count} link",
+ "viewer.export.card.link.other": "{count} links",
+ "viewer.export.card.hop.one": "{count} hop",
+ "viewer.export.card.hop.other": "{count} hops",
+ "viewer.export.card.routeBadge": "ARCHIFY · ROUTE · {hops}",
+ "viewer.export.card.reachBadge": "ARCHIFY · {direction} REACH",
+ "viewer.export.direction.upstream": "Upstream",
+ "viewer.export.direction.downstream": "Downstream",
+ "viewer.export.error.canvasUnavailable": "Canvas unavailable for {label}",
+ "viewer.export.error.contextUnavailable": "2D canvas context unavailable for {label}",
+ "viewer.export.error.toBlobUnavailable": "canvas.toBlob unavailable for {label}",
+ "viewer.export.error.toBlobNull": "canvas.toBlob returned no data for {label}",
+ "viewer.export.error.variantsCombined": "Share Card variants cannot be combined",
+ "viewer.export.error.viewerState": "Share Card export could not remove temporary viewer state",
+ "viewer.export.error.routeState": "Route Card export could not preserve the resolved route safely",
+ "viewer.export.error.reachState": "Reach Card export could not preserve authored reach safely",
+ "viewer.export.error.webmRequirements": "WebM motion export requires a trace animation and browser MediaRecorder support",
+ "viewer.export.error.mediaRecorder": "MediaRecorder failed",
+ "viewer.export.error.emptyWebm": "MediaRecorder produced an empty WebM",
+ "viewer.export.error.webmBackground": "SVG background could not be loaded for WebM export",
+ "viewer.guide.title": "Explore this system",
+ "viewer.focus.selectedNodes": "{count} selected nodes",
+ "viewer.guide.eyebrow": "Diagram guide",
+ "viewer.guide.close": "Close diagram guide",
+ "viewer.guide.inspecting": "Inspecting compiled semantics",
+ "viewer.guide.actions": "Diagram exploration actions",
+ "viewer.guide.find": "Find any node",
+ "viewer.guide.find.hint": "Search labels, responsibilities, kinds, and stable IDs.",
+ "viewer.guide.route": "Trace a route",
+ "viewer.guide.route.aria": "Trace a directed route",
+ "viewer.guide.route.hint": "Ask how two semantic nodes connect in authored direction.",
+ "viewer.guide.map": "See the whole system",
+ "viewer.guide.map.hint": "Open Semantic Radar with a live viewport and stable nodes.",
+ "viewer.guide.lens": "Compare semantic kinds",
+ "viewer.guide.lens.hint": "Count roles, reveal their traffic, and compare direct authored links.",
+ "viewer.guide.present": "Enter Presentation Stage",
+ "viewer.guide.present.hint": "Give the live diagram the viewport without changing export.",
+ "viewer.guide.shortcuts": "Additional keyboard shortcuts",
+ "viewer.guide.shortcut.export": "Export",
+ "viewer.guide.shortcut.theme": "Theme",
+ "viewer.guide.shortcut.style": "Style",
+ "viewer.guide.shortcut.reset": "Reset",
+ "viewer.guide.shortcut.zoomIn": "Zoom in",
+ "viewer.guide.shortcut.zoomOut": "Zoom out",
+ "viewer.guide.shortcut.close": "Close",
+ "viewer.guide.facts": "{nodes} · {relationships}",
+ "viewer.guide.fact.node.one": "{count} semantic node",
+ "viewer.guide.fact.node.other": "{count} semantic nodes",
+ "viewer.guide.fact.relationship.one": "{count} relationship",
+ "viewer.guide.fact.relationship.other": "{count} relationships",
+ "viewer.guide.open": "Open diagram guide",
+ "viewer.finder.title": "Find a node",
+ "viewer.finder.close": "Close node finder",
+ "viewer.finder.placeholder": "Search labels or IDs",
+ "viewer.finder.search": "Search diagram nodes",
+ "viewer.finder.results": "Diagram nodes",
+ "viewer.finder.empty": "No matching nodes",
+ "viewer.finder.result.focus": "Focus {label}",
+ "viewer.finder.result.routeStart": "Choose {label} as route start",
+ "viewer.finder.result.routeTarget": "Choose {label} as route destination, {links}",
+ "viewer.finder.status.empty": "No matching nodes",
+ "viewer.finder.status.count.one": "{count} matching node",
+ "viewer.finder.status.count.other": "{count} matching nodes",
+ "viewer.finder.noun.nodes": "nodes",
+ "viewer.finder.link.one": "{count} link",
+ "viewer.finder.link.other": "{count} links",
+ "viewer.finder.result.focus.one": "Focus {label}, {count} related connection",
+ "viewer.finder.result.focus.other": "Focus {label}, {count} related connections",
+ "viewer.finder.status.filtered": "{visible} of {available} {noun}",
+ "viewer.finder.status.all": "{available} {noun}",
+ "viewer.passport.eyebrow": "Semantic passport",
+ "viewer.passport.metadata": "Node metadata",
+ "viewer.passport.evidence": "Verified source evidence",
+ "viewer.passport.verified": "Verified source",
+ "viewer.passport.verificationScope": "Verified against local Git at the pinned revision. Remote access has not been checked.",
+ "viewer.passport.reach": "Authored reach",
+ "viewer.passport.reach.trace": "Trace authored reachability",
+ "viewer.passport.upstream": "Upstream",
+ "viewer.passport.downstream": "Downstream",
+ "viewer.passport.upstream.trace": "Trace upstream authored reachability",
+ "viewer.passport.downstream.trace": "Trace downstream authored reachability",
+ "viewer.passport.close": "Close semantic passport",
+ "viewer.passport.move": "Move semantic passport. Drag, use arrow keys, or press Home to reset.",
+ "viewer.passport.copy": "Copy link",
+ "viewer.passport.copy.focus": "Copy link to focused node",
+ "viewer.passport.relations": "Relations",
+ "viewer.passport.relations.show": "Show connected relationships",
+ "viewer.passport.relations.hide": "Hide connected relationships",
+ "viewer.passport.relations.list": "Connected relationships",
+ "viewer.passport.copyRelation": "Copy relation",
+ "viewer.passport.copyNode": "Copy node",
+ "viewer.passport.copyPinned": "Copy link to pinned relationship",
+ "viewer.passport.copySource": "Copy link to source node",
+ "viewer.passport.copy.focused.success": "Focused node link copied",
+ "viewer.passport.copy.pinned.success": "Pinned relationship link copied",
+ "viewer.passport.copy.focused.failed": "Could not copy focused node link",
+ "viewer.passport.copy.pinned.failed": "Could not copy pinned relationship link",
+ "viewer.passport.relationship.none": "No connected relationships",
+ "viewer.passport.relationship.count.one": "{count} relation",
+ "viewer.passport.relationship.count.other": "{count} relations",
+ "viewer.passport.relationship.show.one": "Show {count} connected relationship",
+ "viewer.passport.relationship.show.other": "Show {count} connected relationships",
+ "viewer.passport.relationship.summary": "{out} outgoing · {in} incoming{loops}",
+ "viewer.passport.relationship.loops": " · {count} loop",
+ "viewer.passport.relationship.explorer": "Direct relationship explorer",
+ "viewer.passport.relationship.help": "Use arrow keys to explore relationships. Press Enter or Space to pin details; Escape clears.",
+ "viewer.passport.relationship.loopsBack": "loops back",
+ "viewer.passport.relationship.connectsTo": "connects to",
+ "viewer.passport.relationship.connectsFrom": "connects from",
+ "viewer.passport.relationship.pinned": "Pinned relationship · {from} → {to} · {label}",
+ "viewer.passport.relationship.inspect": "Inspect relationship {index} of {total}: {from} to {to}, {label}. Press Enter for details.",
+ "viewer.passport.relationship.group.out": "Outgoing",
+ "viewer.passport.relationship.group.in": "Incoming",
+ "viewer.passport.relationship.group.loop": "Self loops",
+ "viewer.passport.relationship.row": "{group}: {relationship}, {neighbor}",
+ "viewer.passport.relationship.direction.out": "OUT →",
+ "viewer.passport.relationship.direction.in": "← IN",
+ "viewer.passport.relationship.direction.loop": "LOOP",
+ "viewer.passport.sourceCount.one": "{count} verified source reference",
+ "viewer.passport.sourceCount.other": "{count} verified source references",
+ "viewer.passport.sourceMarker": "SRC",
+ "viewer.passport.beacon.one": "{count} verified source; focus this node to inspect",
+ "viewer.passport.beacon.other": "{count} verified sources; focus this node to inspect",
+ "viewer.passport.repository.open": "Open verified repository revision {revision}",
+ "viewer.passport.source.open": "Open verified source {path} at revision {revision}",
+ "viewer.passport.source.openLink": "Open ↗",
+ "viewer.passport.reach.upstream.one": "Trace {count} upstream authored node",
+ "viewer.passport.reach.upstream.other": "Trace {count} upstream authored nodes",
+ "viewer.passport.reach.downstream.one": "Trace {count} downstream authored node",
+ "viewer.passport.reach.downstream.other": "Trace {count} downstream authored nodes",
+ "viewer.passport.reach.noUpstream": "No upstream authored nodes",
+ "viewer.passport.reach.noDownstream": "No downstream authored nodes",
+ "viewer.passport.reach.status": "{direction} · {nodes} nodes · {links} links · max {hops} hops",
+ "viewer.route.eyebrow": "Path",
+ "viewer.route.start": "Click where the path starts",
+ "viewer.route.start.find": "Find start",
+ "viewer.route.start.find.aria": "Find a route start",
+ "viewer.route.copy": "Copy link",
+ "viewer.route.copy.aria": "Copy link to traced route",
+ "viewer.route.clear": "Clear",
+ "viewer.route.clear.aria": "Clear route probe",
+ "viewer.route.traced": "Path",
+ "viewer.route.pickTwo": "Click two nodes on the diagram",
+ "viewer.route.pickOne": "Click a node on the diagram",
+ "viewer.route.controls": "Route journey controls",
+ "viewer.route.previous": "Previous route position",
+ "viewer.route.play": "Play route journey",
+ "viewer.route.pause": "Pause route journey",
+ "viewer.route.replay": "Replay route journey",
+ "viewer.route.next": "Next route position",
+ "viewer.route.journey": "Journey",
+ "viewer.route.pause.label": "Pause",
+ "viewer.route.replay.label": "Replay",
+ "viewer.route.overview": "Overview",
+ "viewer.route.overview.aria": "Show complete route overview",
+ "viewer.route.instructions": "Click a start, then an end. Paths follow the arrows.",
+ "viewer.route.destination": "Where does the path from {label} end?",
+ "viewer.route.destination.find": "Find target",
+ "viewer.route.destination.find.aria": "Find a reachable route destination",
+ "viewer.route.differentDestination": "Choose a different destination",
+ "viewer.route.distinct": "Pick two different nodes.",
+ "viewer.route.unreachable": "Cannot reach {label} from here",
+ "viewer.route.unreachable.detail": "{target} cannot be reached from {source} along the arrows. Pick a highlighted node.",
+ "viewer.route.start.instructions": "Next, pick the end. Only nodes you can reach will light up.",
+ "viewer.route.copy.success": "Traced route link copied",
+ "viewer.route.copy.failed": "Could not copy traced route link",
+ "viewer.route.position": "Route position {index} of {total}: {label}",
+ "viewer.route.step": "Step {index} of {total} · {phase} · {label}",
+ "viewer.route.motionRequired": "Automatic journey requires Live motion",
+ "viewer.route.trigger.clear": "Clear traced route",
+ "viewer.route.overview.status": "{nodes} · {hops} · shortest path",
+ "viewer.route.overview.node.one": "{count} node",
+ "viewer.route.overview.node.other": "{count} nodes",
+ "viewer.route.overview.hop.one": "{count} step",
+ "viewer.route.overview.hop.other": "{count} steps",
+ "viewer.route.phase.playing": "Playing",
+ "viewer.route.phase.complete": "Complete",
+ "viewer.route.phase.inspecting": "Inspecting",
+ "viewer.route.destination.count.one": "{count} reachable node is highlighted. Click it.",
+ "viewer.route.destination.count.other": "{count} reachable nodes are highlighted. Click one.",
+ "viewer.route.noOutgoing": "No arrows lead out of this node. Clear it and pick another start.",
+ "viewer.route.result.title": "{source} to {target}",
+ "viewer.route.finder.source.title": "Choose route start",
+ "viewer.route.finder.source.placeholder": "Search route sources",
+ "viewer.route.finder.source.empty": "No matching route sources",
+ "viewer.route.finder.source.results": "Nodes that can start a route",
+ "viewer.route.finder.source.noun": "route sources",
+ "viewer.route.finder.source.badge": "start",
+ "viewer.route.finder.target.title": "Destination from {label}",
+ "viewer.route.finder.target.placeholder": "Search reachable destinations",
+ "viewer.route.finder.target.empty": "No matching reachable destinations",
+ "viewer.route.finder.target.results": "Reachable route destinations",
+ "viewer.route.finder.target.noun": "reachable destinations",
+ "viewer.route.hop.one": "{count} hop",
+ "viewer.route.hop.other": "{count} hops",
+ "viewer.lens.eyebrow": "Semantic lens",
+ "viewer.lens.title": "Compare system roles",
+ "viewer.lens.close": "Close semantic lens",
+ "viewer.lens.instruction": "Choose up to two semantic kinds. One reveals its real traffic; two compare only direct authored relationships.",
+ "viewer.lens.kinds": "Semantic kinds",
+ "viewer.lens.choose": "Choose a kind to inspect its nodes and touching relationships.",
+ "viewer.lens.copy": "Copy link to semantic lens",
+ "viewer.lens.clear": "Clear semantic lens",
+ "viewer.lens.open": "Open semantic lens",
+ "viewer.lens.openActive": "Open active semantic lens",
+ "viewer.lens.legend": "Semantic legend",
+ "viewer.lens.legend.inspect.one": "Inspect {label}, {count} node",
+ "viewer.lens.legend.inspect.other": "Inspect {label}, {count} nodes",
+ "viewer.lens.kind.count.one": "{label}, {count} node",
+ "viewer.lens.kind.count.other": "{label}, {count} nodes",
+ "viewer.lens.compare.one": "{first} → {second}: {forward} · {second} → {first}: {reverse} · {count} direct relationship",
+ "viewer.lens.compare.other": "{first} → {second}: {forward} · {second} → {first}: {reverse} · {count} direct relationships",
+ "viewer.lens.single": "{nodes} · {relationships} · connected peers remain visible",
+ "viewer.lens.node.one": "{count} {label} node",
+ "viewer.lens.node.other": "{count} {label} nodes",
+ "viewer.lens.relationship.one": "{count} touching relationship",
+ "viewer.lens.relationship.other": "{count} touching relationships",
+ "viewer.radar.title": "Semantic radar",
+ "viewer.radar.building": "Building overview",
+ "viewer.radar.openFull": "Open full semantic radar",
+ "viewer.radar.open": "Open radar",
+ "viewer.radar.close": "Close semantic radar",
+ "viewer.radar.surface": "Diagram overview. Click a node to focus it, or use arrow keys to pan.",
+ "viewer.radar.click": "Click node",
+ "viewer.radar.drag": "Drag to pan",
+ "viewer.radar.space": "Semantic radar needs more MAP space.",
+ "viewer.radar.nodes": "Semantic diagram radar nodes",
+ "viewer.radar.focus": "Focus {label} from Semantic Radar",
+ "viewer.radar.status": "{count} nodes · {viewport}",
+ "viewer.radar.fullMap": "{count} nodes · full map",
+ "viewer.radar.compacted": "Radar compacted to avoid covering the Semantic Passport or MAP controls.",
+ "viewer.radar.cancelWaiting": "Cancel semantic radar waiting for more MAP space",
+ "viewer.radar.needsSpace": "Semantic radar needs more visible MAP space",
+ "viewer.radar.viewport.full": "full map",
+ "viewer.radar.viewport.width": "{percent}% width",
+ "viewer.radar.viewport.scale": "{percent}% viewport",
+ "viewer.nav.controls": "Diagram view controls",
+ "viewer.nav.route": "Trace a directed route",
+ "viewer.nav.route.title": "Trace route (R)",
+ "viewer.nav.route.short": "PATH",
+ "viewer.nav.radar": "Open semantic radar",
+ "viewer.nav.radar.title": "Semantic radar (M)",
+ "viewer.nav.radar.short": "MAP",
+ "viewer.nav.lens": "Open semantic lens",
+ "viewer.nav.lens.title": "Semantic lens (L)",
+ "viewer.nav.lens.short": "LENS",
+ "viewer.nav.find": "Find a node",
+ "viewer.nav.find.title": "Find a node (/)",
+ "viewer.outline.title": "Node index",
+ "viewer.rail.show": "Notes & index",
+ "viewer.rail.controls": "Side panel",
+ "viewer.rail.collapse": "Collapse side panel",
+ "viewer.rail.bottom": "Move panel below the diagram",
+ "viewer.rail.right": "Move panel beside the diagram",
+ "viewer.nav.guide": "Open diagram guide",
+ "viewer.nav.guide.title": "Diagram guide (?)",
+ "viewer.nav.zoomOut": "Zoom out",
+ "viewer.nav.zoomOut.title": "Zoom out (-)",
+ "viewer.nav.reset": "Reset diagram view",
+ "viewer.nav.reset.title": "Reset view (0)",
+ "viewer.nav.read": "READ",
+ "viewer.nav.zoomIn": "Zoom in",
+ "viewer.nav.zoomIn.title": "Zoom in (+)",
+ "viewer.nav.camera": "{hint}. Reset diagram view",
+ "viewer.nav.camera.title": "{semantic}{hint} · reset view (0)",
+ "viewer.nav.camera.semantic": "Semantic camera active · ",
+ "viewer.nav.level.map": "MAP",
+ "viewer.nav.level.read": "READ",
+ "viewer.nav.level.full": "FULL",
+ "viewer.nav.level.auto": "AUTO",
+ "viewer.nav.detail.map": "Zoom in to reveal relationship labels and node context",
+ "viewer.nav.detail.read": "Zoom in again to reveal tags and annotations",
+ "viewer.nav.detail.full": "Full diagram detail",
+ "viewer.intent.summary": "{label}. {out} outgoing, {in} incoming{loops}. {total} connections. Press Enter for details.",
+ "viewer.intent.loops": ", {count} self loop",
+ "viewer.common.copied": "Copied",
+ "viewer.common.copyFailed": "Copy failed",
+ "viewer.common.copyLink": "Copy link",
+ "viewer.common.clear": "Clear",
+ "viewer.common.close": "Close"
+}
diff --git a/archify/examples/locales/es.json b/archify/locales/es.json
similarity index 100%
rename from archify/examples/locales/es.json
rename to archify/locales/es.json
diff --git a/archify/examples/locales/ko.json b/archify/locales/ko.json
similarity index 100%
rename from archify/examples/locales/ko.json
rename to archify/locales/ko.json
diff --git a/archify/locales/manifest.json b/archify/locales/manifest.json
new file mode 100644
index 00000000..2e93c019
--- /dev/null
+++ b/archify/locales/manifest.json
@@ -0,0 +1,8 @@
+{
+ "catalogs": [
+ { "locale": "en", "file": "en.json" },
+ { "locale": "zh-CN", "file": "zh-CN.json" },
+ { "locale": "es", "file": "es.json" },
+ { "locale": "ko", "file": "ko.json" }
+ ]
+}
diff --git a/archify/locales/zh-CN.json b/archify/locales/zh-CN.json
new file mode 100644
index 00000000..a603975b
--- /dev/null
+++ b/archify/locales/zh-CN.json
@@ -0,0 +1,440 @@
+{
+ "page.title": "{title}",
+ "diagram.description.architecture": "由 Archify 生成的架构图。",
+ "diagram.description.workflow": "由 Archify 生成的工作流图。",
+ "diagram.description.sequence": "由 Archify 生成的时序图。",
+ "diagram.description.dataflow": "由 Archify 生成的数据流图。",
+ "diagram.description.lifecycle": "由 Archify 生成的生命周期图。",
+ "node.focus": "聚焦{label}",
+ "node.focus.detail": "聚焦{label},{detail}",
+ "node.context.architecture": "架构组件",
+ "node.context.workflow": "工作流节点",
+ "node.context.sequence": "时序参与者",
+ "node.context.dataflow": "数据流节点",
+ "node.context.lifecycle": "生命周期状态",
+ "legend.title": "图例",
+ "legend.architecture.frontend": "前端",
+ "legend.architecture.backend": "后端",
+ "legend.architecture.database": "数据库",
+ "legend.architecture.cloud": "云服务",
+ "legend.architecture.security": "安全",
+ "legend.architecture.messagebus": "消息总线",
+ "legend.architecture.external": "外部系统",
+ "legend.workflow.frontend": "用户界面",
+ "legend.workflow.backend": "Agent 逻辑",
+ "legend.workflow.security": "策略",
+ "legend.workflow.messagebus": "工具操作",
+ "legend.workflow.database": "上下文 / 追踪",
+ "legend.workflow.cloud": "云服务",
+ "legend.workflow.external": "外部系统",
+ "legend.sequence.emphasis": "主路径请求",
+ "legend.sequence.return": "返回",
+ "legend.sequence.security": "安全",
+ "legend.sequence.dashed": "异步追踪",
+ "legend.sequence.default": "普通消息",
+ "legend.dataflow.emphasis": "主要数据",
+ "legend.dataflow.security": "策略 / PII",
+ "legend.dataflow.dashed": "异步批处理",
+ "legend.dataflow.database": "数据存储",
+ "legend.dataflow.default": "数据流",
+ "legend.lifecycle.start": "起点",
+ "legend.lifecycle.active": "进行中",
+ "legend.lifecycle.waiting": "等待",
+ "legend.lifecycle.decision": "决策",
+ "legend.lifecycle.success": "成功",
+ "legend.lifecycle.failure": "失败 / 退出",
+ "legend.lifecycle.neutral": "中性状态",
+ "legend.lifecycle.external": "外部状态",
+ "legend.lifecycle.final": "终态",
+ "viewer.kind.frontend": "前端",
+ "viewer.kind.backend": "后端",
+ "viewer.kind.database": "数据库",
+ "viewer.kind.cloud": "云服务",
+ "viewer.kind.security": "安全",
+ "viewer.kind.messagebus": "消息总线",
+ "viewer.kind.external": "外部系统",
+ "viewer.kind.neutral": "中性",
+ "viewer.kind.node": "节点",
+ "viewer.kind.start": "开始",
+ "viewer.kind.active": "活动",
+ "viewer.kind.waiting": "等待",
+ "viewer.kind.decision": "决策",
+ "viewer.kind.success": "成功",
+ "viewer.kind.failure": "失败",
+ "viewer.toolbar.actions": "图表操作",
+ "viewer.theme.toggle.title": "切换主题(T)",
+ "viewer.theme.toggle": "切换颜色主题",
+ "viewer.theme.dark": "深色",
+ "viewer.theme.light": "浅色",
+ "viewer.preset.choose.title": "选择视觉风格(S 循环切换)",
+ "viewer.preset.choose": "选择视觉风格",
+ "viewer.preset.style": "风格",
+ "viewer.preset.menu": "视觉风格",
+ "viewer.preset.identity": "视觉表达",
+ "viewer.preset.cycles": "循环切换",
+ "viewer.preset.classic": "经典",
+ "viewer.preset.classic.short": "经典",
+ "viewer.preset.classic.hint": "稳定的技术默认风格",
+ "viewer.preset.flow": "信号流",
+ "viewer.preset.flow.short": "流动",
+ "viewer.preset.flow.hint": "突出动态流向",
+ "viewer.preset.blueprint": "蓝图",
+ "viewer.preset.blueprint.hint": "工程评审",
+ "viewer.preset.editorial": "编辑风格",
+ "viewer.preset.editorial.hint": "适合发布与上线说明",
+ "viewer.preset.badge.signalFlow": "信号流",
+ "viewer.preset.badge.blueprint": "蓝图 / 修订 01",
+ "viewer.preset.badge.editorial": "编辑风格 / 现场笔记",
+ "viewer.preset.badge.editorialPlate": "ARCHIFY / 图版 04",
+ "viewer.preset.current": "当前视觉风格:{style}。选择视觉风格",
+ "viewer.motion.live": "动态",
+ "viewer.motion.still": "静态",
+ "viewer.motion.pause": "暂停动效",
+ "viewer.motion.resume": "恢复动效",
+ "viewer.motion.reduced": "已根据减少动态效果偏好暂停动效",
+ "viewer.motion.hidden": "页面不可见时已暂停动效",
+ "viewer.motion.yielding": "暂停动效;当前让位于{owner}",
+ "viewer.motion.yielding.title": "动态预览已启用 · 正在让位于{owner}",
+ "viewer.owner.route": "路径探测",
+ "viewer.owner.lens": "语义透镜",
+ "viewer.owner.relationship": "关系预览",
+ "viewer.owner.intent": "意图追踪",
+ "viewer.owner.focus": "语义聚焦",
+ "viewer.owner.legend": "图例预览",
+ "viewer.owner.reader": "读者交互",
+ "viewer.present.enter": "进入演示模式",
+ "viewer.present.enter.title": "演示模式(F)",
+ "viewer.present.exit": "退出演示模式",
+ "viewer.present.exit.title": "退出演示模式(F 或 Escape)",
+ "viewer.present.present": "演示",
+ "viewer.present.exit.label": "退出",
+ "viewer.export.button": "导出",
+ "viewer.export.button.title": "导出图表(E)",
+ "viewer.export.diagram": "导出图表",
+ "viewer.export.menu": "导出",
+ "viewer.export.subtitle": "便携、整洁的输出",
+ "viewer.export.share": "分享",
+ "viewer.export.shareCard": "分享卡片",
+ "viewer.export.routeShareCard": "路径分享卡片",
+ "viewer.export.reachShareCard": "可达范围分享卡片",
+ "viewer.export.copyDiagram": "复制图表",
+ "viewer.export.clipboardPng": "复制 PNG 到剪贴板",
+ "viewer.export.raster": "位图",
+ "viewer.export.image": "图像",
+ "viewer.export.lossless": "无损图像",
+ "viewer.export.compact": "紧凑图像",
+ "viewer.export.modern": "现代图像格式",
+ "viewer.export.vectorMotion": "矢量与动效",
+ "viewer.export.vectorMotion.heading": "矢量与动效",
+ "viewer.export.editable": "可编辑矢量图",
+ "viewer.export.svg.auto": "SVG · 自动",
+ "viewer.export.svg.auto.hint": "匹配宿主主题",
+ "viewer.export.svg.light": "SVG · 浅色",
+ "viewer.export.svg.light.hint": "始终浅色",
+ "viewer.export.svg.dark": "SVG · 深色",
+ "viewer.export.svg.dark.hint": "始终深色",
+ "viewer.export.motion6s": "6 秒动效",
+ "viewer.export.unsupported": "当前浏览器不支持",
+ "viewer.export.clipboardUnsupported": "当前浏览器不支持写入图片剪贴板",
+ "viewer.export.clipboardUnsupported.short": "此浏览器不支持写入图片剪贴板。",
+ "viewer.export.motionUnavailable": "当前浏览器无法录制动效",
+ "viewer.export.webmUnavailable": "当前浏览器不支持 WebM",
+ "viewer.export.failed": "导出失败:{message}",
+ "viewer.export.unknownVariant": "未知的分享卡片类型:{variant}",
+ "viewer.export.routeRequired": "请先追踪路径,再导出路径分享卡片",
+ "viewer.export.reachRequired": "请先追踪编写可达范围,再导出可达范围分享卡片",
+ "viewer.export.unknown": "未知错误",
+ "viewer.export.routeFailed": "路径分享卡片导出失败:{message}",
+ "viewer.export.reachFailed": "可达范围分享卡片导出失败:{message}",
+ "viewer.export.copyFailed": "复制失败:{message}",
+ "viewer.export.copiedPng": "已将 PNG 复制到剪贴板",
+ "viewer.export.downloadedRoute": "已下载路径分享卡片",
+ "viewer.export.downloadedReach": "已下载可达范围分享卡片",
+ "viewer.export.downloadedWebm": "已下载 WebM",
+ "viewer.export.recording": "正在录制 6 秒动效…",
+ "viewer.export.card.routeSummary.one": "路径:{source} → {target} · {count} 步",
+ "viewer.export.card.routeSummary.other": "路径:{source} → {target} · {count} 步",
+ "viewer.export.card.reachSummary": "从{origin}开始的编写{direction} · {nodes} · {links} · 最深 {hops}",
+ "viewer.export.card.node.one": "{count} 个节点",
+ "viewer.export.card.node.other": "{count} 个节点",
+ "viewer.export.card.link.one": "{count} 条连接",
+ "viewer.export.card.link.other": "{count} 条连接",
+ "viewer.export.card.hop.one": "{count} 跳",
+ "viewer.export.card.hop.other": "{count} 跳",
+ "viewer.export.card.routeBadge": "ARCHIFY · 路径 · {hops}",
+ "viewer.export.card.reachBadge": "ARCHIFY · {direction}可达范围",
+ "viewer.export.direction.upstream": "上游",
+ "viewer.export.direction.downstream": "下游",
+ "viewer.export.error.canvasUnavailable": "无法为{label}使用画布",
+ "viewer.export.error.contextUnavailable": "无法为{label}创建二维画布上下文",
+ "viewer.export.error.toBlobUnavailable": "{label}无法使用 canvas.toBlob",
+ "viewer.export.error.toBlobNull": "{label}的 canvas.toBlob 未返回数据",
+ "viewer.export.error.variantsCombined": "无法同时组合多种分享卡片类型",
+ "viewer.export.error.viewerState": "分享卡片导出无法移除临时 Viewer 状态",
+ "viewer.export.error.routeState": "路径卡片导出无法安全保留已解析路径",
+ "viewer.export.error.reachState": "可达范围卡片导出无法安全保留编写的可达范围",
+ "viewer.export.error.webmRequirements": "WebM 动效导出需要追踪动画及浏览器 MediaRecorder 支持",
+ "viewer.export.error.mediaRecorder": "MediaRecorder 录制失败",
+ "viewer.export.error.emptyWebm": "MediaRecorder 生成了空的 WebM",
+ "viewer.export.error.webmBackground": "无法为 WebM 导出加载 SVG 背景",
+ "viewer.guide.title": "探索此系统",
+ "viewer.focus.selectedNodes": "已选择 {count} 个节点",
+ "viewer.guide.eyebrow": "图表指南",
+ "viewer.guide.close": "关闭图表指南",
+ "viewer.guide.inspecting": "正在检查已编译语义",
+ "viewer.guide.actions": "图表探索操作",
+ "viewer.guide.find": "查找任意节点",
+ "viewer.guide.find.hint": "搜索标签、职责、类型和稳定 ID。",
+ "viewer.guide.route": "追踪路径",
+ "viewer.guide.route.aria": "追踪有向路径",
+ "viewer.guide.route.hint": "查看两个语义节点如何按编写方向连接。",
+ "viewer.guide.map": "查看完整系统",
+ "viewer.guide.map.hint": "打开带实时视口和稳定节点的语义雷达。",
+ "viewer.guide.lens": "比较语义类型",
+ "viewer.guide.lens.hint": "统计角色、显示流量并比较直接编写的连接。",
+ "viewer.guide.present": "进入演示模式",
+ "viewer.guide.present.hint": "让实时图表占满视口,同时不改变导出。",
+ "viewer.guide.shortcuts": "其他键盘快捷键",
+ "viewer.guide.shortcut.export": "导出",
+ "viewer.guide.shortcut.theme": "主题",
+ "viewer.guide.shortcut.style": "风格",
+ "viewer.guide.shortcut.reset": "重置",
+ "viewer.guide.shortcut.zoomIn": "放大",
+ "viewer.guide.shortcut.zoomOut": "缩小",
+ "viewer.guide.shortcut.close": "关闭",
+ "viewer.guide.facts": "{nodes} · {relationships}",
+ "viewer.guide.fact.node.one": "{count} 个语义节点",
+ "viewer.guide.fact.node.other": "{count} 个语义节点",
+ "viewer.guide.fact.relationship.one": "{count} 条关系",
+ "viewer.guide.fact.relationship.other": "{count} 条关系",
+ "viewer.guide.open": "打开图表指南",
+ "viewer.finder.title": "查找节点",
+ "viewer.finder.close": "关闭节点查找器",
+ "viewer.finder.placeholder": "搜索标签或 ID",
+ "viewer.finder.search": "搜索图表节点",
+ "viewer.finder.results": "图表节点",
+ "viewer.finder.empty": "没有匹配的节点",
+ "viewer.finder.result.focus": "聚焦{label}",
+ "viewer.finder.result.routeStart": "选择{label}作为路径起点",
+ "viewer.finder.result.routeTarget": "选择{label}作为路径终点,{links}",
+ "viewer.finder.status.empty": "没有匹配的节点",
+ "viewer.finder.status.count.one": "{count} 个匹配节点",
+ "viewer.finder.status.count.other": "{count} 个匹配节点",
+ "viewer.finder.noun.nodes": "个节点",
+ "viewer.finder.link.one": "{count} 条连接",
+ "viewer.finder.link.other": "{count} 条连接",
+ "viewer.finder.result.focus.one": "聚焦{label},{count} 条相关连接",
+ "viewer.finder.result.focus.other": "聚焦{label},{count} 条相关连接",
+ "viewer.finder.status.filtered": "{visible}/{available} {noun}",
+ "viewer.finder.status.all": "{available} {noun}",
+ "viewer.passport.eyebrow": "语义护照",
+ "viewer.passport.metadata": "节点元数据",
+ "viewer.passport.evidence": "已验证的源代码证据",
+ "viewer.passport.verified": "已验证来源",
+ "viewer.passport.verificationScope": "已按固定修订版本验证本地 Git 证据,未检查远程访问权限。",
+ "viewer.passport.reach": "编写可达范围",
+ "viewer.passport.reach.trace": "追踪编写的可达性",
+ "viewer.passport.upstream": "上游",
+ "viewer.passport.downstream": "下游",
+ "viewer.passport.upstream.trace": "追踪上游编写可达性",
+ "viewer.passport.downstream.trace": "追踪下游编写可达性",
+ "viewer.passport.close": "关闭语义护照",
+ "viewer.passport.move": "移动语义护照。可拖动、使用方向键移动,或按 Home 恢复自动位置。",
+ "viewer.passport.copy": "复制链接",
+ "viewer.passport.copy.focus": "复制聚焦节点的链接",
+ "viewer.passport.relations": "关系",
+ "viewer.passport.relations.show": "显示关联关系",
+ "viewer.passport.relations.hide": "隐藏关联关系",
+ "viewer.passport.relations.list": "关联关系",
+ "viewer.passport.copyRelation": "复制关系",
+ "viewer.passport.copyNode": "复制节点",
+ "viewer.passport.copyPinned": "复制固定关系的链接",
+ "viewer.passport.copySource": "复制来源节点的链接",
+ "viewer.passport.copy.focused.success": "已复制聚焦节点链接",
+ "viewer.passport.copy.pinned.success": "已复制固定关系链接",
+ "viewer.passport.copy.focused.failed": "无法复制聚焦节点链接",
+ "viewer.passport.copy.pinned.failed": "无法复制固定关系链接",
+ "viewer.passport.relationship.none": "没有关联关系",
+ "viewer.passport.relationship.count.one": "{count} 条关系",
+ "viewer.passport.relationship.count.other": "{count} 条关系",
+ "viewer.passport.relationship.show.one": "显示 {count} 条关联关系",
+ "viewer.passport.relationship.show.other": "显示 {count} 条关联关系",
+ "viewer.passport.relationship.summary": "{out} 条出向 · {in} 条入向{loops}",
+ "viewer.passport.relationship.loops": " · {count} 条自环",
+ "viewer.passport.relationship.explorer": "直接关系浏览器",
+ "viewer.passport.relationship.help": "使用方向键浏览关系。按 Enter 或空格键固定详情;按 Escape 清除。",
+ "viewer.passport.relationship.loopsBack": "回环",
+ "viewer.passport.relationship.connectsTo": "连接到",
+ "viewer.passport.relationship.connectsFrom": "连接自",
+ "viewer.passport.relationship.pinned": "已固定关系 · {from} → {to} · {label}",
+ "viewer.passport.relationship.inspect": "检查第 {index}/{total} 条关系:{from} 到 {to},{label}。按 Enter 查看详情。",
+ "viewer.passport.relationship.group.out": "出向",
+ "viewer.passport.relationship.group.in": "入向",
+ "viewer.passport.relationship.group.loop": "自环",
+ "viewer.passport.relationship.row": "{group}:{relationship},{neighbor}",
+ "viewer.passport.relationship.direction.out": "出 →",
+ "viewer.passport.relationship.direction.in": "← 入",
+ "viewer.passport.relationship.direction.loop": "自环",
+ "viewer.passport.sourceCount.one": "{count} 个已验证来源引用",
+ "viewer.passport.sourceCount.other": "{count} 个已验证来源引用",
+ "viewer.passport.sourceMarker": "来源",
+ "viewer.passport.beacon.one": "{count} 个已验证来源;聚焦此节点以检查",
+ "viewer.passport.beacon.other": "{count} 个已验证来源;聚焦此节点以检查",
+ "viewer.passport.repository.open": "打开已验证的仓库修订版本 {revision}",
+ "viewer.passport.source.open": "打开修订版本 {revision} 中已验证的来源 {path}",
+ "viewer.passport.source.openLink": "打开 ↗",
+ "viewer.passport.reach.upstream.one": "追踪 {count} 个上游编写节点",
+ "viewer.passport.reach.upstream.other": "追踪 {count} 个上游编写节点",
+ "viewer.passport.reach.downstream.one": "追踪 {count} 个下游编写节点",
+ "viewer.passport.reach.downstream.other": "追踪 {count} 个下游编写节点",
+ "viewer.passport.reach.noUpstream": "没有上游编写节点",
+ "viewer.passport.reach.noDownstream": "没有下游编写节点",
+ "viewer.passport.reach.status": "{direction} · {nodes} 个节点 · {links} 条连接 · 最深 {hops} 跳",
+ "viewer.route.eyebrow": "路径",
+ "viewer.route.start": "点击路径的起点",
+ "viewer.route.start.find": "查找起点",
+ "viewer.route.start.find.aria": "查找路径起点",
+ "viewer.route.copy": "复制链接",
+ "viewer.route.copy.aria": "复制已追踪路径的链接",
+ "viewer.route.clear": "清除",
+ "viewer.route.clear.aria": "清除路径探测",
+ "viewer.route.traced": "路径",
+ "viewer.route.pickTwo": "在图上点两个节点",
+ "viewer.route.pickOne": "在图上点一个节点",
+ "viewer.route.controls": "路径旅程控制",
+ "viewer.route.previous": "上一个路径位置",
+ "viewer.route.play": "播放路径旅程",
+ "viewer.route.pause": "暂停路径旅程",
+ "viewer.route.replay": "重播路径旅程",
+ "viewer.route.next": "下一个路径位置",
+ "viewer.route.journey": "旅程",
+ "viewer.route.pause.label": "暂停",
+ "viewer.route.replay.label": "重播",
+ "viewer.route.overview": "总览",
+ "viewer.route.overview.aria": "显示完整路径总览",
+ "viewer.route.instructions": "先点起点,再点终点,沿箭头方向找路。",
+ "viewer.route.destination": "从{label}出发,走到哪里?",
+ "viewer.route.destination.find": "查找目标",
+ "viewer.route.destination.find.aria": "查找可达的路径目标",
+ "viewer.route.differentDestination": "选择其他目标",
+ "viewer.route.distinct": "请选两个不同的节点。",
+ "viewer.route.unreachable": "走不到{label}",
+ "viewer.route.unreachable.detail": "沿箭头方向,从{source}走不到{target}。请选一个高亮节点。",
+ "viewer.route.start.instructions": "接着选终点,能走到的节点会亮起。",
+ "viewer.route.copy.success": "已复制路径链接",
+ "viewer.route.copy.failed": "无法复制路径链接",
+ "viewer.route.position": "路径位置 {index}/{total}:{label}",
+ "viewer.route.step": "第 {index}/{total} 步 · {phase} · {label}",
+ "viewer.route.motionRequired": "自动旅程需要动态模式",
+ "viewer.route.trigger.clear": "清除已追踪路径",
+ "viewer.route.overview.status": "{nodes} · {hops} · 最短路径",
+ "viewer.route.overview.node.one": "{count} 个节点",
+ "viewer.route.overview.node.other": "{count} 个节点",
+ "viewer.route.overview.hop.one": "{count} 步",
+ "viewer.route.overview.hop.other": "{count} 步",
+ "viewer.route.phase.playing": "播放中",
+ "viewer.route.phase.complete": "已完成",
+ "viewer.route.phase.inspecting": "检查中",
+ "viewer.route.destination.count.one": "有 {count} 个能走到的节点已高亮,点一下。",
+ "viewer.route.destination.count.other": "有 {count} 个能走到的节点已高亮,点一个。",
+ "viewer.route.noOutgoing": "这个节点没有向外的箭头。清除后换一个起点。",
+ "viewer.route.result.title": "{source} 到 {target}",
+ "viewer.route.finder.source.title": "选择路径起点",
+ "viewer.route.finder.source.placeholder": "搜索路径来源",
+ "viewer.route.finder.source.empty": "没有匹配的路径来源",
+ "viewer.route.finder.source.results": "可作为路径起点的节点",
+ "viewer.route.finder.source.noun": "个路径来源",
+ "viewer.route.finder.source.badge": "起点",
+ "viewer.route.finder.target.title": "从{label}出发的目标",
+ "viewer.route.finder.target.placeholder": "搜索可达目标",
+ "viewer.route.finder.target.empty": "没有匹配的可达目标",
+ "viewer.route.finder.target.results": "可达路径目标",
+ "viewer.route.finder.target.noun": "个可达目标",
+ "viewer.route.hop.one": "{count} 跳",
+ "viewer.route.hop.other": "{count} 跳",
+ "viewer.lens.eyebrow": "语义透镜",
+ "viewer.lens.title": "比较系统角色",
+ "viewer.lens.close": "关闭语义透镜",
+ "viewer.lens.instruction": "最多选择两种语义类型。选择一种可显示其真实流量;选择两种只比较直接编写的关系。",
+ "viewer.lens.kinds": "语义类型",
+ "viewer.lens.choose": "选择一种类型以检查其节点和相连关系。",
+ "viewer.lens.copy": "复制语义透镜链接",
+ "viewer.lens.clear": "清除语义透镜",
+ "viewer.lens.open": "打开语义透镜",
+ "viewer.lens.openActive": "打开当前语义透镜",
+ "viewer.lens.legend": "语义图例",
+ "viewer.lens.legend.inspect.one": "检查{label},{count} 个节点",
+ "viewer.lens.legend.inspect.other": "检查{label},{count} 个节点",
+ "viewer.lens.kind.count.one": "{label},{count} 个节点",
+ "viewer.lens.kind.count.other": "{label},{count} 个节点",
+ "viewer.lens.compare.one": "{first} → {second}:{forward} · {second} → {first}:{reverse} · 共 {count} 条直接关系",
+ "viewer.lens.compare.other": "{first} → {second}:{forward} · {second} → {first}:{reverse} · 共 {count} 条直接关系",
+ "viewer.lens.single": "{nodes} · {relationships} · 已连接节点保持可见",
+ "viewer.lens.node.one": "{count} 个{label}节点",
+ "viewer.lens.node.other": "{count} 个{label}节点",
+ "viewer.lens.relationship.one": "{count} 条相连关系",
+ "viewer.lens.relationship.other": "{count} 条相连关系",
+ "viewer.radar.title": "语义雷达",
+ "viewer.radar.building": "正在构建总览",
+ "viewer.radar.openFull": "打开完整语义雷达",
+ "viewer.radar.open": "打开雷达",
+ "viewer.radar.close": "关闭语义雷达",
+ "viewer.radar.surface": "图表总览。点击节点进行聚焦,或使用方向键平移。",
+ "viewer.radar.click": "点击节点",
+ "viewer.radar.drag": "拖动平移",
+ "viewer.radar.space": "语义雷达需要更多地图可见空间。",
+ "viewer.radar.nodes": "语义图表雷达节点",
+ "viewer.radar.focus": "从语义雷达聚焦{label}",
+ "viewer.radar.status": "{count} 个节点 · {viewport}",
+ "viewer.radar.fullMap": "{count} 个节点 · 完整地图",
+ "viewer.radar.compacted": "已收紧雷达,避免遮挡语义护照或地图控件。",
+ "viewer.radar.cancelWaiting": "取消等待更多地图空间的语义雷达",
+ "viewer.radar.needsSpace": "语义雷达需要更多可见地图空间",
+ "viewer.radar.viewport.full": "完整地图",
+ "viewer.radar.viewport.width": "宽度 {percent}%",
+ "viewer.radar.viewport.scale": "视口 {percent}%",
+ "viewer.nav.controls": "图表视图控制",
+ "viewer.nav.route": "追踪有向路径",
+ "viewer.nav.route.title": "追踪路径(R)",
+ "viewer.nav.route.short": "路径",
+ "viewer.nav.radar": "打开语义雷达",
+ "viewer.nav.radar.title": "语义雷达(M)",
+ "viewer.nav.radar.short": "地图",
+ "viewer.nav.lens": "打开语义透镜",
+ "viewer.nav.lens.title": "语义透镜(L)",
+ "viewer.nav.lens.short": "透镜",
+ "viewer.nav.find": "查找节点",
+ "viewer.nav.find.title": "查找节点(/)",
+ "viewer.outline.title": "节点索引",
+ "viewer.rail.show": "要点与索引",
+ "viewer.rail.controls": "侧栏",
+ "viewer.rail.collapse": "收起侧栏",
+ "viewer.rail.bottom": "移到图下方",
+ "viewer.rail.right": "移到图右侧",
+ "viewer.nav.guide": "打开图表指南",
+ "viewer.nav.guide.title": "图表指南(?)",
+ "viewer.nav.zoomOut": "缩小",
+ "viewer.nav.zoomOut.title": "缩小(-)",
+ "viewer.nav.reset": "重置图表视图",
+ "viewer.nav.reset.title": "重置视图(0)",
+ "viewer.nav.read": "阅读",
+ "viewer.nav.zoomIn": "放大",
+ "viewer.nav.zoomIn.title": "放大(+)",
+ "viewer.nav.camera": "{hint}。重置图表视图",
+ "viewer.nav.camera.title": "{semantic}{hint} · 重置视图(0)",
+ "viewer.nav.camera.semantic": "语义相机已启用 · ",
+ "viewer.nav.level.map": "概览",
+ "viewer.nav.level.read": "阅读",
+ "viewer.nav.level.full": "完整",
+ "viewer.nav.level.auto": "自动",
+ "viewer.nav.detail.map": "放大以显示关系标签和节点上下文",
+ "viewer.nav.detail.read": "再次放大以显示标签和注释",
+ "viewer.nav.detail.full": "完整图表详情",
+ "viewer.intent.summary": "{label}。{out} 条出向,{in} 条入向{loops}。共 {total} 条连接。按 Enter 查看详情。",
+ "viewer.intent.loops": ",{count} 条自环",
+ "viewer.common.copied": "已复制",
+ "viewer.common.copyFailed": "复制失败",
+ "viewer.common.copyLink": "复制链接",
+ "viewer.common.clear": "清除",
+ "viewer.common.close": "关闭"
+}
diff --git a/archify/references/authoring-contract.md b/archify/references/authoring-contract.md
index 623473f9..822c0e4c 100644
--- a/archify/references/authoring-contract.md
+++ b/archify/references/authoring-contract.md
@@ -75,24 +75,33 @@ legend label overrides, and cards. A bilingual diagram still
chooses one primary locale for the Viewer; follow an explicit primary-language
request, then prompt order or conversation dominance.
-`en` and `zh-CN` are built-in Viewer catalogs and need nothing further. For
-every other `meta.locale`, also set `meta.translations`: an object mapping the
-renderer's canonical message keys (`catalogKeys()` in
+Bundled Viewer catalogs are enrolled in `locales/manifest.json`: currently
+`en`, `zh-CN`, `es`, and `ko`. For these, `meta.locale` alone selects the full
+catalog. Tags match case-insensitively (`zh-cn` selects `zh-CN`), but region
+and script variants are distinct: `zh-Hant`, `es-MX`, or `ko-KR` select no
+bundled catalog.
+
+`meta.translations` is an optional per-key override: an object mapping the
+renderer's canonical message keys (`locales/en.json`, or `catalogKeys()` in
`renderers/shared/i18n.mjs`) to translated strings whose `{placeholder}` tokens
-match the English source exactly. Reuse suitable translations from `examples/locales/` or a previously reviewed
-catalog; Spanish uses `examples/locales/es.json`. Translate missing keys or adapt terminology when the diagram needs it;
-use the English source to check keys and placeholders. Example catalogs may
-lag new Viewer keys; validation reports those gaps and uses English for them. A key that is missing, unrecognized, or has mismatched
-placeholders falls back to its English string — `validate`/`render`/`deliver`
-report the resulting coverage to stderr — rather than breaking the render or
-silently shipping an untranslated string as if it were translated.
-
-For older dev inputs using only `meta.locale: "es"`, copy the Spanish catalog
-into `meta.translations` before rendering again. Existing standalone HTML
-keeps its embedded translations.
+match the English source exactly. Each message resolves as: valid
+`meta.translations` value → the selected bundled catalog → English. For a
+bundled locale, supply only the keys whose wording the diagram needs to change;
+the rest of the language is kept. Omitting the field or supplying `{}` means no
+override. For a language without a bundled catalog, supply the catalog here.
+Reuse suitable translations from `examples/locales/` or a previously reviewed
+catalog, translate missing keys, and use the English source to check keys and
+placeholders.
+
+An unknown key or a value with mismatched placeholders is rejected and keeps
+the lower-priority message; `validate`/`render`/`deliver` report it as
+`i18n/invalid-translation`. Keys that still resolve to English in a
+non-English locale are reported as `i18n/translation-coverage`, with the missing
+keys and their English source text; add exactly those keys to repair the gap.
+Coverage describes the final resolved catalog, not the size of the override.
For a requested language you cannot supply `meta.translations` for, do not
-write a `meta.locale` with no built-in catalog and no translations. Keep every
+write a `meta.locale` with no bundled catalog and no translations. Keep every
reader-facing authored string in the requested language, omit `meta.locale` so
the renderer safely uses English, and explicitly tell the user that fixed
Viewer UI and `<html lang>` remain English and the artifact is not fully localized.
diff --git a/archify/references/authoring-defaults.md b/archify/references/authoring-defaults.md
index ea3b41a0..1ae97dde 100644
--- a/archify/references/authoring-defaults.md
+++ b/archify/references/authoring-defaults.md
@@ -32,7 +32,7 @@ Examples show field shape, not legal values or source facts. Read the mode schem
## Presentation and modes
-Use one primary authored language from the user's choice or the request/conversation. Set `meta.locale` for built-in English (`en`) or Simplified Chinese (`zh-CN`); for other languages, including Spanish (`es`), supply `meta.translations` with reusable UI translations, or disclose the fixed Viewer UI and `<html lang>` English fallback. Keep exact product, code, protocol, command, API, and environment names while localizing surrounding explanation. See [Language consistency](authoring-contract.md#language-consistency) for bilingual cases.
+Use one primary authored language from the user's choice or the request/conversation. Set `meta.locale`; `en`, `zh-CN`, `es`, and `ko` select a bundled Viewer catalog with nothing further. For other languages, supply `meta.translations` with reusable UI translations, or disclose the fixed Viewer UI and `<html lang>` English fallback. Keep exact product, code, protocol, command, API, and environment names while localizing surrounding explanation. See [Language consistency](authoring-contract.md#language-consistency) for bilingual cases.
Omit `meta.visual_preset` for classic, `meta.subtitle` for a title-only header, `meta.legend` for truthful auto, and `meta.engineering_profile` for an ordinary system overview. Explicit styles and a subtitle require a user request. Use legend or deployment ownership under the [legend](authoring-contract.md#legend-contract) or [engineering profile](authoring-contract.md#engineering-profile-default) contracts. Branding is optional and explicit when a node names a real product; [Brand marks](brand-marks.md) gives lookup and capture rules for that branch. Never let a badge replace semantic type, label, or relationship facts. Set required `meta.output` to a portable POSIX-relative `.html` path within the working directory; see [Output path contracts](delivery-contract.md#output-path-contracts) for native path exceptions.
diff --git a/archify/renderers/shared/cli.mjs b/archify/renderers/shared/cli.mjs
index bc4a5e3b..ce8e5c39 100644
--- a/archify/renderers/shared/cli.mjs
+++ b/archify/renderers/shared/cli.mjs
@@ -18,55 +18,76 @@ import {
removeOwnedRegularFile,
verifyAtomicOutput,
} from './atomic-output.mjs';
-import { resolveLocale, translateMessage, registerLocale, SUPPORTED_LOCALES } from './i18n.mjs';
+import { resolveLocale, translateMessage, registerLocale, englishSourceFor, SUPPORTED_LOCALES } from './i18n.mjs';
import { prepareDiagramBrandMarks } from './brand-marks.mjs';
const outputPathGuards = new Map();
let renderCandidateSequence = 0;
-// meta.locale is renderer-owned Viewer UI, not authored content.
-// en and zh-CN ship as built-in catalogs.
-// Any other tag needs meta.translations (validated against the English
-// message-key set, layered over English per-key so partial/invalid entries
-// never break rendering) or it falls back to the English Viewer chrome —
-// the same "omit locale, disclose the fallback" contract as before, just
-// resolved from data instead of a hard-coded enum. See i18n.mjs.
+// meta.locale is renderer-owned Viewer UI, not authored content. Each message
+// resolves as: valid meta.translations value → bundled catalog enrolled in
+// locales/manifest.json → English (see i18n.mjs). A tag with neither a bundled
+// catalog nor a usable override falls back to the English Viewer chrome.
+// Every fallback is disclosed on stderr unconditionally so render/deliver/
+// validate report it even without ARCHIFY_DIAGNOSTIC_FORMAT.
+function warnLocale(diagnostic) {
+ recordDiagnostic({ severity: 'warning', ...diagnostic });
+ console.warn(`archify: ${diagnostic.message}`);
+}
+
function applyLocaleTranslations(diagramType, diagram) {
const locale = diagram.meta?.locale;
if (!locale) return;
- const translations = diagram.meta?.translations;
- if (translations && Object.keys(translations).length) {
- const report = registerLocale(locale, translations);
- if (report.missingKeys.length || report.unknownKeys.length || report.placeholderMismatches.length) {
- recordDiagnostic({
- code: 'i18n/translation-coverage',
- severity: 'warning',
- message: `meta.translations for locale ${JSON.stringify(locale)} covers ${report.coveredKeys}/${report.totalKeys} renderer-owned messages (${Math.round(report.coverage * 100)}%); uncovered keys fall back to English.`,
- subject: { diagramType, path: '/meta/translations' },
- evidence: {
- missingKeys: report.missingKeys.slice(0, 10),
- missingKeysTotal: report.missingKeys.length,
- unknownKeys: report.unknownKeys.slice(0, 10),
- unknownKeysTotal: report.unknownKeys.length,
- placeholderMismatches: report.placeholderMismatches.slice(0, 10),
- placeholderMismatchesTotal: report.placeholderMismatches.length,
- },
- supportedFixes: ['Add the missing keys to meta.translations.', 'Match each translation\'s {placeholders} to the English source string.'],
- });
- // Coverage is a fact about this render, not just a diagnostic-mode
- // artifact: print it to stderr unconditionally so `render`/`deliver`/
- // `validate` disclose the fallback even without ARCHIFY_DIAGNOSTIC_FORMAT.
- console.warn(`archify: meta.translations for locale ${JSON.stringify(locale)} covers ${report.coveredKeys}/${report.totalKeys} renderer-owned messages (${Math.round(report.coverage * 100)}%); uncovered keys fall back to English.`);
- }
- } else if (!SUPPORTED_LOCALES.includes(locale)) {
- recordDiagnostic({
+ const report = registerLocale(locale, diagram.meta?.translations);
+ const { unknownKeys, placeholderMismatches, appliedKeys } = report.override;
+ const rejected = unknownKeys.length + placeholderMismatches.length;
+ if (rejected) {
+ const kept = report.bundledLocale ? `bundled ${report.bundledLocale} message` : 'English message';
+ warnLocale({
+ code: 'i18n/invalid-translation',
+ message: `meta.translations for locale ${JSON.stringify(locale)} has ${rejected} unusable ${rejected === 1 ? 'entry' : 'entries'} (${unknownKeys.length} unknown, ${placeholderMismatches.length} placeholder mismatch); each keeps its ${kept}.`,
+ subject: { diagramType, path: '/meta/translations' },
+ evidence: {
+ locale,
+ unknownKeys: unknownKeys.slice(0, 10),
+ unknownKeysTotal: unknownKeys.length,
+ placeholderMismatches: placeholderMismatches.slice(0, 10),
+ placeholderMismatchesTotal: placeholderMismatches.length,
+ },
+ supportedFixes: ['Remove each unknown key or rename it to a canonical message key.', 'Use exactly the {placeholders} of the English source string for each mismatched key.'],
+ });
+ }
+ if (report.fallback) {
+ warnLocale({
code: 'i18n/locale-fallback',
- severity: 'warning',
- message: `meta.locale ${JSON.stringify(locale)} has no built-in catalog and no meta.translations; the Viewer chrome and <html lang> fall back to English.`,
+ message: `meta.locale ${JSON.stringify(locale)} has no bundled catalog and no usable meta.translations; the Viewer chrome and <html lang> fall back to English.`,
subject: { diagramType, path: '/meta/locale' },
- supportedFixes: ['Supply meta.translations for this locale.', `Use a built-in locale: ${SUPPORTED_LOCALES.join(', ')}.`],
+ evidence: { locale, bundledLocales: SUPPORTED_LOCALES },
+ supportedFixes: ['Supply meta.translations for this locale.', `Use a bundled locale: ${SUPPORTED_LOCALES.join(', ')}.`],
+ });
+ } else if (report.fallbackKeys.length) {
+ const source = [
+ report.bundledLocale && `the bundled ${report.bundledLocale} catalog`,
+ appliedKeys && `${appliedKeys} meta.translations ${appliedKeys === 1 ? 'entry' : 'entries'}`,
+ ].filter(Boolean).join(' and ');
+ const missingKeys = report.fallbackKeys.slice(0, 10);
+ warnLocale({
+ code: 'i18n/translation-coverage',
+ message: `meta.locale ${JSON.stringify(locale)} resolves ${report.translatedKeys}/${report.totalKeys} renderer-owned messages (${Math.floor(report.coverage * 100)}%) from ${source}; ${report.fallbackKeys.length} fall back to English.`,
+ subject: { diagramType, path: '/meta/translations' },
+ evidence: {
+ locale,
+ resolvedLocale: report.resolvedLocale,
+ bundledLocale: report.bundledLocale,
+ translatedKeys: report.translatedKeys,
+ totalKeys: report.totalKeys,
+ appliedOverrideKeys: appliedKeys,
+ missingKeys,
+ missingKeysTotal: report.fallbackKeys.length,
+ englishSource: englishSourceFor(missingKeys),
+ },
+ supportedFixes: ['Add each missing key to meta.translations, translating its English source string and keeping its {placeholders}.'],
});
- console.warn(`archify: meta.locale ${JSON.stringify(locale)} has no built-in catalog and no meta.translations; the Viewer chrome and <html lang> fall back to English.`);
}
}
diff --git a/archify/renderers/shared/i18n.mjs b/archify/renderers/shared/i18n.mjs
index 09f3879a..c3f2db22 100644
--- a/archify/renderers/shared/i18n.mjs
+++ b/archify/renderers/shared/i18n.mjs
@@ -1,4 +1,6 @@
-export const SUPPORTED_LOCALES = ['en', 'zh-CN'];
+import fs from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
export const DEFAULT_LOCALE = 'en';
const ESCAPE_MAP = { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' };
@@ -7,478 +9,59 @@ export function escapeHtml(value) {
return String(value ?? '').replace(/[&<>"']/g, (character) => ESCAPE_MAP[character]);
}
-// One catalog feeds renderer-time SVG/HTML copy and the selected runtime
-// catalog embedded in each standalone artifact. Keeping both built-in locales in one
-// tuple makes missing translations impossible to hide behind an English
-// fallback during development.
-const MESSAGE_PAIRS = {
- 'page.title': ['{title} Diagram', '{title}'],
- 'diagram.description.architecture': ['An architecture diagram generated by Archify.', '由 Archify 生成的架构图。'],
- 'diagram.description.workflow': ['A workflow diagram generated by Archify.', '由 Archify 生成的工作流图。'],
- 'diagram.description.sequence': ['A sequence diagram generated by Archify.', '由 Archify 生成的时序图。'],
- 'diagram.description.dataflow': ['A data-flow diagram generated by Archify.', '由 Archify 生成的数据流图。'],
- 'diagram.description.lifecycle': ['A lifecycle diagram generated by Archify.', '由 Archify 生成的生命周期图。'],
- 'node.focus': ['Focus {label}', '聚焦{label}'],
- 'node.focus.detail': ['Focus {label}, {detail}', '聚焦{label},{detail}'],
- 'node.context.architecture': ['Architecture component', '架构组件'],
- 'node.context.workflow': ['Workflow node', '工作流节点'],
- 'node.context.sequence': ['Sequence participant', '时序参与者'],
- 'node.context.dataflow': ['Data-flow node', '数据流节点'],
- 'node.context.lifecycle': ['Lifecycle state', '生命周期状态'],
- 'legend.title': ['Legend', '图例'],
-
- 'legend.architecture.frontend': ['Frontend', '前端'],
- 'legend.architecture.backend': ['Backend', '后端'],
- 'legend.architecture.database': ['Database', '数据库'],
- 'legend.architecture.cloud': ['Cloud', '云服务'],
- 'legend.architecture.security': ['Security', '安全'],
- 'legend.architecture.messagebus': ['Message bus', '消息总线'],
- 'legend.architecture.external': ['External', '外部系统'],
- 'legend.workflow.frontend': ['User UI', '用户界面'],
- 'legend.workflow.backend': ['Agent logic', 'Agent 逻辑'],
- 'legend.workflow.security': ['Policy', '策略'],
- 'legend.workflow.messagebus': ['Tool action', '工具操作'],
- 'legend.workflow.database': ['Context / trace', '上下文 / 追踪'],
- 'legend.workflow.cloud': ['Cloud service', '云服务'],
- 'legend.workflow.external': ['External system', '外部系统'],
- 'legend.sequence.emphasis': ['main request', '主路径请求'],
- 'legend.sequence.return': ['return', '返回'],
- 'legend.sequence.security': ['security', '安全'],
- 'legend.sequence.dashed': ['async trace', '异步追踪'],
- 'legend.sequence.default': ['message', '普通消息'],
- 'legend.dataflow.emphasis': ['primary data', '主要数据'],
- 'legend.dataflow.security': ['policy / PII', '策略 / PII'],
- 'legend.dataflow.dashed': ['async batch', '异步批处理'],
- 'legend.dataflow.database': ['data store', '数据存储'],
- 'legend.dataflow.default': ['data flow', '数据流'],
- 'legend.lifecycle.start': ['initial state', '起点'],
- 'legend.lifecycle.active': ['active', '进行中'],
- 'legend.lifecycle.waiting': ['waiting', '等待'],
- 'legend.lifecycle.decision': ['decision', '决策'],
- 'legend.lifecycle.success': ['success', '成功'],
- 'legend.lifecycle.failure': ['failure / exit', '失败 / 退出'],
- 'legend.lifecycle.neutral': ['neutral', '中性状态'],
- 'legend.lifecycle.external': ['external', '外部状态'],
- 'legend.lifecycle.final': ['final state', '终态'],
-
- 'viewer.kind.frontend': ['Frontend', '前端'],
- 'viewer.kind.backend': ['Backend', '后端'],
- 'viewer.kind.database': ['Database', '数据库'],
- 'viewer.kind.cloud': ['Cloud', '云服务'],
- 'viewer.kind.security': ['Security', '安全'],
- 'viewer.kind.messagebus': ['Message bus', '消息总线'],
- 'viewer.kind.external': ['External', '外部系统'],
- 'viewer.kind.neutral': ['Neutral', '中性'],
- 'viewer.kind.node': ['Node', '节点'],
- 'viewer.kind.start': ['Start', '开始'],
- 'viewer.kind.active': ['Active', '活动'],
- 'viewer.kind.waiting': ['Waiting', '等待'],
- 'viewer.kind.decision': ['Decision', '决策'],
- 'viewer.kind.success': ['Success', '成功'],
- 'viewer.kind.failure': ['Failure', '失败'],
-
- 'viewer.toolbar.actions': ['Diagram actions', '图表操作'],
- 'viewer.theme.toggle.title': ['Toggle theme (T)', '切换主题(T)'],
- 'viewer.theme.toggle': ['Toggle color theme', '切换颜色主题'],
- 'viewer.theme.dark': ['Dark', '深色'],
- 'viewer.theme.light': ['Light', '浅色'],
- 'viewer.preset.choose.title': ['Choose visual style (S cycles)', '选择视觉风格(S 循环切换)'],
- 'viewer.preset.choose': ['Choose visual style', '选择视觉风格'],
- 'viewer.preset.style': ['Style', '风格'],
- 'viewer.preset.menu': ['Visual style', '视觉风格'],
- 'viewer.preset.identity': ['Visual identity', '视觉表达'],
- 'viewer.preset.cycles': ['to cycle', '循环切换'],
- 'viewer.preset.classic': ['Classic', '经典'],
- 'viewer.preset.classic.short': ['Classic', '经典'],
- 'viewer.preset.classic.hint': ['Stable technical default', '稳定的技术默认风格'],
- 'viewer.preset.flow': ['Signal Flow', '信号流'],
- 'viewer.preset.flow.short': ['Flow', '流动'],
- 'viewer.preset.flow.hint': ['Motion-forward presentation', '突出动态流向'],
- 'viewer.preset.blueprint': ['Blueprint', '蓝图'],
- 'viewer.preset.blueprint.hint': ['Engineering review', '工程评审'],
- 'viewer.preset.editorial': ['Editorial', '编辑风格'],
- 'viewer.preset.editorial.hint': ['Publication and launch notes', '适合发布与上线说明'],
- 'viewer.preset.badge.signalFlow': ['SIGNAL FLOW', '信号流'],
- 'viewer.preset.badge.blueprint': ['BLUEPRINT / REV 01', '蓝图 / 修订 01'],
- 'viewer.preset.badge.editorial': ['EDITORIAL / FIELD NOTE', '编辑风格 / 现场笔记'],
- 'viewer.preset.badge.editorialPlate': ['ARCHIFY / PLATE 04', 'ARCHIFY / 图版 04'],
- 'viewer.preset.current': ['Visual style: {style}. Choose visual style', '当前视觉风格:{style}。选择视觉风格'],
- 'viewer.motion.live': ['Live', '动态'],
- 'viewer.motion.still': ['Still', '静态'],
- 'viewer.motion.pause': ['Pause motion', '暂停动效'],
- 'viewer.motion.resume': ['Resume motion', '恢复动效'],
- 'viewer.motion.reduced': ['Motion paused by reduced-motion preference', '已根据减少动态效果偏好暂停动效'],
- 'viewer.motion.hidden': ['Motion paused while this page is hidden', '页面不可见时已暂停动效'],
- 'viewer.motion.yielding': ['Pause motion; currently yielding to {owner}', '暂停动效;当前让位于{owner}'],
- 'viewer.motion.yielding.title': ['Live preview enabled · yielding to {owner}', '动态预览已启用 · 正在让位于{owner}'],
- 'viewer.owner.route': ['Route Probe', '路径探测'],
- 'viewer.owner.lens': ['Semantic Lens', '语义透镜'],
- 'viewer.owner.relationship': ['Relationship Preview', '关系预览'],
- 'viewer.owner.intent': ['Intent Trace', '意图追踪'],
- 'viewer.owner.focus': ['semantic focus', '语义聚焦'],
- 'viewer.owner.legend': ['legend preview', '图例预览'],
- 'viewer.owner.reader': ['reader interaction', '读者交互'],
- 'viewer.present.enter': ['Enter presentation stage', '进入演示模式'],
- 'viewer.present.enter.title': ['Presentation stage (F)', '演示模式(F)'],
- 'viewer.present.exit': ['Exit presentation stage', '退出演示模式'],
- 'viewer.present.exit.title': ['Exit presentation stage (F or Escape)', '退出演示模式(F 或 Escape)'],
- 'viewer.present.present': ['Present', '演示'],
- 'viewer.present.exit.label': ['Exit', '退出'],
-
- 'viewer.export.button': ['Export', '导出'],
- 'viewer.export.button.title': ['Export diagram (E)', '导出图表(E)'],
- 'viewer.export.diagram': ['Export diagram', '导出图表'],
- 'viewer.export.menu': ['Export', '导出'],
- 'viewer.export.subtitle': ['Portable, clean outputs', '便携、整洁的输出'],
- 'viewer.export.share': ['Share', '分享'],
- 'viewer.export.shareCard': ['Share Card', '分享卡片'],
- 'viewer.export.routeShareCard': ['Route Share Card', '路径分享卡片'],
- 'viewer.export.reachShareCard': ['Reach Share Card', '可达范围分享卡片'],
- 'viewer.export.copyDiagram': ['Copy diagram', '复制图表'],
- 'viewer.export.clipboardPng': ['PNG to clipboard', '复制 PNG 到剪贴板'],
- 'viewer.export.raster': ['Raster images', '位图'],
- 'viewer.export.image': ['Image', '图像'],
- 'viewer.export.lossless': ['Lossless image', '无损图像'],
- 'viewer.export.compact': ['Compact image', '紧凑图像'],
- 'viewer.export.modern': ['Modern image', '现代图像格式'],
- 'viewer.export.vectorMotion': ['Vector and motion', '矢量与动效'],
- 'viewer.export.vectorMotion.heading': ['Vector & motion', '矢量与动效'],
- 'viewer.export.editable': ['Editable vector', '可编辑矢量图'],
- 'viewer.export.svg.auto': ['SVG · Auto', 'SVG · 自动'],
- 'viewer.export.svg.auto.hint': ['Matches host theme', '匹配宿主主题'],
- 'viewer.export.svg.light': ['SVG · Light', 'SVG · 浅色'],
- 'viewer.export.svg.light.hint': ['Always light', '始终浅色'],
- 'viewer.export.svg.dark': ['SVG · Dark', 'SVG · 深色'],
- 'viewer.export.svg.dark.hint': ['Always dark', '始终深色'],
- 'viewer.export.motion6s': ['6s motion', '6 秒动效'],
- 'viewer.export.unsupported': ['Not supported by this browser', '当前浏览器不支持'],
- 'viewer.export.clipboardUnsupported': ['Clipboard image write not supported by this browser', '当前浏览器不支持写入图片剪贴板'],
- 'viewer.export.clipboardUnsupported.short': ['Clipboard image write not supported in this browser.', '此浏览器不支持写入图片剪贴板。'],
- 'viewer.export.motionUnavailable': ['Motion capture unavailable in this browser', '当前浏览器无法录制动效'],
- 'viewer.export.webmUnavailable': ['WebM unavailable in this browser', '当前浏览器不支持 WebM'],
- 'viewer.export.failed': ['Export failed: {message}', '导出失败:{message}'],
- 'viewer.export.unknownVariant': ['Unknown Share Card variant: {variant}', '未知的分享卡片类型:{variant}'],
- 'viewer.export.routeRequired': ['Trace a route before exporting a Route Share Card', '请先追踪路径,再导出路径分享卡片'],
- 'viewer.export.reachRequired': ['Trace authored reach before exporting a Reach Share Card', '请先追踪编写可达范围,再导出可达范围分享卡片'],
- 'viewer.export.unknown': ['unknown', '未知错误'],
- 'viewer.export.routeFailed': ['Route Share Card export failed: {message}', '路径分享卡片导出失败:{message}'],
- 'viewer.export.reachFailed': ['Reach Share Card export failed: {message}', '可达范围分享卡片导出失败:{message}'],
- 'viewer.export.copyFailed': ['Copy failed: {message}', '复制失败:{message}'],
- 'viewer.export.copiedPng': ['Copied PNG to clipboard', '已将 PNG 复制到剪贴板'],
- 'viewer.export.downloadedRoute': ['Downloaded Route Share Card', '已下载路径分享卡片'],
- 'viewer.export.downloadedReach': ['Downloaded Reach Share Card', '已下载可达范围分享卡片'],
- 'viewer.export.downloadedWebm': ['Downloaded WebM', '已下载 WebM'],
- 'viewer.export.recording': ['Recording 6 seconds of motion…', '正在录制 6 秒动效…'],
- 'viewer.export.card.routeSummary.one': ['Path: {source} → {target} · {count} step', '路径:{source} → {target} · {count} 步'],
- 'viewer.export.card.routeSummary.other': ['Path: {source} → {target} · {count} steps', '路径:{source} → {target} · {count} 步'],
- 'viewer.export.card.reachSummary': ['Authored {direction} from {origin} · {nodes} · {links} · max {hops}', '从{origin}开始的编写{direction} · {nodes} · {links} · 最深 {hops}'],
- 'viewer.export.card.node.one': ['{count} node', '{count} 个节点'],
- 'viewer.export.card.node.other': ['{count} nodes', '{count} 个节点'],
- 'viewer.export.card.link.one': ['{count} link', '{count} 条连接'],
- 'viewer.export.card.link.other': ['{count} links', '{count} 条连接'],
- 'viewer.export.card.hop.one': ['{count} hop', '{count} 跳'],
- 'viewer.export.card.hop.other': ['{count} hops', '{count} 跳'],
- 'viewer.export.card.routeBadge': ['ARCHIFY · ROUTE · {hops}', 'ARCHIFY · 路径 · {hops}'],
- 'viewer.export.card.reachBadge': ['ARCHIFY · {direction} REACH', 'ARCHIFY · {direction}可达范围'],
- 'viewer.export.direction.upstream': ['Upstream', '上游'],
- 'viewer.export.direction.downstream': ['Downstream', '下游'],
- 'viewer.export.error.canvasUnavailable': ['Canvas unavailable for {label}', '无法为{label}使用画布'],
- 'viewer.export.error.contextUnavailable': ['2D canvas context unavailable for {label}', '无法为{label}创建二维画布上下文'],
- 'viewer.export.error.toBlobUnavailable': ['canvas.toBlob unavailable for {label}', '{label}无法使用 canvas.toBlob'],
- 'viewer.export.error.toBlobNull': ['canvas.toBlob returned no data for {label}', '{label}的 canvas.toBlob 未返回数据'],
- 'viewer.export.error.variantsCombined': ['Share Card variants cannot be combined', '无法同时组合多种分享卡片类型'],
- 'viewer.export.error.viewerState': ['Share Card export could not remove temporary viewer state', '分享卡片导出无法移除临时 Viewer 状态'],
- 'viewer.export.error.routeState': ['Route Card export could not preserve the resolved route safely', '路径卡片导出无法安全保留已解析路径'],
- 'viewer.export.error.reachState': ['Reach Card export could not preserve authored reach safely', '可达范围卡片导出无法安全保留编写的可达范围'],
- 'viewer.export.error.webmRequirements': ['WebM motion export requires a trace animation and browser MediaRecorder support', 'WebM 动效导出需要追踪动画及浏览器 MediaRecorder 支持'],
- 'viewer.export.error.mediaRecorder': ['MediaRecorder failed', 'MediaRecorder 录制失败'],
- 'viewer.export.error.emptyWebm': ['MediaRecorder produced an empty WebM', 'MediaRecorder 生成了空的 WebM'],
- 'viewer.export.error.webmBackground': ['SVG background could not be loaded for WebM export', '无法为 WebM 导出加载 SVG 背景'],
-
- 'viewer.guide.title': ['Explore this system', '探索此系统'],
- 'viewer.focus.selectedNodes': ['{count} selected nodes', '已选择 {count} 个节点'],
-
- 'viewer.guide.eyebrow': ['Diagram guide', '图表指南'],
- 'viewer.guide.close': ['Close diagram guide', '关闭图表指南'],
- 'viewer.guide.inspecting': ['Inspecting compiled semantics', '正在检查已编译语义'],
- 'viewer.guide.actions': ['Diagram exploration actions', '图表探索操作'],
- 'viewer.guide.find': ['Find any node', '查找任意节点'],
- 'viewer.guide.find.hint': ['Search labels, responsibilities, kinds, and stable IDs.', '搜索标签、职责、类型和稳定 ID。'],
- 'viewer.guide.route': ['Trace a route', '追踪路径'],
- 'viewer.guide.route.aria': ['Trace a directed route', '追踪有向路径'],
- 'viewer.guide.route.hint': ['Ask how two semantic nodes connect in authored direction.', '查看两个语义节点如何按编写方向连接。'],
- 'viewer.guide.map': ['See the whole system', '查看完整系统'],
- 'viewer.guide.map.hint': ['Open Semantic Radar with a live viewport and stable nodes.', '打开带实时视口和稳定节点的语义雷达。'],
- 'viewer.guide.lens': ['Compare semantic kinds', '比较语义类型'],
- 'viewer.guide.lens.hint': ['Count roles, reveal their traffic, and compare direct authored links.', '统计角色、显示流量并比较直接编写的连接。'],
- 'viewer.guide.present': ['Enter Presentation Stage', '进入演示模式'],
- 'viewer.guide.present.hint': ['Give the live diagram the viewport without changing export.', '让实时图表占满视口,同时不改变导出。'],
- 'viewer.guide.shortcuts': ['Additional keyboard shortcuts', '其他键盘快捷键'],
- 'viewer.guide.shortcut.export': ['Export', '导出'],
- 'viewer.guide.shortcut.theme': ['Theme', '主题'],
- 'viewer.guide.shortcut.style': ['Style', '风格'],
- 'viewer.guide.shortcut.reset': ['Reset', '重置'],
- 'viewer.guide.shortcut.zoomIn': ['Zoom in', '放大'],
- 'viewer.guide.shortcut.zoomOut': ['Zoom out', '缩小'],
- 'viewer.guide.shortcut.close': ['Close', '关闭'],
- 'viewer.guide.facts': ['{nodes} · {relationships}', '{nodes} · {relationships}'],
- 'viewer.guide.fact.node.one': ['{count} semantic node', '{count} 个语义节点'],
- 'viewer.guide.fact.node.other': ['{count} semantic nodes', '{count} 个语义节点'],
- 'viewer.guide.fact.relationship.one': ['{count} relationship', '{count} 条关系'],
- 'viewer.guide.fact.relationship.other': ['{count} relationships', '{count} 条关系'],
- 'viewer.guide.open': ['Open diagram guide', '打开图表指南'],
-
- 'viewer.finder.title': ['Find a node', '查找节点'],
- 'viewer.finder.close': ['Close node finder', '关闭节点查找器'],
- 'viewer.finder.placeholder': ['Search labels or IDs', '搜索标签或 ID'],
- 'viewer.finder.search': ['Search diagram nodes', '搜索图表节点'],
- 'viewer.finder.results': ['Diagram nodes', '图表节点'],
- 'viewer.finder.empty': ['No matching nodes', '没有匹配的节点'],
- 'viewer.finder.result.focus': ['Focus {label}', '聚焦{label}'],
- 'viewer.finder.result.routeStart': ['Choose {label} as route start', '选择{label}作为路径起点'],
- 'viewer.finder.result.routeTarget': ['Choose {label} as route destination, {links}', '选择{label}作为路径终点,{links}'],
- 'viewer.finder.status.empty': ['No matching nodes', '没有匹配的节点'],
- 'viewer.finder.status.count.one': ['{count} matching node', '{count} 个匹配节点'],
- 'viewer.finder.status.count.other': ['{count} matching nodes', '{count} 个匹配节点'],
- 'viewer.finder.noun.nodes': ['nodes', '个节点'],
- 'viewer.finder.link.one': ['{count} link', '{count} 条连接'],
- 'viewer.finder.link.other': ['{count} links', '{count} 条连接'],
- 'viewer.finder.result.focus.one': ['Focus {label}, {count} related connection', '聚焦{label},{count} 条相关连接'],
- 'viewer.finder.result.focus.other': ['Focus {label}, {count} related connections', '聚焦{label},{count} 条相关连接'],
- 'viewer.finder.status.filtered': ['{visible} of {available} {noun}', '{visible}/{available} {noun}'],
- 'viewer.finder.status.all': ['{available} {noun}', '{available} {noun}'],
-
- 'viewer.passport.eyebrow': ['Semantic passport', '语义护照'],
- 'viewer.passport.metadata': ['Node metadata', '节点元数据'],
- 'viewer.passport.evidence': ['Verified source evidence', '已验证的源代码证据'],
- 'viewer.passport.verified': ['Verified source', '已验证来源'],
- 'viewer.passport.verificationScope': ['Verified against local Git at the pinned revision. Remote access has not been checked.', '已按固定修订版本验证本地 Git 证据,未检查远程访问权限。'],
- 'viewer.passport.reach': ['Authored reach', '编写可达范围'],
- 'viewer.passport.reach.trace': ['Trace authored reachability', '追踪编写的可达性'],
- 'viewer.passport.upstream': ['Upstream', '上游'],
- 'viewer.passport.downstream': ['Downstream', '下游'],
- 'viewer.passport.upstream.trace': ['Trace upstream authored reachability', '追踪上游编写可达性'],
- 'viewer.passport.downstream.trace': ['Trace downstream authored reachability', '追踪下游编写可达性'],
- 'viewer.passport.close': ['Close semantic passport', '关闭语义护照'],
- 'viewer.passport.move': ['Move semantic passport. Drag, use arrow keys, or press Home to reset.', '移动语义护照。可拖动、使用方向键移动,或按 Home 恢复自动位置。'],
- 'viewer.passport.copy': ['Copy link', '复制链接'],
- 'viewer.passport.copy.focus': ['Copy link to focused node', '复制聚焦节点的链接'],
- 'viewer.passport.relations': ['Relations', '关系'],
- 'viewer.passport.relations.show': ['Show connected relationships', '显示关联关系'],
- 'viewer.passport.relations.hide': ['Hide connected relationships', '隐藏关联关系'],
- 'viewer.passport.relations.list': ['Connected relationships', '关联关系'],
- 'viewer.passport.copyRelation': ['Copy relation', '复制关系'],
- 'viewer.passport.copyNode': ['Copy node', '复制节点'],
- 'viewer.passport.copyPinned': ['Copy link to pinned relationship', '复制固定关系的链接'],
- 'viewer.passport.copySource': ['Copy link to source node', '复制来源节点的链接'],
- 'viewer.passport.copy.focused.success': ['Focused node link copied', '已复制聚焦节点链接'],
- 'viewer.passport.copy.pinned.success': ['Pinned relationship link copied', '已复制固定关系链接'],
- 'viewer.passport.copy.focused.failed': ['Could not copy focused node link', '无法复制聚焦节点链接'],
- 'viewer.passport.copy.pinned.failed': ['Could not copy pinned relationship link', '无法复制固定关系链接'],
- 'viewer.passport.relationship.none': ['No connected relationships', '没有关联关系'],
- 'viewer.passport.relationship.count.one': ['{count} relation', '{count} 条关系'],
- 'viewer.passport.relationship.count.other': ['{count} relations', '{count} 条关系'],
- 'viewer.passport.relationship.show.one': ['Show {count} connected relationship', '显示 {count} 条关联关系'],
- 'viewer.passport.relationship.show.other': ['Show {count} connected relationships', '显示 {count} 条关联关系'],
- 'viewer.passport.relationship.summary': ['{out} outgoing · {in} incoming{loops}', '{out} 条出向 · {in} 条入向{loops}'],
- 'viewer.passport.relationship.loops': [' · {count} loop', ' · {count} 条自环'],
- 'viewer.passport.relationship.explorer': ['Direct relationship explorer', '直接关系浏览器'],
- 'viewer.passport.relationship.help': ['Use arrow keys to explore relationships. Press Enter or Space to pin details; Escape clears.', '使用方向键浏览关系。按 Enter 或空格键固定详情;按 Escape 清除。'],
- 'viewer.passport.relationship.loopsBack': ['loops back', '回环'],
- 'viewer.passport.relationship.connectsTo': ['connects to', '连接到'],
- 'viewer.passport.relationship.connectsFrom': ['connects from', '连接自'],
- 'viewer.passport.relationship.pinned': ['Pinned relationship · {from} → {to} · {label}', '已固定关系 · {from} → {to} · {label}'],
- 'viewer.passport.relationship.inspect': ['Inspect relationship {index} of {total}: {from} to {to}, {label}. Press Enter for details.', '检查第 {index}/{total} 条关系:{from} 到 {to},{label}。按 Enter 查看详情。'],
- 'viewer.passport.relationship.group.out': ['Outgoing', '出向'],
- 'viewer.passport.relationship.group.in': ['Incoming', '入向'],
- 'viewer.passport.relationship.group.loop': ['Self loops', '自环'],
- 'viewer.passport.relationship.row': ['{group}: {relationship}, {neighbor}', '{group}:{relationship},{neighbor}'],
- 'viewer.passport.relationship.direction.out': ['OUT →', '出 →'],
- 'viewer.passport.relationship.direction.in': ['← IN', '← 入'],
- 'viewer.passport.relationship.direction.loop': ['LOOP', '自环'],
- 'viewer.passport.sourceCount.one': ['{count} verified source reference', '{count} 个已验证来源引用'],
- 'viewer.passport.sourceCount.other': ['{count} verified source references', '{count} 个已验证来源引用'],
- 'viewer.passport.sourceMarker': ['SRC', '来源'],
- 'viewer.passport.beacon.one': ['{count} verified source; focus this node to inspect', '{count} 个已验证来源;聚焦此节点以检查'],
- 'viewer.passport.beacon.other': ['{count} verified sources; focus this node to inspect', '{count} 个已验证来源;聚焦此节点以检查'],
- 'viewer.passport.repository.open': ['Open verified repository revision {revision}', '打开已验证的仓库修订版本 {revision}'],
- 'viewer.passport.source.open': ['Open verified source {path} at revision {revision}', '打开修订版本 {revision} 中已验证的来源 {path}'],
- 'viewer.passport.source.openLink': ['Open ↗', '打开 ↗'],
- 'viewer.passport.reach.upstream.one': ['Trace {count} upstream authored node', '追踪 {count} 个上游编写节点'],
- 'viewer.passport.reach.upstream.other': ['Trace {count} upstream authored nodes', '追踪 {count} 个上游编写节点'],
- 'viewer.passport.reach.downstream.one': ['Trace {count} downstream authored node', '追踪 {count} 个下游编写节点'],
- 'viewer.passport.reach.downstream.other': ['Trace {count} downstream authored nodes', '追踪 {count} 个下游编写节点'],
- 'viewer.passport.reach.noUpstream': ['No upstream authored nodes', '没有上游编写节点'],
- 'viewer.passport.reach.noDownstream': ['No downstream authored nodes', '没有下游编写节点'],
- 'viewer.passport.reach.status': ['{direction} · {nodes} nodes · {links} links · max {hops} hops', '{direction} · {nodes} 个节点 · {links} 条连接 · 最深 {hops} 跳'],
-
- 'viewer.route.eyebrow': ['Path', '路径'],
- 'viewer.route.start': ['Click where the path starts', '点击路径的起点'],
- 'viewer.route.start.find': ['Find start', '查找起点'],
- 'viewer.route.start.find.aria': ['Find a route start', '查找路径起点'],
- 'viewer.route.copy': ['Copy link', '复制链接'],
- 'viewer.route.copy.aria': ['Copy link to traced route', '复制已追踪路径的链接'],
- 'viewer.route.clear': ['Clear', '清除'],
- 'viewer.route.clear.aria': ['Clear route probe', '清除路径探测'],
- 'viewer.route.traced': ['Path', '路径'],
- 'viewer.route.pickTwo': ['Click two nodes on the diagram', '在图上点两个节点'],
- 'viewer.route.pickOne': ['Click a node on the diagram', '在图上点一个节点'],
- 'viewer.route.controls': ['Route journey controls', '路径旅程控制'],
- 'viewer.route.previous': ['Previous route position', '上一个路径位置'],
- 'viewer.route.play': ['Play route journey', '播放路径旅程'],
- 'viewer.route.pause': ['Pause route journey', '暂停路径旅程'],
- 'viewer.route.replay': ['Replay route journey', '重播路径旅程'],
- 'viewer.route.next': ['Next route position', '下一个路径位置'],
- 'viewer.route.journey': ['Journey', '旅程'],
- 'viewer.route.pause.label': ['Pause', '暂停'],
- 'viewer.route.replay.label': ['Replay', '重播'],
- 'viewer.route.overview': ['Overview', '总览'],
- 'viewer.route.overview.aria': ['Show complete route overview', '显示完整路径总览'],
- 'viewer.route.instructions': ['Click a start, then an end. Paths follow the arrows.', '先点起点,再点终点,沿箭头方向找路。'],
- 'viewer.route.destination': ['Where does the path from {label} end?', '从{label}出发,走到哪里?'],
- 'viewer.route.destination.find': ['Find target', '查找目标'],
- 'viewer.route.destination.find.aria': ['Find a reachable route destination', '查找可达的路径目标'],
- 'viewer.route.differentDestination': ['Choose a different destination', '选择其他目标'],
- 'viewer.route.distinct': ['Pick two different nodes.', '请选两个不同的节点。'],
- 'viewer.route.unreachable': ['Cannot reach {label} from here', '走不到{label}'],
- 'viewer.route.unreachable.detail': ['{target} cannot be reached from {source} along the arrows. Pick a highlighted node.', '沿箭头方向,从{source}走不到{target}。请选一个高亮节点。'],
- 'viewer.route.start.instructions': ['Next, pick the end. Only nodes you can reach will light up.', '接着选终点,能走到的节点会亮起。'],
- 'viewer.route.copy.success': ['Traced route link copied', '已复制路径链接'],
- 'viewer.route.copy.failed': ['Could not copy traced route link', '无法复制路径链接'],
- 'viewer.route.position': ['Route position {index} of {total}: {label}', '路径位置 {index}/{total}:{label}'],
- 'viewer.route.step': ['Step {index} of {total} · {phase} · {label}', '第 {index}/{total} 步 · {phase} · {label}'],
- 'viewer.route.motionRequired': ['Automatic journey requires Live motion', '自动旅程需要动态模式'],
- 'viewer.route.trigger.clear': ['Clear traced route', '清除已追踪路径'],
- 'viewer.route.overview.status': ['{nodes} · {hops} · shortest path', '{nodes} · {hops} · 最短路径'],
- 'viewer.route.overview.node.one': ['{count} node', '{count} 个节点'],
- 'viewer.route.overview.node.other': ['{count} nodes', '{count} 个节点'],
- 'viewer.route.overview.hop.one': ['{count} step', '{count} 步'],
- 'viewer.route.overview.hop.other': ['{count} steps', '{count} 步'],
- 'viewer.route.phase.playing': ['Playing', '播放中'],
- 'viewer.route.phase.complete': ['Complete', '已完成'],
- 'viewer.route.phase.inspecting': ['Inspecting', '检查中'],
- 'viewer.route.destination.count.one': ['{count} reachable node is highlighted. Click it.', '有 {count} 个能走到的节点已高亮,点一下。'],
- 'viewer.route.destination.count.other': ['{count} reachable nodes are highlighted. Click one.', '有 {count} 个能走到的节点已高亮,点一个。'],
- 'viewer.route.noOutgoing': ['No arrows lead out of this node. Clear it and pick another start.', '这个节点没有向外的箭头。清除后换一个起点。'],
- 'viewer.route.result.title': ['{source} to {target}', '{source} 到 {target}'],
- 'viewer.route.finder.source.title': ['Choose route start', '选择路径起点'],
- 'viewer.route.finder.source.placeholder': ['Search route sources', '搜索路径来源'],
- 'viewer.route.finder.source.empty': ['No matching route sources', '没有匹配的路径来源'],
- 'viewer.route.finder.source.results': ['Nodes that can start a route', '可作为路径起点的节点'],
- 'viewer.route.finder.source.noun': ['route sources', '个路径来源'],
- 'viewer.route.finder.source.badge': ['start', '起点'],
- 'viewer.route.finder.target.title': ['Destination from {label}', '从{label}出发的目标'],
- 'viewer.route.finder.target.placeholder': ['Search reachable destinations', '搜索可达目标'],
- 'viewer.route.finder.target.empty': ['No matching reachable destinations', '没有匹配的可达目标'],
- 'viewer.route.finder.target.results': ['Reachable route destinations', '可达路径目标'],
- 'viewer.route.finder.target.noun': ['reachable destinations', '个可达目标'],
- 'viewer.route.hop.one': ['{count} hop', '{count} 跳'],
- 'viewer.route.hop.other': ['{count} hops', '{count} 跳'],
-
- 'viewer.lens.eyebrow': ['Semantic lens', '语义透镜'],
- 'viewer.lens.title': ['Compare system roles', '比较系统角色'],
- 'viewer.lens.close': ['Close semantic lens', '关闭语义透镜'],
- 'viewer.lens.instruction': ['Choose up to two semantic kinds. One reveals its real traffic; two compare only direct authored relationships.', '最多选择两种语义类型。选择一种可显示其真实流量;选择两种只比较直接编写的关系。'],
- 'viewer.lens.kinds': ['Semantic kinds', '语义类型'],
- 'viewer.lens.choose': ['Choose a kind to inspect its nodes and touching relationships.', '选择一种类型以检查其节点和相连关系。'],
- 'viewer.lens.copy': ['Copy link to semantic lens', '复制语义透镜链接'],
- 'viewer.lens.clear': ['Clear semantic lens', '清除语义透镜'],
- 'viewer.lens.open': ['Open semantic lens', '打开语义透镜'],
- 'viewer.lens.openActive': ['Open active semantic lens', '打开当前语义透镜'],
- 'viewer.lens.legend': ['Semantic legend', '语义图例'],
- 'viewer.lens.legend.inspect.one': ['Inspect {label}, {count} node', '检查{label},{count} 个节点'],
- 'viewer.lens.legend.inspect.other': ['Inspect {label}, {count} nodes', '检查{label},{count} 个节点'],
- 'viewer.lens.kind.count.one': ['{label}, {count} node', '{label},{count} 个节点'],
- 'viewer.lens.kind.count.other': ['{label}, {count} nodes', '{label},{count} 个节点'],
- 'viewer.lens.compare.one': ['{first} → {second}: {forward} · {second} → {first}: {reverse} · {count} direct relationship', '{first} → {second}:{forward} · {second} → {first}:{reverse} · 共 {count} 条直接关系'],
- 'viewer.lens.compare.other': ['{first} → {second}: {forward} · {second} → {first}: {reverse} · {count} direct relationships', '{first} → {second}:{forward} · {second} → {first}:{reverse} · 共 {count} 条直接关系'],
- 'viewer.lens.single': ['{nodes} · {relationships} · connected peers remain visible', '{nodes} · {relationships} · 已连接节点保持可见'],
- 'viewer.lens.node.one': ['{count} {label} node', '{count} 个{label}节点'],
- 'viewer.lens.node.other': ['{count} {label} nodes', '{count} 个{label}节点'],
- 'viewer.lens.relationship.one': ['{count} touching relationship', '{count} 条相连关系'],
- 'viewer.lens.relationship.other': ['{count} touching relationships', '{count} 条相连关系'],
-
- 'viewer.radar.title': ['Semantic radar', '语义雷达'],
- 'viewer.radar.building': ['Building overview', '正在构建总览'],
- 'viewer.radar.openFull': ['Open full semantic radar', '打开完整语义雷达'],
- 'viewer.radar.open': ['Open radar', '打开雷达'],
- 'viewer.radar.close': ['Close semantic radar', '关闭语义雷达'],
- 'viewer.radar.surface': ['Diagram overview. Click a node to focus it, or use arrow keys to pan.', '图表总览。点击节点进行聚焦,或使用方向键平移。'],
- 'viewer.radar.click': ['Click node', '点击节点'],
- 'viewer.radar.drag': ['Drag to pan', '拖动平移'],
- 'viewer.radar.space': ['Semantic radar needs more MAP space.', '语义雷达需要更多地图可见空间。'],
- 'viewer.radar.nodes': ['Semantic diagram radar nodes', '语义图表雷达节点'],
- 'viewer.radar.focus': ['Focus {label} from Semantic Radar', '从语义雷达聚焦{label}'],
- 'viewer.radar.status': ['{count} nodes · {viewport}', '{count} 个节点 · {viewport}'],
- 'viewer.radar.fullMap': ['{count} nodes · full map', '{count} 个节点 · 完整地图'],
- 'viewer.radar.compacted': ['Radar compacted to avoid covering the Semantic Passport or MAP controls.', '已收紧雷达,避免遮挡语义护照或地图控件。'],
- 'viewer.radar.cancelWaiting': ['Cancel semantic radar waiting for more MAP space', '取消等待更多地图空间的语义雷达'],
- 'viewer.radar.needsSpace': ['Semantic radar needs more visible MAP space', '语义雷达需要更多可见地图空间'],
- 'viewer.radar.viewport.full': ['full map', '完整地图'],
- 'viewer.radar.viewport.width': ['{percent}% width', '宽度 {percent}%'],
- 'viewer.radar.viewport.scale': ['{percent}% viewport', '视口 {percent}%'],
+// Bundled catalogs are package data, not renderer code. locales/manifest.json
+// enrolls the catalogs meta.locale selects automatically; only listed files
+// are read, relative to this installed package and never from the working
+// directory, home, environment, or network. Adding a language changes data
+// only. en.json defines the canonical keys and the final fallback.
+const LOCALES_DIR = new URL('../../locales/', import.meta.url);
+// Mirrors common.schema.json#/$defs/locale.
+const LOCALE_TAG = /^[a-z]{2,3}(-[A-Za-z0-9]{2,8})*$/;
+const CATALOG_FILE = /^[A-Za-z0-9][A-Za-z0-9._-]*\.json$/;
+
+function readLocaleData(file) {
+ try {
+ return JSON.parse(fs.readFileSync(fileURLToPath(new URL(file, LOCALES_DIR)), 'utf8'));
+ } catch (error) {
+ throw new Error(`Archify locale data ${JSON.stringify(file)} could not be loaded: ${error.message}`);
+ }
+}
- 'viewer.nav.controls': ['Diagram view controls', '图表视图控制'],
- 'viewer.nav.route': ['Trace a directed route', '追踪有向路径'],
- 'viewer.nav.route.title': ['Trace route (R)', '追踪路径(R)'],
- 'viewer.nav.route.short': ['PATH', '路径'],
- 'viewer.nav.radar': ['Open semantic radar', '打开语义雷达'],
- 'viewer.nav.radar.title': ['Semantic radar (M)', '语义雷达(M)'],
- 'viewer.nav.radar.short': ['MAP', '地图'],
- 'viewer.nav.lens': ['Open semantic lens', '打开语义透镜'],
- 'viewer.nav.lens.title': ['Semantic lens (L)', '语义透镜(L)'],
- 'viewer.nav.lens.short': ['LENS', '透镜'],
- 'viewer.nav.find': ['Find a node', '查找节点'],
- 'viewer.nav.find.title': ['Find a node (/)', '查找节点(/)'],
- 'viewer.outline.title': ['Node index', '节点索引'],
- 'viewer.rail.show': ['Notes & index', '要点与索引'],
- 'viewer.rail.controls': ['Side panel', '侧栏'],
- 'viewer.rail.collapse': ['Collapse side panel', '收起侧栏'],
- 'viewer.rail.bottom': ['Move panel below the diagram', '移到图下方'],
- 'viewer.rail.right': ['Move panel beside the diagram', '移到图右侧'],
- 'viewer.nav.guide': ['Open diagram guide', '打开图表指南'],
- 'viewer.nav.guide.title': ['Diagram guide (?)', '图表指南(?)'],
- 'viewer.nav.zoomOut': ['Zoom out', '缩小'],
- 'viewer.nav.zoomOut.title': ['Zoom out (-)', '缩小(-)'],
- 'viewer.nav.reset': ['Reset diagram view', '重置图表视图'],
- 'viewer.nav.reset.title': ['Reset view (0)', '重置视图(0)'],
- 'viewer.nav.read': ['READ', '阅读'],
- 'viewer.nav.zoomIn': ['Zoom in', '放大'],
- 'viewer.nav.zoomIn.title': ['Zoom in (+)', '放大(+)'],
- 'viewer.nav.camera': ['{hint}. Reset diagram view', '{hint}。重置图表视图'],
- 'viewer.nav.camera.title': ['{semantic}{hint} · reset view (0)', '{semantic}{hint} · 重置视图(0)'],
- 'viewer.nav.camera.semantic': ['Semantic camera active · ', '语义相机已启用 · '],
- 'viewer.nav.level.map': ['MAP', '概览'],
- 'viewer.nav.level.read': ['READ', '阅读'],
- 'viewer.nav.level.full': ['FULL', '完整'],
- 'viewer.nav.level.auto': ['AUTO', '自动'],
- 'viewer.nav.detail.map': ['Zoom in to reveal relationship labels and node context', '放大以显示关系标签和节点上下文'],
- 'viewer.nav.detail.read': ['Zoom in again to reveal tags and annotations', '再次放大以显示标签和注释'],
- 'viewer.nav.detail.full': ['Full diagram detail', '完整图表详情'],
+function loadManifest() {
+ const catalogs = readLocaleData('manifest.json')?.catalogs;
+ if (!Array.isArray(catalogs)) throw new Error('Archify locale manifest must list catalogs');
+ const byKey = new Map();
+ for (const entry of catalogs) {
+ const { locale, file } = entry || {};
+ if (typeof locale !== 'string' || locale.length > 35 || !LOCALE_TAG.test(locale)) {
+ throw new Error(`Archify locale manifest has an invalid locale tag ${JSON.stringify(locale)}`);
+ }
+ if (typeof file !== 'string' || !CATALOG_FILE.test(file)) {
+ throw new Error(`Archify locale manifest has an invalid catalog file for ${locale}`);
+ }
+ // Tags match case-insensitively, so two entries differing only in case
+ // would make selection ambiguous.
+ const key = locale.toLowerCase();
+ if (byKey.has(key)) throw new Error(`Archify locale manifest lists ${locale} more than once`);
+ byKey.set(key, { locale, file });
+ }
+ if (byKey.get(DEFAULT_LOCALE)?.locale !== DEFAULT_LOCALE) {
+ throw new Error(`Archify locale manifest must enroll the ${DEFAULT_LOCALE} source catalog`);
+ }
+ return byKey;
+}
- 'viewer.intent.summary': ['{label}. {out} outgoing, {in} incoming{loops}. {total} connections. Press Enter for details.', '{label}。{out} 条出向,{in} 条入向{loops}。共 {total} 条连接。按 Enter 查看详情。'],
- 'viewer.intent.loops': [', {count} self loop', ',{count} 条自环'],
+const MANIFEST = loadManifest();
- 'viewer.common.copied': ['Copied', '已复制'],
- 'viewer.common.copyFailed': ['Copy failed', '复制失败'],
- 'viewer.common.copyLink': ['Copy link', '复制链接'],
- 'viewer.common.clear': ['Clear', '清除'],
- 'viewer.common.close': ['Close', '关闭'],
-};
+export const SUPPORTED_LOCALES = Object.freeze([...MANIFEST.values()].map(({ locale }) => locale));
-for (const [key, messages] of Object.entries(MESSAGE_PAIRS)) {
- if (messages.length !== SUPPORTED_LOCALES.length || messages.some((message) => typeof message !== 'string')) {
- throw new Error(`Incomplete Archify i18n tuple ${JSON.stringify(key)}`);
+const EN = Object.freeze(readLocaleData(MANIFEST.get(DEFAULT_LOCALE).file));
+for (const [key, message] of Object.entries(EN)) {
+ if (typeof message !== 'string' || message.length === 0) {
+ throw new Error(`Archify source message ${JSON.stringify(key)} must be a non-empty string`);
}
}
-const BUILTIN_CATALOGS = Object.fromEntries(SUPPORTED_LOCALES.map((locale, index) => [
- locale,
- Object.fromEntries(Object.entries(MESSAGE_PAIRS).map(([key, pair]) => [key, pair[index]])),
-]));
-
-const EN = BUILTIN_CATALOGS.en;
-
const CANONICAL_KEYS = Object.keys(EN);
const PLACEHOLDER_PATTERN = /\{([a-zA-Z0-9_]+)\}/g;
@@ -496,77 +79,154 @@ function placeholdersMatch(expected, actual) {
return true;
}
-// Runtime catalogs registered by registerLocale(), keyed by whatever locale
-// tag the caller supplied (e.g. an agent-authored 'fr'). Kept separate from
-// BUILTIN_CATALOGS so a caller can never accidentally shadow a shipped
-// catalog with a partial one.
-const RUNTIME_CATALOGS = new Map();
-
-function catalogFor(locale) {
- return RUNTIME_CATALOGS.get(locale) || BUILTIN_CATALOGS[locale];
-}
-
-// Validates caller-supplied translation data against the canonical (English)
-// message-key set. Pure and side-effect free: registerLocale() calls this
-// and additionally builds/installs the resolved catalog.
-export function validateTranslations(translations = {}) {
+// Splits translation data into the entries that can replace a canonical
+// message and the ones that cannot. Rejected entries never replace a valid
+// lower-priority message.
+function classifyTranslations(translations) {
const supplied = Object.keys(translations || {});
- const suppliedSet = new Set(supplied);
- const missingKeys = CANONICAL_KEYS.filter((key) => !suppliedSet.has(key));
- const unknownKeys = supplied.filter((key) => !Object.hasOwn(CANONICAL_PLACEHOLDERS, key));
+ const usable = new Map();
+ const unknownKeys = [];
const placeholderMismatches = [];
- const usableKeys = [];
for (const key of supplied) {
- if (!Object.hasOwn(CANONICAL_PLACEHOLDERS, key)) continue;
+ if (!Object.hasOwn(CANONICAL_PLACEHOLDERS, key)) {
+ unknownKeys.push(key);
+ continue;
+ }
const value = translations[key];
+ const expected = [...CANONICAL_PLACEHOLDERS[key]].sort();
if (typeof value !== 'string' || value.length === 0) {
- placeholderMismatches.push({ key, expected: [...CANONICAL_PLACEHOLDERS[key]].sort(), actual: null });
+ placeholderMismatches.push({ key, expected, actual: null });
continue;
}
const actual = extractPlaceholders(value);
if (placeholdersMatch(CANONICAL_PLACEHOLDERS[key], actual)) {
- usableKeys.push(key);
+ usable.set(key, value);
} else {
- placeholderMismatches.push({
- key,
- expected: [...CANONICAL_PLACEHOLDERS[key]].sort(),
- actual: [...actual].sort(),
- });
+ placeholderMismatches.push({ key, expected, actual: [...actual].sort() });
}
}
+ return { supplied, usable, unknownKeys, placeholderMismatches };
+}
+
+// Validates caller-supplied translation data against the canonical (English)
+// message-key set. Pure and side-effect free; coverage here describes only the
+// supplied data. resolveCatalog() reports the final resolved coverage.
+export function validateTranslations(translations = {}) {
+ const { usable, unknownKeys, placeholderMismatches } = classifyTranslations(translations);
return {
totalKeys: CANONICAL_KEYS.length,
- coveredKeys: usableKeys.length,
- coverage: CANONICAL_KEYS.length ? usableKeys.length / CANONICAL_KEYS.length : 1,
- missingKeys,
+ coveredKeys: usable.size,
+ coverage: CANONICAL_KEYS.length ? usable.size / CANONICAL_KEYS.length : 1,
+ missingKeys: CANONICAL_KEYS.filter((key) => !Object.hasOwn(translations || {}, key)),
unknownKeys,
placeholderMismatches,
};
}
-// Registers a fully-resolved catalog for an arbitrary locale tag, built by
-// layering validated translations over the English base. A key that is
-// missing, non-string, or whose interpolation placeholders don't match the
-// canonical set falls back to its English string — partial or malformed
-// translation data can never break rendering. Returns the same coverage
-// report validateTranslations() would, for the caller to surface as an
-// explicit fallback/coverage diagnostic before rendering.
-export function registerLocale(locale, translations = {}) {
- const report = validateTranslations(translations);
- const catalog = { ...EN };
+export function bundledLocaleFor(locale) {
+ if (typeof locale !== 'string') return null;
+ return MANIFEST.get(locale.toLowerCase())?.locale || null;
+}
+
+function isEnglishTag(locale) {
+ const key = locale.toLowerCase();
+ return key === DEFAULT_LOCALE || key.startsWith(`${DEFAULT_LOCALE}-`);
+}
+
+// Bundled catalogs load on first use and stay immutable; a diagram's
+// overrides are layered onto a copy.
+const BUNDLED_CATALOGS = new Map([[DEFAULT_LOCALE, { usable: new Map(Object.entries(EN)), messages: EN }]]);
+
+function bundledCatalog(locale) {
+ if (!BUNDLED_CATALOGS.has(locale)) {
+ const { usable } = classifyTranslations(readLocaleData(MANIFEST.get(locale.toLowerCase()).file));
+ const messages = Object.freeze(Object.fromEntries(
+ CANONICAL_KEYS.map((key) => [key, usable.get(key) ?? EN[key]]),
+ ));
+ BUNDLED_CATALOGS.set(locale, { usable, messages });
+ }
+ return BUNDLED_CATALOGS.get(locale);
+}
+
+// Resolves each canonical message as: valid meta.translations value →
+// selected bundled-catalog value → English source. Pure; returns the resolved
+// catalog with a report that separates rejected overrides from real English
+// fallback gaps. Omitted or empty translations mean no override. A tag with
+// neither a bundled catalog nor a usable override falls back to English UI
+// and language metadata.
+export function resolveCatalog(locale, translations = undefined) {
+ const override = classifyTranslations(translations);
+ const bundledLocale = bundledLocaleFor(locale);
+ const fallback = Boolean(locale) && !bundledLocale && override.usable.size === 0;
+ const resolvedLocale = !locale || fallback ? DEFAULT_LOCALE : bundledLocale || locale;
+ const bundled = bundledLocale ? bundledCatalog(bundledLocale) : null;
+ const english = isEnglishTag(resolvedLocale);
+ const messages = {};
+ const fallbackKeys = [];
for (const key of CANONICAL_KEYS) {
- const value = translations?.[key];
- if (typeof value !== 'string' || value.length === 0) continue;
- if (placeholdersMatch(CANONICAL_PLACEHOLDERS[key], extractPlaceholders(value))) {
- catalog[key] = value;
+ if (override.usable.has(key)) {
+ messages[key] = override.usable.get(key);
+ } else if (bundled?.usable.has(key)) {
+ messages[key] = bundled.usable.get(key);
+ } else {
+ messages[key] = EN[key];
+ if (!english) fallbackKeys.push(key);
}
}
- RUNTIME_CATALOGS.set(locale, catalog);
- return { locale, ...report };
+ const translatedKeys = english ? CANONICAL_KEYS.length : CANONICAL_KEYS.length - fallbackKeys.length;
+ return {
+ messages: Object.freeze(messages),
+ report: {
+ locale: locale || null,
+ resolvedLocale,
+ bundledLocale,
+ fallback,
+ totalKeys: CANONICAL_KEYS.length,
+ translatedKeys,
+ coverage: CANONICAL_KEYS.length ? translatedKeys / CANONICAL_KEYS.length : 1,
+ fallbackKeys,
+ override: {
+ suppliedKeys: override.supplied.length,
+ appliedKeys: override.usable.size,
+ unknownKeys: override.unknownKeys,
+ placeholderMismatches: override.placeholderMismatches,
+ },
+ },
+ };
+}
+
+// Per-document catalogs installed by registerLocale(), keyed by the authored
+// tag so renderers can keep passing meta.locale. They never mutate a bundled
+// catalog.
+const DOCUMENT_CATALOGS = new Map();
+
+function catalogFor(locale) {
+ if (DOCUMENT_CATALOGS.has(locale)) return DOCUMENT_CATALOGS.get(locale);
+ const bundledLocale = bundledLocaleFor(locale);
+ return bundledLocale ? { locale: bundledLocale, messages: bundledCatalog(bundledLocale).messages } : null;
+}
+
+// Installs the resolved catalog for one authored locale and returns its
+// report. Re-registering the same tag replaces the previous document's
+// overrides; a fallback clears them.
+export function registerLocale(locale, translations = undefined) {
+ const { messages, report } = resolveCatalog(locale, translations);
+ if (report.fallback || !locale) {
+ DOCUMENT_CATALOGS.delete(locale);
+ } else {
+ DOCUMENT_CATALOGS.set(locale, { locale: report.resolvedLocale, messages });
+ }
+ return report;
+}
+
+// English source text for the first reported gaps, so a caller can translate
+// exactly those keys without re-reading the whole catalog.
+export function englishSourceFor(keys) {
+ return Object.fromEntries(keys.filter((key) => Object.hasOwn(EN, key)).map((key) => [key, EN[key]]));
}
export function resolveLocale(locale) {
- return catalogFor(locale) ? locale : DEFAULT_LOCALE;
+ return catalogFor(locale)?.locale || DEFAULT_LOCALE;
}
export function formatMessage(template, values = {}) {
@@ -576,10 +236,9 @@ export function formatMessage(template, values = {}) {
}
export function translateMessage(locale, key, values = {}) {
- const resolved = resolveLocale(locale);
- const catalog = catalogFor(resolved);
+ const catalog = catalogFor(locale)?.messages || EN;
if (!Object.hasOwn(catalog, key)) {
- throw new Error(`Missing Archify i18n message ${JSON.stringify(key)} for ${resolved}`);
+ throw new Error(`Missing Archify i18n message ${JSON.stringify(key)} for ${resolveLocale(locale)}`);
}
return formatMessage(catalog[key], values);
}
@@ -590,8 +249,8 @@ export function translateCount(locale, key, count, values = {}) {
}
export function viewerCatalog(locale) {
- const resolved = resolveLocale(locale);
- return Object.fromEntries(Object.entries(catalogFor(resolved)).filter(([key]) => key.startsWith('viewer.')));
+ const messages = catalogFor(locale)?.messages || EN;
+ return Object.fromEntries(Object.entries(messages).filter(([key]) => key.startsWith('viewer.')));
}
export function localizeTemplate(template, locale) {
diff --git a/archify/schemas/README.md b/archify/schemas/README.md
index f1a2763f..161d0221 100644
--- a/archify/schemas/README.md
+++ b/archify/schemas/README.md
@@ -24,22 +24,22 @@ in generated HTML. Omit it, or set `"none"`, for the default static output.
It also accepts `locale`, any well-formed language tag (schema pattern
`^[a-z]{2,3}(-[A-Za-z0-9]{2,8})*$`). The field selects the fixed Viewer UI,
renderer-owned default legend and accessibility copy, document-title suffix,
-and `<html lang>` value; it does not translate authored strings. `en` and
-`zh-CN` are built-in catalogs; any other tag needs a matching `translations`
-object (see below) or the renderer falls back to English and discloses it.
+and `<html lang>` value; it does not translate authored strings. The bundled
+catalogs enrolled in `locales/manifest.json` (`en`, `zh-CN`, `es`, `ko`) are
+selected by tag, case-insensitively; region and script variants are distinct
+tags. Any other tag needs a matching `translations` object (see below) or the
+renderer falls back to English and discloses it.
Omitting `locale` preserves legacy behavior and resolves to English.
Malformed locale tags fail schema validation instead of being guessed or
silently rewritten.
-`meta.translations` supplies the Viewer message catalog for a `locale` with no
-built-in catalog, as data: an object mapping canonical message keys (see
-`catalogKeys()` in `renderers/shared/i18n.mjs`) to translated strings whose
-`{placeholder}` tokens match the English source. A key that is missing,
-unrecognized, or has mismatched placeholders falls back to English rather than
-failing the render; `validate`/`render`/`deliver` report the resulting
-coverage to stderr. Spanish uses the reusable `examples/locales/es.json`
-catalog; dev inputs that previously used only `locale: "es"` now need this
-object in `meta.translations` to retain Spanish UI.
+`meta.translations` is an optional per-key override, as data: an object mapping
+canonical message keys (`locales/en.json`) to translated strings whose
+`{placeholder}` tokens match the English source. Each message resolves as:
+valid `translations` value → bundled catalog for `locale` → English. An
+unrecognized key or mismatched placeholders never replaces a valid
+lower-priority message and fails no render; `validate`/`render`/`deliver`
+report rejected entries and the final resolved coverage to stderr.
`visual_preset` accepts `classic` (the stable default), `signal-flow` (luminous
motion-forward presentation), `blueprint` (high-contrast engineering review),
or `editorial` (warm publication-style design review and documentation).
@@ -168,10 +168,10 @@ The five diagram schemas reference `common.schema.json#/$defs/...`:
- `point` — an `[x, y]` pair of numbers (used by `via` and `labelAt`)
- `componentType` — `frontend`, `backend`, `database`, `cloud`, `security`,
`messagebus`, `external`
-- `locale` — a well-formed renderer locale tag (`en` and `zh-CN` are built in;
- any other tag needs a matching `translations` object)
-- `translations` — canonical message key → translated string, for a `locale`
- with no built-in catalog
+- `locale` — a well-formed renderer locale tag (bundled catalogs are listed in
+ `locales/manifest.json`; any other tag needs a matching `translations` object)
+- `translations` — canonical message key → translated string, layered over the
+ bundled catalog for `locale`, then English
- `portableOutputPath` — the portable POSIX-relative `.html` path used by
`meta.output`; see the two output-path boundaries in the
[delivery contract](../references/delivery-contract.md#output-path-contracts)
diff --git a/archify/test/i18n.test.mjs b/archify/test/i18n.test.mjs
index 9fbc24c3..f7e8747e 100644
--- a/archify/test/i18n.test.mjs
+++ b/archify/test/i18n.test.mjs
@@ -11,7 +11,9 @@ import { ChromeVisualBrowser, findChrome } from '../bin/visual-check.mjs';
import {
SUPPORTED_LOCALES,
+ bundledLocaleFor,
catalogKeys,
+ resolveCatalog,
translateCount,
translateMessage,
registerLocale,
@@ -22,21 +24,18 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url));
const skillRoot = path.resolve(__dirname, '..');
const cli = path.join(skillRoot, 'bin/archify.mjs');
const templatePath = path.join(skillRoot, 'assets/template.html');
-const ES_TRANSLATIONS = JSON.parse(fs.readFileSync(path.join(skillRoot, 'examples/locales/es.json'), 'utf8'));
+const ES_TRANSLATIONS = JSON.parse(fs.readFileSync(path.join(skillRoot, 'locales/es.json'), 'utf8'));
const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-i18n-'));
const chromePath = process.env.ARCHIFY_CHROME ? findChrome() : null;
let sequence = 0;
-// examples/locales/ko.json is the worked example the maintainer asked for:
-// Korean supplied as data through meta.translations instead of a third
-// hard-coded locale in i18n.mjs. examples/locales/fr.partial.json is the
-// genericity proof — a second, previously unsupported language, deliberately
-// partial to also exercise the coverage/fallback contract. Registering 'ko'
-// here (once, at module scope) makes direct translateMessage('ko', …) calls
-// below resolve the same way the CLI resolves it per-document.
-const KO_TRANSLATIONS = JSON.parse(fs.readFileSync(path.join(skillRoot, 'examples/locales/ko.json'), 'utf8'));
+// locales/ holds the package-owned catalogs that meta.locale selects through
+// locales/manifest.json. examples/locales/fr.partial.json is the genericity
+// proof — an unbundled language, deliberately partial to also exercise the
+// coverage/fallback contract.
+const KO_TRANSLATIONS = JSON.parse(fs.readFileSync(path.join(skillRoot, 'locales/ko.json'), 'utf8'));
const FR_PARTIAL_TRANSLATIONS = JSON.parse(fs.readFileSync(path.join(skillRoot, 'examples/locales/fr.partial.json'), 'utf8'));
-registerLocale('ko', KO_TRANSLATIONS);
+const MANIFEST = JSON.parse(fs.readFileSync(path.join(skillRoot, 'locales/manifest.json'), 'utf8'));
const EXAMPLES = {
architecture: 'web-app.architecture.json',
@@ -152,7 +151,7 @@ async function loadArtifact(browser, artifactPath) {
}
test('zh-CN localizes renderer-owned output across all five modes without translating authored content', () => {
- assert.deepEqual(SUPPORTED_LOCALES, ['en', 'zh-CN']);
+ assert.deepEqual(SUPPORTED_LOCALES, ['en', 'zh-CN', 'es', 'ko']);
for (const type of Object.keys(EXAMPLES)) {
const document = example(type);
const authoredTitle = document.meta.title;
@@ -195,7 +194,7 @@ test('supplied es catalog localizes renderer-owned output across all five modes
assert.match(result.html, /"locale":"es"/);
assert.match(result.html, />Exportar diagrama</);
assert.doesNotMatch(result.html, /\{\{i18n:/);
- assert.doesNotMatch(result.stderr, /has no built-in catalog/, `${type}: es unexpectedly fell back to English`);
+ assert.doesNotMatch(result.stderr, /has no bundled catalog/, `${type}: es unexpectedly fell back to English`);
}
});
@@ -458,7 +457,9 @@ test('malformed locale tags fail schema validation in every mode', () => {
});
test('a well-formed but unregistered locale passes validation, falls back to English chrome, and discloses the fallback', () => {
- for (const locale of ['fr', 'zh-HK', 'es']) {
+ // Region and script variants are distinct tags: none collapses onto a
+ // bundled catalog without explicit data.
+ for (const locale of ['fr', 'zh-HK', 'zh-Hant', 'es-MX', 'ko-KR']) {
for (const type of Object.keys(EXAMPLES)) {
const document = example(type);
document.meta.locale = locale;
@@ -467,7 +468,7 @@ test('a well-formed but unregistered locale passes validation, falls back to Eng
assert.equal(JSON.parse(validated.stdout).ok, true, `${type}/${locale}`);
assert.match(
validated.stderr,
- new RegExp(`meta\\.locale "${locale}" has no built-in catalog and no meta\\.translations`),
+ new RegExp(`meta\\.locale "${locale}" has no bundled catalog and no usable meta\\.translations`),
`${type}/${locale}: fallback was not disclosed`,
);
@@ -500,7 +501,7 @@ test('a previously unsupported locale localizes renderer-owned output once meta.
assert.match(result.html, />Node index</, `${type}: uncovered key did not fall back to English`);
assert.match(
result.stderr,
- new RegExp(`meta\\.translations for locale "fr" covers ${report.coveredKeys}/${report.totalKeys} renderer-owned messages`),
+ new RegExp(`meta\\.locale "fr" resolves ${report.coveredKeys}/${report.totalKeys} renderer-owned messages \\(\\d+%\\) from ${report.coveredKeys} meta\\.translations entries; ${report.totalKeys - report.coveredKeys} fall back to English`),
`${type}: coverage was not disclosed`,
);
}
@@ -522,7 +523,209 @@ test('translations with unknown keys or mismatched interpolation placeholders ar
// match the canonical {label} token — never a raw or broken template.
assert.match(result.html, /aria-label="Focus /);
assert.doesNotMatch(result.html, /wrongPlaceholder/);
- assert.match(result.stderr, /meta\.translations for locale "fr" covers \d+\/\d+ renderer-owned messages/);
+ assert.match(result.stderr, /meta\.translations for locale "fr" has 2 unusable entries \(1 unknown, 1 placeholder mismatch\); each keeps its English message/);
+ assert.match(result.stderr, /meta\.locale "fr" resolves \d+\/\d+ renderer-owned messages/);
+});
+
+function embeddedMessages(html) {
+ const embedded = html.match(/<script id="archify-i18n-data" type="application\/json">([\s\S]*?)<\/script>/);
+ assert.ok(embedded, 'missing embedded i18n data script');
+ return JSON.parse(embedded[1]);
+}
+
+function localeDocument(type, meta) {
+ const document = example(type);
+ delete document.meta.subtitle;
+ Object.assign(document.meta, meta);
+ return document;
+}
+
+test('bundled es and ko render from meta.locale alone in all five modes, identical to supplying the full catalog', () => {
+ const cases = {
+ es: { catalog: ES_TRANSLATIONS, legend: 'Leyenda', focus: 'Enfocar', exportLabel: 'Exportar diagrama' },
+ ko: { catalog: KO_TRANSLATIONS, legend: '범례', focus: '포커스', exportLabel: '다이어그램 내보내기' },
+ };
+ for (const [locale, expected] of Object.entries(cases)) {
+ for (const type of Object.keys(EXAMPLES)) {
+ const localeOnly = run(type, localeDocument(type, { locale }));
+ assert.equal(localeOnly.status, 0, `${type}/${locale}: ${localeOnly.stderr || localeOnly.stdout}`);
+ assert.equal(localeOnly.stderr, '', `${type}/${locale}: a complete bundled catalog should not warn`);
+ assert.match(localeOnly.html, new RegExp(`^<!DOCTYPE html>\\n<html lang="${locale}"`));
+ assert.match(localeOnly.html, new RegExp(`<svg\\b[^>]*\\blang="${locale}"`));
+ assert.match(localeOnly.html, new RegExp(`<text\\b[^>]*>${expected.legend}</text>`), `${type}/${locale}: default legend`);
+ assert.match(localeOnly.html, new RegExp(`aria-label="[^"]*${expected.focus}`), `${type}/${locale}: accessibility copy`);
+ assert.ok(localeOnly.html.includes(`>${expected.exportLabel}<`), `${type}/${locale}: fixed control`);
+ const runtime = embeddedMessages(localeOnly.html);
+ assert.equal(runtime.locale, locale);
+ for (const [key, message] of Object.entries(runtime.messages)) {
+ assert.equal(message, expected.catalog[key], `${type}/${locale}: dynamic Viewer message ${key}`);
+ }
+
+ const supplied = run(type, localeDocument(type, { locale, translations: expected.catalog }));
+ assert.equal(supplied.status, 0, `${type}/${locale}: ${supplied.stderr || supplied.stdout}`);
+ assert.equal(supplied.html, localeOnly.html, `${type}/${locale}: supplied catalog changed existing wording`);
+ }
+ }
+});
+
+test('a partial override replaces only its keys and keeps the rest of the selected bundled language', () => {
+ const overrides = {
+ 'zh-CN': { message: '关闭面板', legend: '图例' },
+ es: { message: 'Cerrar panel', legend: 'Leyenda' },
+ ko: { message: '패널 닫기', legend: '범례' },
+ };
+ for (const [locale, expected] of Object.entries(overrides)) {
+ for (const type of Object.keys(EXAMPLES)) {
+ const result = run(type, localeDocument(type, { locale, translations: { 'viewer.common.close': expected.message } }));
+ assert.equal(result.status, 0, `${type}/${locale}: ${result.stderr || result.stdout}`);
+ assert.equal(result.stderr, '', `${type}/${locale}: a valid one-key override over a complete catalog is not a coverage gap`);
+ assert.match(result.html, new RegExp(`^<!DOCTYPE html>\\n<html lang="${locale}"`));
+ assert.match(result.html, new RegExp(`<text\\b[^>]*>${expected.legend}</text>`), `${type}/${locale}: rest of the language was lost`);
+ const runtime = embeddedMessages(result.html);
+ assert.equal(runtime.messages['viewer.common.close'], expected.message);
+ assert.equal(runtime.messages['viewer.common.copyLink'], translateMessage(locale, 'viewer.common.copyLink'));
+ }
+ }
+});
+
+test('empty translations and equivalent tag casing select the same bundled catalog', () => {
+ for (const type of Object.keys(EXAMPLES)) {
+ const reference = run(type, localeDocument(type, { locale: 'zh-CN' }));
+ assert.equal(reference.status, 0, reference.stderr);
+ const lowered = run(type, localeDocument(type, { locale: 'zh-cn' }));
+ assert.equal(lowered.status, 0, lowered.stderr);
+ assert.equal(lowered.stderr, '');
+ assert.equal(lowered.html, reference.html, `${type}: zh-cn should select the zh-CN catalog and canonical lang`);
+
+ const korean = run(type, localeDocument(type, { locale: 'ko' }));
+ const empty = run(type, localeDocument(type, { locale: 'ko', translations: {} }));
+ assert.equal(empty.status, 0, empty.stderr);
+ assert.equal(empty.stderr, '');
+ assert.equal(empty.html, korean.html, `${type}: {} is not an override`);
+ }
+ assert.equal(bundledLocaleFor('ZH-cn'), 'zh-CN');
+ assert.equal(bundledLocaleFor('zh-Hant'), null);
+ assert.equal(bundledLocaleFor('zh'), null);
+});
+
+test('rejected overrides keep the bundled message and are reported apart from English fallback gaps', () => {
+ const result = run('architecture', localeDocument('architecture', {
+ locale: 'es',
+ translations: {
+ 'viewer.common.close': 'Cerrar {panel}',
+ 'viewer.common.clear': 'Vaciar',
+ 'viewer.common.closee': 'Cerrar',
+ },
+ }));
+ assert.equal(result.status, 0, result.stderr || result.stdout);
+ const runtime = embeddedMessages(result.html);
+ assert.equal(runtime.messages['viewer.common.close'], ES_TRANSLATIONS['viewer.common.close']);
+ assert.equal(runtime.messages['viewer.common.clear'], 'Vaciar');
+ assert.match(result.stderr, /meta\.translations for locale "es" has 2 unusable entries \(1 unknown, 1 placeholder mismatch\); each keeps its bundled es message\./);
+ assert.doesNotMatch(result.stderr, /fall back to English/, 'a rejected override over a complete catalog is not an English gap');
+
+ const { report } = resolveCatalog('es', {
+ 'viewer.common.close': 'Cerrar {panel}',
+ 'viewer.common.clear': 'Vaciar',
+ 'viewer.common.closee': 'Cerrar',
+ });
+ assert.equal(report.translatedKeys, report.totalKeys);
+ assert.deepEqual(report.fallbackKeys, []);
+ assert.equal(report.override.appliedKeys, 1);
+ assert.deepEqual(report.override.unknownKeys, ['viewer.common.closee']);
+ assert.deepEqual(report.override.placeholderMismatches, [{ key: 'viewer.common.close', expected: [], actual: ['panel'] }]);
+});
+
+test('an unbundled tag with only unusable translations falls back to English UI and language metadata', () => {
+ const result = run('architecture', localeDocument('architecture', {
+ locale: 'fr',
+ translations: { 'viewer.common.closee': 'Fermer' },
+ }));
+ assert.equal(result.status, 0, result.stderr || result.stdout);
+ assert.match(result.html, /^<!DOCTYPE html>\n<html lang="en"/);
+ assert.match(result.stderr, /has 1 unusable entry \(1 unknown, 0 placeholder mismatch\); each keeps its English message/);
+ assert.match(result.stderr, /meta\.locale "fr" has no bundled catalog and no usable meta\.translations/);
+});
+
+test('coverage reports the final resolved catalog with the English source of each gap', () => {
+ const partial = resolveCatalog('fr', FR_PARTIAL_TRANSLATIONS).report;
+ assert.equal(partial.resolvedLocale, 'fr');
+ assert.equal(partial.bundledLocale, null);
+ assert.equal(partial.translatedKeys, Object.keys(FR_PARTIAL_TRANSLATIONS).length);
+ assert.equal(partial.translatedKeys + partial.fallbackKeys.length, partial.totalKeys);
+
+ const oneKey = resolveCatalog('ko', { 'viewer.common.close': '패널 닫기' }).report;
+ assert.equal(oneKey.translatedKeys, oneKey.totalKeys, 'override size must not be reported as coverage');
+ assert.equal(oneKey.override.appliedKeys, 1);
+
+ // A bundled catalog that lags behind a new canonical key reports only that
+ // gap; English is never a gap for English.
+ const lagging = { ...ES_TRANSLATIONS };
+ delete lagging['viewer.common.close'];
+ const unbundledSpanish = resolveCatalog('es-419', lagging).report;
+ assert.deepEqual(unbundledSpanish.fallbackKeys, ['viewer.common.close']);
+ assert.deepEqual(resolveCatalog('en', { 'viewer.common.close': 'Dismiss' }).report.fallbackKeys, []);
+ assert.deepEqual(resolveCatalog('en-GB', { 'viewer.common.close': 'Dismiss' }).report.fallbackKeys, []);
+});
+
+test('a document override never mutates the reusable bundled catalog', () => {
+ const before = translateMessage('es', 'viewer.common.close');
+ const { messages } = resolveCatalog('es', { 'viewer.common.close': 'Cerrar panel' });
+ assert.equal(messages['viewer.common.close'], 'Cerrar panel');
+ assert.ok(Object.isFrozen(messages));
+ assert.equal(translateMessage('es', 'viewer.common.close'), before);
+
+ registerLocale('es', { 'viewer.common.close': 'Cerrar panel' });
+ assert.equal(translateMessage('es', 'viewer.common.close'), 'Cerrar panel');
+ registerLocale('es');
+ assert.equal(translateMessage('es', 'viewer.common.close'), before, 'a later document without overrides reuses the bundled catalog');
+});
+
+test('the manifest enrolls exactly the bundled catalogs, and each is complete', () => {
+ assert.deepEqual(MANIFEST.catalogs.map(({ locale }) => locale), SUPPORTED_LOCALES);
+ const files = fs.readdirSync(path.join(skillRoot, 'locales')).filter((file) => file.endsWith('.json') && file !== 'manifest.json').sort();
+ assert.deepEqual(MANIFEST.catalogs.map(({ file }) => file).sort(), files, 'every bundled catalog file is enrolled and every entry exists');
+ for (const { locale, file } of MANIFEST.catalogs) {
+ const report = validateTranslations(JSON.parse(fs.readFileSync(path.join(skillRoot, 'locales', file), 'utf8')));
+ assert.equal(report.coveredKeys, report.totalKeys, `${locale}: missing ${report.missingKeys.join(', ')}`);
+ assert.deepEqual(report.unknownKeys, [], locale);
+ assert.deepEqual(report.placeholderMismatches, [], locale);
+ }
+});
+
+test('enrolling a catalog is a data-only change and works from an unrelated working directory', () => {
+ // Copy the runtime (no tests, no node_modules) outside the checkout, enroll
+ // one more catalog through data alone, and render from an unrelated cwd.
+ const packageRoot = path.join(tmp, 'package-copy', 'archify');
+ fs.cpSync(skillRoot, packageRoot, {
+ recursive: true,
+ filter: (source) => !['node_modules', 'test'].includes(path.basename(source)) || path.dirname(source) !== skillRoot,
+ });
+ const french = JSON.parse(fs.readFileSync(path.join(skillRoot, 'examples/locales/fr.json'), 'utf8'));
+ fs.writeFileSync(path.join(packageRoot, 'locales/fr.json'), JSON.stringify(french));
+ const manifestPath = path.join(packageRoot, 'locales/manifest.json');
+ const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+ manifest.catalogs.push({ locale: 'fr', file: 'fr.json' });
+ fs.writeFileSync(manifestPath, JSON.stringify(manifest));
+
+ const unrelated = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-i18n-cwd-'));
+ // A decoy catalog in the working directory must never be picked up.
+ fs.mkdirSync(path.join(unrelated, 'locales'));
+ fs.writeFileSync(path.join(unrelated, 'locales/manifest.json'), '{"catalogs":[]}');
+ for (const [locale, legend] of [['fr', 'Légende'], ['ko', '범례']]) {
+ const input = path.join(unrelated, `${locale}.json`);
+ const output = path.join(unrelated, `${locale}.html`);
+ fs.writeFileSync(input, JSON.stringify(localeDocument('architecture', { locale })));
+ const result = spawnSync(process.execPath, [path.join(packageRoot, 'bin/archify.mjs'), 'render', 'architecture', input, output], {
+ cwd: unrelated,
+ encoding: 'utf8',
+ });
+ assert.equal(result.status, 0, `${locale}: ${result.stderr || result.stdout}`);
+ const html = fs.readFileSync(output, 'utf8');
+ assert.match(html, new RegExp(`^<!DOCTYPE html>\\n<html lang="${locale}"`));
+ assert.match(html, new RegExp(`<text\\b[^>]*>${legend}</text>`));
+ if (locale === 'fr') assert.match(result.stderr, /meta\.locale "fr" resolves \d+\/\d+ renderer-owned messages \(\d+%\) from the bundled fr catalog; \d+ fall back to English\./);
+ }
});
const BROWSER_LOCALES = {
@@ -562,7 +765,6 @@ async function assertLocalizedViewer(browser, locale, expected) {
for (const type of Object.keys(EXAMPLES)) {
const document = example(type);
document.meta.locale = locale;
- if (locale === 'es') document.meta.translations = ES_TRANSLATIONS;
const authoredTitle = expected.title(type);
document.meta.title = authoredTitle;
const result = run(type, document);
@@ -700,7 +902,6 @@ test('real Chrome keeps ko Finder, Route, Export, and accessibility UI localized
for (const type of Object.keys(EXAMPLES)) {
const document = example(type);
document.meta.locale = 'ko';
- document.meta.translations = KO_TRANSLATIONS;
document.meta.title = `브라우저 로케일-${type}`;
const result = run(type, document);
assert.equal(result.status, 0, `${type}: ${result.stderr || result.stdout}`);
@@ -845,11 +1046,7 @@ test('every supported catalog is complete and preserves interpolation variables'
}
});
-// ko is no longer a built-in catalog (SUPPORTED_LOCALES), so its full-coverage
-// guarantee now lives here as a data test on examples/locales/ko.json, the
-// worked example, instead of the module-load assertion i18n.mjs used to run
-// over a hard-coded third tuple slot.
-test('the checked-in Korean example catalog is complete and preserves interpolation variables for every canonical key', () => {
+test('the bundled Korean catalog is complete and preserves interpolation variables for every canonical key', () => {
const report = validateTranslations(KO_TRANSLATIONS);
assert.equal(report.missingKeys.length, 0, `missing: ${report.missingKeys.join(', ')}`);
assert.equal(report.unknownKeys.length, 0, `unknown: ${report.unknownKeys.join(', ')}`);
@@ -884,7 +1081,7 @@ for (const locale of ['fr', 'pt', 'ja', 'de', 'it', 'ru']) {
assert.match(result.html, new RegExp(`^<!DOCTYPE html>\\n<html lang="${locale}"`));
assert.match(result.html, new RegExp(`"locale":"${locale}"`));
assert.doesNotMatch(result.html, /\{\{i18n:/);
- assert.doesNotMatch(result.stderr, /has no built-in catalog/, `${locale}: unexpectedly fell back to English`);
+ assert.doesNotMatch(result.stderr, /has no bundled catalog/, `${locale}: unexpectedly fell back to English`);
// Check the actual embedded runtime catalog, not raw HTML/CSS source
// (which can contain incidental English substrings, e.g. template
diff --git a/archify/test/skill-metadata.test.mjs b/archify/test/skill-metadata.test.mjs
index 335b1e9a..669c1b6c 100644
--- a/archify/test/skill-metadata.test.mjs
+++ b/archify/test/skill-metadata.test.mjs
@@ -64,12 +64,14 @@ test('update awareness is notification-only and never replaces the requested wor
test('language behavior stays within the bounded locale contract', () => {
assert.match(defaults, /one primary authored language/);
assert.match(defaults, /user's choice or the request\/conversation/);
- assert.match(defaults, /English \(`en`\) or Simplified Chinese \(`zh-CN`\)/);
+ assert.match(defaults, /`en`, `zh-CN`, `es`, and `ko` select a bundled Viewer catalog/);
assert.match(defaults, /meta\.translations/);
assert.match(defaults, /exact product, code, protocol, command, API, and environment names/);
assert.match(defaults, /Language consistency\]\(authoring-contract\.md#language-consistency\)/);
assert.match(authoringContract, /`meta\.locale` controls only renderer-owned reader surfaces/);
- assert.match(authoringContract, /every other `meta\.locale`, also set `meta\.translations`/);
+ assert.match(authoringContract, /valid\s+`meta\.translations` value → the selected bundled catalog → English/);
+ assert.match(authoringContract, /supply only the keys whose wording the diagram needs to change/);
+ assert.match(authoringContract, /For a language without a bundled catalog, supply the catalog here/);
assert.match(authoringContract, /Reuse suitable translations/);
assert.match(authoringContract, /artifact is\s+not fully localized/);
assert.match(authoringContract, /Do not silently substitute\s+`zh-CN` for another language or Chinese locale/);
diff --git a/scripts/package-smoke.mjs b/scripts/package-smoke.mjs
index b31d2ee0..617636f2 100644
--- a/scripts/package-smoke.mjs
+++ b/scripts/package-smoke.mjs
@@ -293,6 +293,29 @@ try {
run(['render', 'architecture', path.join(skillRoot, 'examples', fixtures[0][1]), deployment]);
run(['check', deployment]);
+ // Bundled Viewer catalogs resolve from the installed package, not the cwd,
+ // and the artifact embeds only the selected catalog.
+ const manifest = JSON.parse(fs.readFileSync(path.join(skillRoot, 'locales', 'manifest.json'), 'utf8'));
+ for (const { file } of manifest.catalogs) {
+ if (!fs.existsSync(path.join(skillRoot, 'locales', file))) {
+ throw new Error(`packaged locale manifest lists a missing catalog: ${file}`);
+ }
+ }
+ const localized = JSON.parse(fs.readFileSync(path.join(skillRoot, 'examples', fixtures[0][1]), 'utf8'));
+ localized.meta.locale = 'ko';
+ localized.meta.output = 'localized.html';
+ const localizedInput = path.join(scratch, 'localized.architecture.json');
+ const localizedOutput = path.join(scratch, 'localized.html');
+ fs.writeFileSync(localizedInput, JSON.stringify(localized));
+ run(['render', 'architecture', localizedInput, localizedOutput], { cwd: os.tmpdir() });
+ const localizedHtml = fs.readFileSync(localizedOutput, 'utf8');
+ const embeddedLocale = localizedHtml.match(/<script id="archify-i18n-data" type="application\/json">([\s\S]*?)<\/script>/);
+ if (!localizedHtml.startsWith('<!DOCTYPE html>\n<html lang="ko"')
+ || !localizedHtml.includes('>범례</text>')
+ || JSON.parse(embeddedLocale?.[1] || '{}').locale !== 'ko') {
+ throw new Error('packaged renderer did not select the bundled ko catalog from meta.locale');
+ }
+
const compareReceipt = JSON.parse(run([
'compare', 'architecture',
path.join(skillRoot, 'examples', 'checkout-platform.base.architecture.json'),