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): carry locale warnings in passing validate, deliver, and finalize receipts

uygnoey1a16e75d2366
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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-28
diff --git a/archify.zip b/archify.zip
index 1a8347eb..83926e59 100644
Binary files a/archify.zip and b/archify.zip differ
diff --git a/archify/bin/archify.mjs b/archify/bin/archify.mjs
index 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 = engineeringProfile
diff --git a/archify/bin/finalize.mjs b/archify/bin/finalize.mjs
index 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.md
index 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 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
+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 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.
diff --git a/archify/references/delivery-contract.md b/archify/references/delivery-contract.md
index 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 rere
A 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 evidence
diff --git a/archify/renderers/shared/cli.mjs b/archify/renderers/shared/cli.mjs
index 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.mjs
index 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.mjs
index 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();