An open source design system that's fully customizable and agent ready
TypeScript
#!/usr/bin/env node
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
* Generates the compact string-map catalogs shipped to runtime consumers.
*
* packages/core/locales/*.json remain the canonical Crowdin sources and keep
* translator descriptions. Each generated module exports only the
* key-to-defaultMessage map used at runtime.
*
* It also derives Core's per-module English fallback maps (see
* scripts/i18n-english-fallback.mjs) and fails when a Core module that names
* catalog keys does not import and register its own map.
*/
import {spawn} from 'node:child_process';
import fs from 'node:fs';
import path from 'node:path';
import {fileURLToPath} from 'node:url';
import {createPseudoCatalog} from '../packages/core/scripts/build-pseudo-locale.mjs';
import {
CORE_SRC_DIR,
collectEnglishFallbackSlices,
findWiringProblems,
isShippedSourceModule,
writeEnglishFallbackSlices,
} from './i18n-english-fallback.mjs';
const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
const REPO_ROOT = path.resolve(SCRIPT_DIR, '..');
const SOURCE_LOCALES_DIR = path.join(REPO_ROOT, 'packages', 'core', 'locales');
const GENERATED_LOCALES_DIR = path.join(
REPO_ROOT,
'packages',
'core',
'src',
'i18n',
'generated-locales',
);
const EN_FILE = 'en.json';
const PSEUDO_FILE = 'pseudo.json';
function readJson(file) {
return JSON.parse(fs.readFileSync(file, 'utf8'));
}
function validateEntry(key, entry) {
if (
entry === null ||
typeof entry !== 'object' ||
Array.isArray(entry) ||
typeof entry.defaultMessage !== 'string'
) {
throw new Error(`${key}: missing string "defaultMessage"`);
}
}
/** Reduce a rich authoring catalog to the strings used at runtime. */
export function createRuntimeCatalog(sourceCatalog) {
return Object.fromEntries(
Object.entries(sourceCatalog).map(([key, entry]) => {
validateEntry(key, entry);
return [key, entry.defaultMessage];
}),
);
}
export function createRuntimeCatalogs(sourceCatalogs) {
const runtimeCatalogs = Object.fromEntries(
Object.entries(sourceCatalogs).map(([file, catalog]) => [
file,
createRuntimeCatalog(catalog),
]),
);
const english = sourceCatalogs[EN_FILE];
if (!english) throw new Error(`Missing source catalog: ${EN_FILE}`);
runtimeCatalogs[PSEUDO_FILE] = createRuntimeCatalog(
createPseudoCatalog(english),
);
return runtimeCatalogs;
}
export function getGeneratedModuleName(sourceFile) {
if (!sourceFile.endsWith('.json')) {
throw new Error(`Expected a JSON locale filename: ${sourceFile}`);
}
return `${sourceFile.slice(0, -'.json'.length)}.generated.ts`;
}
function getGeneratedModulePath(sourceFile) {
return path.join(GENERATED_LOCALES_DIR, getGeneratedModuleName(sourceFile));
}
export async function renderRuntimeCatalogModule(runtimeCatalog, sourceFile) {
const {format, resolveConfig} = await import('prettier');
const outputFile = getGeneratedModulePath(sourceFile);
const sourceDescription =
sourceFile === PSEUDO_FILE
? 'the pseudo-localization projection of packages/core/locales/en.json'
: `packages/core/locales/${sourceFile}`;
const source = `// Copyright (c) Meta Platforms, Inc. and affiliates.\n\n/**\n * @generated by scripts/generate-i18n-runtime.mjs from ${sourceDescription}.\n * Translator descriptions remain in the authored JSON catalogs and must not be copied here.\n * Do not edit by hand. Run \`pnpm generate:i18n-runtime\` instead.\n */\n\nconst runtimeCatalog: Readonly<Record<string, string>> = ${JSON.stringify(runtimeCatalog)};\n\nexport default runtimeCatalog;\n`;
const prettierConfig = await resolveConfig(outputFile);
return format(source, {...prettierConfig, filepath: outputFile});
}
function readSourceCatalogs() {
return Object.fromEntries(
fs
.readdirSync(SOURCE_LOCALES_DIR, {withFileTypes: true})
.filter(
entry =>
entry.isFile() &&
entry.name.endsWith('.json') &&
entry.name !== PSEUDO_FILE,
)
.map(entry => [
entry.name,
readJson(path.join(SOURCE_LOCALES_DIR, entry.name)),
])
.sort(([left], [right]) => left.localeCompare(right)),
);
}
function writeIfChanged(file, content) {
if (fs.existsSync(file) && fs.readFileSync(file, 'utf8') === content) {
return false;
}
fs.writeFileSync(file, content);
return true;
}
function removeStaleModules(expectedFiles) {
if (!fs.existsSync(GENERATED_LOCALES_DIR)) return 0;
let removed = 0;
for (const entry of fs.readdirSync(GENERATED_LOCALES_DIR, {
withFileTypes: true,
})) {
if (
entry.isFile() &&
entry.name.endsWith('.generated.ts') &&
!expectedFiles.has(entry.name)
) {
fs.rmSync(path.join(GENERATED_LOCALES_DIR, entry.name));
removed += 1;
}
}
return removed;
}
export function isSourceLocaleFile(file) {
return (
typeof file === 'string' && file.endsWith('.json') && file !== PSEUDO_FILE
);
}
export async function generateRuntimeCatalogs({check = false} = {}) {
const runtimeCatalogs = createRuntimeCatalogs(readSourceCatalogs());
const english = runtimeCatalogs[EN_FILE];
const slices = collectEnglishFallbackSlices(english);
const wiringProblems = findWiringProblems(slices);
const failOnWiringProblems = () => {
if (wiringProblems.length === 0) return;
throw new Error(
`${wiringProblems.length} Core module(s) do not reach their English fallback:\n` +
wiringProblems.map(problem => ` - ${problem}`).join('\n'),
);
};
if (check) {
failOnWiringProblems();
console.log(
`✓ ${Object.keys(runtimeCatalogs).length} authored locale catalogs produce metadata-free runtime maps`,
);
console.log(
`✓ All ${slices.size} Core modules that name catalog keys reach their English`,
);
return;
}
fs.mkdirSync(GENERATED_LOCALES_DIR, {recursive: true});
const expectedFiles = new Set(
Object.keys(runtimeCatalogs).map(getGeneratedModuleName),
);
const removed = removeStaleModules(expectedFiles);
let changed = 0;
for (const [file, catalog] of Object.entries(runtimeCatalogs)) {
const output = await renderRuntimeCatalogModule(catalog, file);
if (writeIfChanged(getGeneratedModulePath(file), output)) changed += 1;
}
const fallback = writeEnglishFallbackSlices(english, slices);
console.log(
`Generated ${Object.keys(runtimeCatalogs).length} runtime locale modules ` +
`(${changed} changed, ${removed} stale removed) and ${slices.size} ` +
`English fallback maps (${fallback.changed} changed, ${fallback.removed} stale removed)`,
);
// Written first so a development server still gets current maps; a module
// that cannot reach its English still fails the build and the test run.
failOnWiringProblems();
}
export function createSpawnInvocation(
command,
platform = process.platform,
commandShell = process.env.ComSpec ?? 'cmd.exe',
) {
if (platform !== 'win32') {
return {file: command[0], args: command.slice(1)};
}
const unsafe = command.find(arg => !/^[A-Za-z0-9_@./:\\=-]+$/.test(arg));
if (unsafe !== undefined) {
throw new Error(
`Windows watch commands cannot contain spaces or shell metacharacters: ${unsafe}`,
);
}
return {
file: commandShell,
args: ['/d', '/s', '/c', command.join(' ')],
};
}
/**
* Runs `command` once the runtime catalogs are current and regenerates them
* while it runs. A test passes its own `generate`, `run` and `watch`.
*/
export async function watchRuntimeCatalogs(
command,
{
generate = generateRuntimeCatalogs,
run = runForwardingSignals,
watch = fs.watch,
} = {},
) {
let debounce;
let regeneration = Promise.resolve();
const queueGeneration = () => {
const next = regeneration.then(() => generate());
regeneration = next.catch(() => {});
return next;
};
const scheduleGeneration = () => {
clearTimeout(debounce);
debounce = setTimeout(() => {
void queueGeneration().catch(error => {
const message = error instanceof Error ? error.message : String(error);
console.error(
`Could not regenerate runtime locale catalogs: ${message}`,
);
});
}, 75);
};
const watcher = watch(SOURCE_LOCALES_DIR, (_event, file) => {
const fileName = file == null ? null : String(file);
if (fileName !== null && !isSourceLocaleFile(fileName)) return;
scheduleGeneration();
});
// Core modules decide which keys each English fallback map holds, so a
// module edit regenerates the maps too.
const sourceWatcher = watch(
CORE_SRC_DIR,
{recursive: true},
(_event, file) => {
const fileName =
file == null ? null : String(file).split(path.sep).join('/');
if (fileName !== null && !isShippedSourceModule(fileName)) return;
scheduleGeneration();
},
);
try {
// Register the watcher first so an edit during initial generation queues a
// second pass instead of leaving the child process on stale catalogs.
await queueGeneration();
return await run(command);
} finally {
clearTimeout(debounce);
watcher.close();
sourceWatcher.close();
}
}
/**
* Runs `command` as a child and forwards SIGINT and SIGTERM to it until it
* exits. Resolves with the child's exit code, or 1 when a signal ended it.
*/
export async function runForwardingSignals(command) {
const invocation = createSpawnInvocation(command);
const child = spawn(invocation.file, invocation.args, {
env: process.env,
stdio: 'inherit',
});
const forwardInterrupt = () => child.kill('SIGINT');
const forwardTermination = () => child.kill('SIGTERM');
process.on('SIGINT', forwardInterrupt);
process.on('SIGTERM', forwardTermination);
try {
return await new Promise((resolve, reject) => {
child.once('error', reject);
child.once('exit', (code, signal) => resolve(signal ? 1 : (code ?? 1)));
});
} finally {
process.removeListener('SIGINT', forwardInterrupt);
process.removeListener('SIGTERM', forwardTermination);
}
}
async function main() {
const args = process.argv.slice(2);
if (args.includes('--watch')) {
const separator = args.indexOf('--');
const command = separator === -1 ? [] : args.slice(separator + 1);
if (command.length === 0) {
throw new Error('`--watch` requires a command after `--`');
}
process.exitCode = await watchRuntimeCatalogs(command);
return;
}
await generateRuntimeCatalogs({check: args.includes('--check')});
}
function isDirectExecution() {
if (!process.argv[1]) return false;
try {
return (
fs.realpathSync(process.argv[1]) ===
fs.realpathSync(fileURLToPath(import.meta.url))
);
} catch {
return false;
}
}
if (isDirectExecution()) {
try {
await main();
} catch (error) {
if (!process.argv.slice(2).includes('--best-effort')) throw error;
const message = error instanceof Error ? error.message : String(error);
console.warn(`Could not generate runtime locale catalogs: ${message}`);
}
}