Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
10.9 KB
Raw Blame
#!/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}`);
  }
}