#!/usr/bin/env node // scripts/ci/check-i18n-contract.mjs // Enforces i18n contract across the monorepo: // 1. All 12 locale files have identical key sets and non-empty string values. // 2. Placeholder tokens ({{token}}) in en.json match ko.json. // 3. Static t('literal') calls in apps/ & packages/ resolve to keys in ko.json. // 4. Orphan candidate count does not exceed the frozen ratchet ceiling. import fs from 'node:fs' import path from 'node:path' import { fileURLToPath } from 'node:url' const __dirname = path.dirname(fileURLToPath(import.meta.url)) const ROOT = path.resolve(__dirname, '../..') const LOCALES_DIR = path.join(ROOT, 'packages/i18n/src/locales') const LOCALES = ['ko', 'en', 'ja', 'zh', 'zh-TW', 'es', 'fr', 'de', 'pt', 'ru', 'vi', 'th'] const MAX_ORPHAN_CANDIDATES = 35 const SEARCH_DIRS = ['apps', 'packages', 'site', 'server'] const IGNORE_DIRS = new Set(['node_modules', '.next', 'dist', 'out', 'build', 'coverage', 'locales', '.git']) export function extractPlaceholders(value) { const matches = [...String(value).matchAll(/\{\{([a-zA-Z0-9_]+)\}\}/g)] return [...new Set(matches.map((m) => m[1]))].sort() } export function validateLocaleCatalogs(catalogsByLocale) { const violations = [] const ko = catalogsByLocale.ko if (!ko) { return ['Missing master locale ko'] } const masterKeys = Object.keys(ko) const masterSet = new Set(masterKeys) for (const locale of Object.keys(catalogsByLocale)) { const data = catalogsByLocale[locale] const keys = Object.keys(data) for (const k of masterKeys) { if (!(k in data)) { violations.push(`locale:${locale}:missing_key:${k}`) } else if (typeof data[k] !== 'string' || data[k].trim().length === 0) { violations.push(`locale:${locale}:empty_value:${k}`) } } for (const k of keys) { if (!masterSet.has(k)) { violations.push(`locale:${locale}:extra_key:${k}`) } } } const en = catalogsByLocale.en if (en) { for (const k of masterKeys) { if (typeof ko[k] !== 'string' || typeof en[k] !== 'string') continue const koVars = extractPlaceholders(ko[k]) const enVars = extractPlaceholders(en[k]) if (koVars.join(',') !== enVars.join(',')) { violations.push(`placeholder_mismatch:en:${k}:expected(${koVars.join(',')}):actual(${enVars.join(',')})`) } } } return violations } export function extractStaticTCalls(sourceText) { const keys = [] const callRegex = /\bt\(\s*(['"])([a-zA-Z0-9_.-]+)\1\s*[,)]/g let match while ((match = callRegex.exec(sourceText)) !== null) { const candidate = match[2] if (candidate.includes('.')) { keys.push(candidate) } } return keys } function walkSourceFiles(dir, out = []) { if (!fs.existsSync(dir)) return out for (const entry of fs.readdirSync(dir, { withFileTypes: true })) { if (IGNORE_DIRS.has(entry.name)) continue const full = path.join(dir, entry.name) if (entry.isDirectory()) { walkSourceFiles(full, out) } else if (/\.(ts|tsx|js|mjs|cjs|cs)$/.test(entry.name)) { out.push(full) } } return out } function runSelfTest() { const okCatalogs = { ko: { 'nav.home': '홈 {{count}}', 'nav.settings': '설정' }, en: { 'nav.home': 'Home {{count}}', 'nav.settings': 'Settings' }, } if (validateLocaleCatalogs(okCatalogs).length !== 0) { throw new Error('self-test failed: expected clean catalogs to pass') } const missingKeyViolations = validateLocaleCatalogs({ ko: { 'nav.home': '홈', 'nav.settings': '설정' }, en: { 'nav.home': 'Home' }, }) if (!missingKeyViolations.includes('locale:en:missing_key:nav.settings')) { throw new Error('self-test failed: expected missing key detection') } const placeholderViolations = validateLocaleCatalogs({ ko: { 'nav.home': '홈 {{count}}' }, en: { 'nav.home': 'Home {{total}}' }, }) if (!placeholderViolations.some((v) => v.startsWith('placeholder_mismatch:en:nav.home'))) { throw new Error('self-test failed: expected placeholder mismatch detection') } const extracted = extractStaticTCalls("const a = t('nav.home'); const b = t(\"nav.settings\", { x: 1 })") if (extracted.join(',') !== 'nav.home,nav.settings') { throw new Error(`self-test failed: unexpected extracted calls ${extracted.join(',')}`) } process.stdout.write('[check-i18n] self-test PASSED\n') } if (process.argv.includes('--self-test')) { runSelfTest() process.exit(0) } const catalogs = {} for (const locale of LOCALES) { catalogs[locale] = JSON.parse(fs.readFileSync(path.join(LOCALES_DIR, `${locale}.json`), 'utf8')) } const violations = validateLocaleCatalogs(catalogs) const masterSet = new Set(Object.keys(catalogs.ko)) const sourceFiles = SEARCH_DIRS.flatMap((d) => walkSourceFiles(path.join(ROOT, d))) const allSourceChunks = [] for (const file of sourceFiles) { const rel = path.relative(ROOT, file).replaceAll('\\', '/') const content = fs.readFileSync(file, 'utf8') allSourceChunks.push(content) // Skip test files that intentionally pass synthetic fallback keys to t(...) if (rel.includes('__tests__') || rel.includes('/tests/') || /\.test\.|\.spec\./.test(rel)) { continue } for (const key of extractStaticTCalls(content)) { if (!masterSet.has(key)) { violations.push(`missing_literal_key:${rel}:${key}`) } } } const joinedSource = allSourceChunks.join('\n') const dynamicPrefixes = [...new Set([...joinedSource.matchAll(/`([a-zA-Z0-9_.-]+\.)\$\{/g)].map((m) => m[1]))] let orphanCount = 0 for (const key of masterSet) { if (joinedSource.includes(key)) continue if (dynamicPrefixes.some((prefix) => key.startsWith(prefix))) continue orphanCount += 1 } if (orphanCount > MAX_ORPHAN_CANDIDATES) { violations.push(`orphan_ceiling_exceeded:${orphanCount}>${MAX_ORPHAN_CANDIDATES}`) } if (violations.length > 0) { process.stderr.write(`[check-i18n] FAILED (${violations.length} violations):\n - ${violations.slice(0, 25).join('\n - ')}\n`) process.exit(1) } process.stdout.write( `[check-i18n] GREEN (${masterSet.size} keys × ${LOCALES.length} locales, unreferenced=${orphanCount}/${MAX_ORPHAN_CANDIDATES})\n`, )