Turn any idea, plan, or codebase into a beautiful interactive diagram. An agent skill for Claude Code, Codex, and more.
HTML agent-skillsai-agentsarchitecture-diagramclaude-codeclaude-skillscodexcoding-agentsdeepseek-harnessdeveloper-toolsdiagramsdiagrams-as-codedsh-pluginflowchartllmmermaidopencodesequence-diagramsoftware-architecturesystem-designvisualization
feat(i18n): carry locale warnings in passing validate, deliver, and finalize receipts
uygnoey1a16e75d2366
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 29e44690..9577a683 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -9,7 +9,7 @@ All notable changes are documented here. Format loosely follows [Keep a Changelo### 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.+- **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. Passing `validate --json`, `deliver`, and `finalize` receipts now carry these `i18n/*` warnings in `diagnostics[]` (gates and exit codes are unchanged); previously `finalize` did not surface them at all.## [3.0.1] — 2026-09-28diff --git a/archify.zip b/archify.zipindex 1a8347eb..83926e59 100644Binary files a/archify.zip and b/archify.zip differdiff --git a/archify/bin/archify.mjs b/archify/bin/archify.mjsindex fa2066d9..935dce2c 100755--- a/archify/bin/archify.mjs+++ b/archify/bin/archify.mjs@@ -1871,6 +1871,21 @@ function recordDeliveryFailure(options) {return recorded;}+// Locale warnings for a successfully rendered candidate. The renderer prints+// them to stderr; receipts carry the same diagnostics from the same pure+// resolver so an agent can repair a translation gap from structured output.+async function specificationLocaleDiagnostics(type, specification) {+ let meta;+ try {+ meta = JSON.parse(String(specification)).meta;+ } catch {+ return [];+ }+ if (!meta?.locale) return [];+ const { localeDiagnostics } = await import('../renderers/shared/i18n.mjs');+ return localeDiagnostics(type, meta);+}+function deliverySuccessProvenance(receipt) {return {schemaVersion: 1,@@ -4850,6 +4865,7 @@ async function commandDeliver(args) {return;}const engineeringProfile = engineeringProfileFromArtifact(artifact);+ const localeWarnings = await specificationLocaleDiagnostics(type, specification);const receipt = {schemaVersion: 1,receiptId,@@ -4887,6 +4903,7 @@ async function commandDeliver(args) {...(sourceEvidence.repository.linkMode ? { linkMode: sourceEvidence.repository.linkMode } : {}),},} : {}),+ ...(localeWarnings.length ? { diagnostics: localeWarnings } : {}),};const provenanceBytes = Buffer.from(`${JSON.stringify(deliverySuccessProvenance(receipt), null, 2)}\n`);@@ -5733,6 +5750,9 @@ async function commandFinalize(rawArgs) {console.log(`gates ${Object.entries(result.summary.gates).map(([stage, status]) => `${stage}:${status}`).join(' ')}`);console.log(`receipt ${result.summary.evidence.receipt}`);console.log(`perceptual visual review ${result.summary.visualReview}`);+ for (const entry of result.summary.diagnostics || []) {+ if (entry.severity === 'warning') console.error(`warning [${entry.code}] ${entry.message}`);+ }if (result.summary.update?.noticeRequired) console.log(result.summary.update.noticeText);}process.exitCode = result.exitCode;@@ -6821,6 +6841,7 @@ async function commandValidate(args) {...artifactIdentity(specification),};const resolvedQuality = quality || result.composition.profile || 'standard';+ const localeWarnings = await specificationLocaleDiagnostics(type, specification);console.log(JSON.stringify({schemaVersion: 1,ok: true,@@ -6846,6 +6867,7 @@ async function commandValidate(args) {checks: result.checks,composition: result.composition,...(engineeringProfile ? { engineeringProfile } : {}),+ ...(localeWarnings.length ? { diagnostics: localeWarnings } : {}),}, null, 2));} else {const engineering = engineeringProfilediff --git a/archify/bin/finalize.mjs b/archify/bin/finalize.mjsindex 4407059b..03719075 100644--- a/archify/bin/finalize.mjs+++ b/archify/bin/finalize.mjs@@ -793,6 +793,9 @@ export async function runFinalize({};if (stage === 'deliver' && status === 'pass') {+ // Non-blocking warnings (for example locale fallbacks) stay visible in+ // a passing receipt; a later failing gate replaces them.+ receipt.diagnostics = (stageReceipt.diagnostics || []).filter((entry) => entry?.severity === 'warning');receipt.stages.validate = {status: 'pass',exitCode: 0,diff --git a/archify/references/authoring-contract.md b/archify/references/authoring-contract.mdindex 822c0e4c..7ea6fbba 100644--- a/archify/references/authoring-contract.md+++ b/archify/references/authoring-contract.md@@ -94,8 +94,9 @@ catalog, translate missing keys, and use the English source to check keys andplaceholders.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+the lower-priority message; it is reported as `i18n/invalid-translation` on+stderr and as a warning in the `validate --json`, `deliver`, and `finalize`+receipt `diagnostics[]`. Keys that still resolve to English in anon-English locale are reported as `i18n/translation-coverage`, with the missingkeys 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.diff --git a/archify/references/delivery-contract.md b/archify/references/delivery-contract.mdindex 1cde6441..45247a97 100644--- a/archify/references/delivery-contract.md+++ b/archify/references/delivery-contract.md@@ -422,6 +422,8 @@ Both browser commands inspect the exact delivered HTML without modifying or rereA passing `finalize` may report `layoutReviewRecommendation.action: "inspect-sequence-width"`. Its `evidence` measures the fixed participant columns' unused right-hand space after accounting for message labels, notes and segment titles. This advice adds no warning, failure, screenshot requirement or automatic geometry change.+A passing `validate --json`, `deliver`, or `finalize` receipt may carry `diagnostics[]` entries with `severity: "warning"` for Viewer locale fallbacks (`i18n/*`). They fail no gate. When the artifact should be fully localized, repair the listed keys from their `evidence` and rerun `finalize`.+For a newly authored candidate with omitted `meta.column_fit` and no user-fixed column geometry, save the candidate, set only `meta.column_fit` to `"spread"`, and rerun the complete `finalize` once with `--out-dir <folder>/width-review`. Keep participant order, messages and their y positions, labels, notes, sources and canvas dimensions. If that attempt fails, restore the candidate and finalize it with `--out-dir <folder>/width-restore`; report the remaining layout suggestion rather than iterating. Preserve an explicitly fixed layout or a supplied legacy candidate and disclose the suggestion without changing it. This review is about horizontal composition; a passing receipt still does not claim perceptual approval.## Optional capture evidencediff --git a/archify/renderers/shared/cli.mjs b/archify/renderers/shared/cli.mjsindex ce8e5c39..f58490c1 100644--- a/archify/renderers/shared/cli.mjs+++ b/archify/renderers/shared/cli.mjs@@ -18,7 +18,7 @@ import {removeOwnedRegularFile,verifyAtomicOutput,} from './atomic-output.mjs';-import { resolveLocale, translateMessage, registerLocale, englishSourceFor, SUPPORTED_LOCALES } from './i18n.mjs';+import { resolveLocale, translateMessage, registerLocale, localeDiagnostics } from './i18n.mjs';import { prepareDiagramBrandMarks } from './brand-marks.mjs';const outputPathGuards = new Map();@@ -26,68 +26,16 @@ let renderCandidateSequence = 0;// 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}`);-}-+// locales/manifest.json → English (see i18n.mjs). Every fallback is disclosed+// on stderr unconditionally so render/deliver/validate report it even without+// ARCHIFY_DIAGNOSTIC_FORMAT; the CLI receipts carry the same diagnostics.function applyLocaleTranslations(diagramType, diagram) {const locale = diagram.meta?.locale;if (!locale) return;- 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',- 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' },- 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}.'],- });+ registerLocale(locale, diagram.meta.translations);+ for (const diagnostic of localeDiagnostics(diagramType, diagram.meta)) {+ recordDiagnostic(diagnostic);+ console.warn(`archify: ${diagnostic.message}`);}}diff --git a/archify/renderers/shared/i18n.mjs b/archify/renderers/shared/i18n.mjsindex c3f2db22..b0720a56 100644--- a/archify/renderers/shared/i18n.mjs+++ b/archify/renderers/shared/i18n.mjs@@ -219,10 +219,70 @@ export function registerLocale(locale, translations = undefined) {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]]));+// Agent-facing warnings for one document's meta.locale/meta.translations.+// Pure, so the renderer and the CLI receipts (validate/deliver/finalize)+// report the same diagnostics from the same input.+export function localeDiagnostics(diagramType, meta) {+ const locale = meta?.locale;+ if (!locale) return [];+ const report = resolveCatalog(locale, meta.translations).report;+ const diagnostics = [];+ const { unknownKeys, placeholderMismatches, appliedKeys } = report.override;+ const rejected = unknownKeys.length + placeholderMismatches.length;+ if (rejected) {+ const kept = report.bundledLocale ? `bundled ${report.bundledLocale} message` : 'English message';+ diagnostics.push({+ code: 'i18n/invalid-translation',+ severity: 'warning',+ 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) {+ diagnostics.push({+ code: 'i18n/locale-fallback',+ severity: 'warning',+ 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' },+ 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);+ diagnostics.push({+ code: 'i18n/translation-coverage',+ severity: 'warning',+ 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,+ // English source for the listed gaps, so a caller can translate+ // exactly those keys without re-reading the whole catalog.+ englishSource: Object.fromEntries(missingKeys.map((key) => [key, EN[key]])),+ },+ supportedFixes: ['Add each missing key to meta.translations, translating its English source string and keeping its {placeholders}.'],+ });+ }+ return diagnostics;}export function resolveLocale(locale) {diff --git a/archify/test/i18n.test.mjs b/archify/test/i18n.test.mjsindex f7e8747e..af467867 100644--- a/archify/test/i18n.test.mjs+++ b/archify/test/i18n.test.mjs@@ -681,6 +681,52 @@ test('a document override never mutates the reusable bundled catalog', () => {assert.equal(translateMessage('es', 'viewer.common.close'), before, 'a later document without overrides reuses the bundled catalog');});+function cliJson(args) {+ const result = spawnSync(process.execPath, [cli, ...args], { cwd: tmp, encoding: 'utf8' });+ assert.equal(result.status, 0, result.stderr || result.stdout);+ return JSON.parse(result.stdout);+}++test('validate and deliver receipts carry locale warnings as structured diagnostics without failing', () => {+ const input = path.join(tmp, 'receipt-fr.json');+ fs.writeFileSync(input, JSON.stringify(localeDocument('architecture', {+ locale: 'fr',+ translations: { ...FR_PARTIAL_TRANSLATIONS, 'viewer.common.closee': 'Fermer' },+ })));+ const validated = cliJson(['validate', 'architecture', input, '--json']);+ const delivered = cliJson(['deliver', 'architecture', input, path.join(tmp, 'receipt-fr.html'), '--json']);+ for (const receipt of [validated, delivered]) {+ assert.equal(receipt.ok, true);+ assert.deepEqual(receipt.diagnostics.map((entry) => [entry.code, entry.severity]), [+ ['i18n/invalid-translation', 'warning'],+ ['i18n/translation-coverage', 'warning'],+ ]);+ const coverage = receipt.diagnostics[1].evidence;+ assert.equal(coverage.missingKeysTotal, coverage.totalKeys - coverage.translatedKeys);+ assert.equal(coverage.missingKeys.length, 10);+ for (const key of coverage.missingKeys) assert.equal(coverage.englishSource[key], translateMessage('en', key));+ assert.deepEqual(receipt.diagnostics[0].evidence.unknownKeys, ['viewer.common.closee']);+ }++ const clean = path.join(tmp, 'receipt-ko.json');+ fs.writeFileSync(clean, JSON.stringify(localeDocument('architecture', { locale: 'ko' })));+ assert.equal(cliJson(['validate', 'architecture', clean, '--json']).diagnostics, undefined);+ assert.equal(cliJson(['deliver', 'architecture', clean, path.join(tmp, 'receipt-ko.html'), '--json']).diagnostics, undefined);+});++test('a passing finalize keeps locale warnings in its receipt', {+ skip: chromePath ? false : 'Set ARCHIFY_CHROME to run finalize with its browser gate.',+}, () => {+ const input = path.join(tmp, 'finalize-fr.json');+ fs.writeFileSync(input, JSON.stringify(localeDocument('architecture', { locale: 'fr', translations: FR_PARTIAL_TRANSLATIONS })));+ const summary = cliJson(['finalize', 'architecture', input, path.join(tmp, 'finalize-fr.html'), '--quality', 'showcase', '--json']);+ assert.equal(summary.ok, true);+ assert.equal(summary.status, 'pass');+ assert.deepEqual(summary.diagnostics.map((entry) => entry.code), ['i18n/translation-coverage']);+ const full = JSON.parse(fs.readFileSync(summary.evidence.receipt, 'utf8'));+ assert.deepEqual(full.diagnostics.map((entry) => entry.code), ['i18n/translation-coverage']);+});+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();