Skip to content

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

docs(skill): stop pointing the agent at examples/locales; translate per diagram

uygnoey8af0480672da
diff --git a/archify.zip b/archify.zip
index 50c68e79..683bcd24 100644
Binary files a/archify.zip and b/archify.zip differ
diff --git a/archify/SKILL.md b/archify/SKILL.md
index 45b747e8..5024f33a 100644
--- a/archify/SKILL.md
+++ b/archify/SKILL.md
@@ -125,9 +125,7 @@ Read `references/viewer-runtime.md` only when the user explicitly asks for Share
This section is about renderer-owned Viewer chrome only. Write titles, node labels, cards, and every other authored string directly in whatever language the user explicitly requested or the conversation established — Archify never machine-translates authored content or calls a translation service, before or after delivery.
-**Any well-formed locale tag works, for any language — not just the ones listed below.** `en`, `zh-CN`, and `es` ship as built-in Viewer-chrome catalogs (`renderers/shared/i18n.mjs`), so those three need nothing further. Every other locale — including ones with no example on disk — is supplied as translation *data* you (the authoring agent) write into the document, not a renderer code change and not a fixed list anywhere in this repo. To localize a diagram in a language with no existing example, set `meta.locale` to its tag and write `meta.translations` yourself: an object mapping canonical message keys (see `catalogKeys()`, or any key in `examples/locales/ko.json`) to translated strings whose `{placeholder}` tokens match the English source exactly. `validate`/`render`/`deliver` report coverage to stderr (`archify: meta.translations for locale "…" covers N/519 renderer-owned messages…`); a key that is missing, unknown, or has mismatched placeholders falls back to its English string rather than breaking the render. `meta.locale` without a built-in catalog or `meta.translations` falls back entirely to English Viewer UI and `<html lang="en">`, with the same disclosure on stderr — never a half-translated page. The renderer itself never translates anything or calls a translation service; every string in `meta.translations` must already be present in the document when you call `validate`/`render`/`deliver`.
-
-`examples/locales/` holds format references only, not catalogs to copy: `examples/locales/ko.json`, `fr.json`, `pt.json`, `ja.json`, `de.json`, `it.json`, and `ru.json` each show a complete (519/519 keys) catalog, and `examples/locales/fr.partial.json` is a small, deliberately partial French catalog demonstrating the missing-key/coverage-report path specifically. Use them to see the key set, placeholder shape, and coverage behavior — never paste one into `meta.translations`. Translate the Viewer strings yourself for each diagram, in the target language and in keeping with that diagram's own terminology, even when an example file exists for that language. None of these are a closed enum; a language with no file here works exactly the same way.
+**Any well-formed locale tag works, for any language — not just the built-in ones.** `en`, `zh-CN`, and `es` ship as built-in Viewer-chrome catalogs (`renderers/shared/i18n.mjs`), so those three need nothing further. Every other locale is supplied as translation *data* you (the authoring agent) write into the document, not a renderer code change and not a fixed list anywhere in this repo. To localize a diagram in any other language, set `meta.locale` to its tag and write `meta.translations` yourself: an object mapping canonical message keys to translated strings whose `{placeholder}` tokens match the English source exactly. Translate from the English source itself, fresh for each diagram and in keeping with that diagram's own terminology — do not look up, copy, or adapt any checked-in translation file. Print the English source for every key with `node --input-type=module -e "import {catalogKeys,translateMessage} from './renderers/shared/i18n.mjs'; console.log(JSON.stringify(Object.fromEntries(catalogKeys().map((k) => [k, translateMessage('en', k)])), null, 2))"` from the skill root. `validate`/`render`/`deliver` report coverage to stderr (`archify: meta.translations for locale "…" covers N/519 renderer-owned messages…`); a key that is missing, unknown, or has mismatched placeholders falls back to its English string rather than breaking the render. `meta.locale` without a built-in catalog or `meta.translations` falls back entirely to English Viewer UI and `<html lang="en">`, with the same disclosure on stderr — never a half-translated page. The renderer itself never translates anything or calls a translation service; every string in `meta.translations` must already be present in the document when you call `validate`/`render`/`deliver`.
`assets/template.html` also bundles D2Coding (SIL OFL, `assets/D2Coding-OFL.txt`) after JetBrains Mono in the monospace stack, and one weight of Pretendard (SIL OFL, `assets/Pretendard-OFL.txt`) in the "editorial" preset's serif heading stack, so Hangul in authored content or a Korean-translated chrome renders without missing glyphs. This is independent of `meta.translations`: it helps any locale or authored text that uses Hangul, and is not required for the translation mechanism itself to work.
diff --git a/archify/references/authoring-contract.md b/archify/references/authoring-contract.md
index 336e0e14..5cb4c502 100644
--- a/archify/references/authoring-contract.md
+++ b/archify/references/authoring-contract.md
@@ -64,9 +64,9 @@ request, then prompt order or conversation dominance.
`en`, `zh-CN`, and `es` 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
-`renderers/shared/i18n.mjs`; `examples/locales/ko.json` is a complete worked
-example) to translated strings whose `{placeholder}` tokens match the English
-source exactly. A key that is missing, unrecognized, or has mismatched
+`renderers/shared/i18n.mjs`) to translated strings whose `{placeholder}` tokens
+match the English source exactly. Translate from the English source for each
+diagram; do not look up, copy, or adapt any checked-in translation file. 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.
diff --git a/archify/schemas/README.md b/archify/schemas/README.md
index af6a4234..2d65961f 100644
--- a/archify/schemas/README.md
+++ b/archify/schemas/README.md
@@ -37,8 +37,7 @@ built-in catalog, as data: an object mapping canonical message keys (see
`{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. `examples/locales/ko.json` is a complete worked example;
-`examples/locales/fr.partial.json` demonstrates partial coverage.
+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).
diff --git a/archify/test/skill-metadata.test.mjs b/archify/test/skill-metadata.test.mjs
index d4fb6762..53246190 100644
--- a/archify/test/skill-metadata.test.mjs
+++ b/archify/test/skill-metadata.test.mjs
@@ -69,8 +69,11 @@ test('language behavior stays within the bounded locale contract', () => {
assert.match(skill, /renderer never translates authored content/i);
assert.match(skill, /product names.*code identifiers.*protocols.*API paths.*environment names/);
assert.match(skill, /catalogKeys\(\)/);
- assert.match(skill, /examples\/locales\/ko\.json/);
- assert.match(skill, /examples\/locales\/fr\.partial\.json/);
+ // examples/locales/ are translation examples only; the agent translates from
+ // the English source per diagram, so the skill must not point at them.
+ assert.doesNotMatch(skill, /examples\/locales/);
+ assert.doesNotMatch(authoringContract, /examples\/locales/);
+ assert.match(skill, /do not look up, copy, or adapt any checked-in translation file/);
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, /artifact is\s+not fully localized/);