create-quiver 0.15.2 → 0.15.4

package/src/create-quiver/lib/demo.js

@@ -6,6 +6,7 @@ const {
   resolveInitPackageScripts,
   toProjectSlug,
 } = require('./init-layout');
+const { createTranslator } = require('./i18n/catalog');
 const cliPackageJson = require('../../../package.json');
 
 const SPEC_VIEWER_DEMO = 'spec-viewer';
@@ -770,38 +771,39 @@ function buildDemoPlan(targetRoot, options = {}) {
 }
 
 function formatDemoPlan(plan, options = {}) {
+  const translator = createTranslator(options.language);
   const lines = [];
-  const title = options.dryRun ? 'Quiver demo dry-run' : 'Quiver demo created';
+  const title = options.dryRun ? translator.t('demo.title.dry_run') : translator.t('demo.title.created');
 
   lines.push(title);
-  lines.push(`- Demo: ${plan.demo}`);
-  lines.push(`- Project: ${plan.projectName}`);
-  lines.push(`- Target: ${plan.targetRoot}`);
-  lines.push(`- Files to create: ${plan.summary.create}`);
-  lines.push(`- Files to preserve: ${plan.summary.preserve}`);
+  lines.push(`- ${translator.t('demo.label.demo', { demo: plan.demo })}`);
+  lines.push(`- ${translator.t('demo.label.project', { project: plan.projectName })}`);
+  lines.push(`- ${translator.t('demo.label.target', { path: plan.targetRoot })}`);
+  lines.push(`- ${translator.t('demo.label.files_to_create', { count: plan.summary.create })}`);
+  lines.push(`- ${translator.t('demo.label.files_to_preserve', { count: plan.summary.preserve })}`);
   lines.push('');
-  lines.push('Files to create');
+  lines.push(translator.t('demo.section.files_to_create'));
   for (const operation of plan.operations.filter((item) => item.action === 'create')) {
     lines.push(`- ${operation.path}`);
   }
   if (plan.summary.create === 0) {
-    lines.push('- none');
+    lines.push(`- ${translator.t('common.none')}`);
   }
   lines.push('');
-  lines.push('Files to preserve');
+  lines.push(translator.t('demo.section.files_to_preserve'));
   for (const operation of plan.operations.filter((item) => item.action === 'preserve')) {
     lines.push(`- ${operation.path}`);
   }
   if (plan.summary.preserve === 0) {
-    lines.push('- none');
+    lines.push(`- ${translator.t('common.none')}`);
   }
 
   if (options.dryRun) {
     lines.push('');
-    lines.push('No files were written.');
+    lines.push(translator.t('demo.no_files_written'));
   } else {
     lines.push('');
-    lines.push('Next commands');
+    lines.push(translator.t('demo.next_commands'));
     lines.push(`- cd ${plan.targetRoot}`);
     lines.push('- npm run validate');
     lines.push('- npm start');

package/src/create-quiver/lib/handoff.js

@@ -1,5 +1,6 @@
 const fs = require('fs');
 const path = require('path');
+const { createTranslator } = require('./i18n/catalog');
 
 const REQUIRED_HEADINGS = [
   '## Background',
@@ -141,23 +142,31 @@ function formatMinimalTemplate(kind) {
   return lines.join('\n').trimEnd();
 }
 
-function formatMissingSectionsError(resolved, missingSections) {
+function formatMissingSectionsError(resolved, missingSections, options = {}) {
+  const translator = createTranslator(options.language);
   return [
-    `create-quiver: ${resolved.label.toLowerCase()} is missing required sections: ${missingSections.join(', ')}`,
+    `create-quiver: ${translator.t('handoff.error.missing_sections', {
+      sections: missingSections.join(', '),
+      subject: translator.t(`handoff.subject.${resolved.kind}`),
+    })}`,
     '',
-    'Accepted headings/aliases:',
+    translator.t('handoff.accepted_headings'),
     formatAliasGuidance(resolved.kind),
     '',
-    'Minimal template:',
+    translator.t('handoff.minimal_template'),
     formatMinimalTemplate(resolved.kind),
   ].join('\n');
 }
 
-function checkHandoff(handoffInput, repoRoot = process.cwd()) {
+function checkHandoff(handoffInput, repoRoot = process.cwd(), options = {}) {
   const resolved = resolveHandoffPath(repoRoot, handoffInput);
+  const translator = createTranslator(options.language);
 
   if (!fs.existsSync(resolved.absolutePath)) {
-    throw new Error(`create-quiver: missing ${resolved.label.toLowerCase()} file: ${resolved.relativePath}`);
+    throw new Error(`create-quiver: ${translator.t('handoff.error.missing_file', {
+      path: resolved.relativePath,
+      subject: translator.t(`handoff.subject.${resolved.kind}`),
+    })}`);
   }
 
   const text = fs.readFileSync(resolved.absolutePath, 'utf8');
@@ -165,7 +174,7 @@ function checkHandoff(handoffInput, repoRoot = process.cwd()) {
     ? validateHandoffSections(text)
     : validateBriefSections(text, resolved.kind);
   if (missingSections.length > 0) {
-    throw new Error(formatMissingSectionsError(resolved, missingSections));
+    throw new Error(formatMissingSectionsError(resolved, missingSections, options));
   }
 
   return resolved;

package/src/create-quiver/lib/i18n/catalog.js

@@ -0,0 +1,152 @@
+const { DEFAULT_LANGUAGE, SUPPORTED_LANGUAGES, normalizeLanguage } = require('./language');
+const en = require('./messages/en');
+const es = require('./messages/es');
+
+const CATALOGS = Object.freeze({
+  en,
+  es,
+});
+
+function getCatalog(language = DEFAULT_LANGUAGE) {
+  const normalized = normalizeLanguage(language) || DEFAULT_LANGUAGE;
+  return CATALOGS[normalized] || CATALOGS[DEFAULT_LANGUAGE];
+}
+
+function listMessageKeys(catalog) {
+  return Object.keys(catalog?.messages || {}).sort();
+}
+
+function validateCatalogCompleteness(catalogs = CATALOGS) {
+  const baseKeys = listMessageKeys(catalogs[DEFAULT_LANGUAGE]);
+  const missing = [];
+  const extra = [];
+
+  for (const language of SUPPORTED_LANGUAGES) {
+    const keys = listMessageKeys(catalogs[language]);
+    for (const key of baseKeys) {
+      if (!keys.includes(key)) {
+        missing.push(`${language}:${key}`);
+      }
+    }
+    for (const key of keys) {
+      if (!baseKeys.includes(key)) {
+        extra.push(`${language}:${key}`);
+      }
+    }
+  }
+
+  return {
+    ok: missing.length === 0 && extra.length === 0,
+    missing,
+    extra,
+  };
+}
+
+function assertCatalogCompleteness(catalogs = CATALOGS) {
+  const report = validateCatalogCompleteness(catalogs);
+  if (!report.ok) {
+    throw new Error([
+      'i18n catalog completeness failed',
+      ...report.missing.map((item) => `missing ${item}`),
+      ...report.extra.map((item) => `extra ${item}`),
+    ].join('\n'));
+  }
+  return report;
+}
+
+function sanitizeInterpolationValue(value) {
+  if (value === null || typeof value === 'undefined') {
+    return '';
+  }
+
+  return String(value)
+    .replace(/\u001b\[[0-?]*[ -/]*[@-~]/g, '')
+    .replace(/\r/g, '\\r')
+    .replace(/\n/g, '\\n')
+    .replace(/\t/g, '\\t')
+    .replace(/[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F]/g, '');
+}
+
+function interpolate(template, params = {}) {
+  return String(template).replace(/\{([a-zA-Z0-9_.-]+)\}/g, (match, name) => {
+    if (!Object.prototype.hasOwnProperty.call(params, name)) {
+      return `[missing:${name}]`;
+    }
+    return sanitizeInterpolationValue(params[name]);
+  });
+}
+
+function selectPluralTemplate(message, params = {}) {
+  if (!message || typeof message !== 'object' || Array.isArray(message)) {
+    return message;
+  }
+
+  const count = Number(params.count);
+  if (count === 1 && typeof message.one === 'string') {
+    return message.one;
+  }
+  if (typeof message.other === 'string') {
+    return message.other;
+  }
+  if (typeof message.one === 'string') {
+    return message.one;
+  }
+  return '';
+}
+
+function resolveMessage(language, key) {
+  const catalog = getCatalog(language);
+  const message = catalog.messages[key];
+  if (typeof message !== 'undefined') {
+    return {
+      message,
+      language: catalog.metadata.language,
+      fallback: false,
+    };
+  }
+
+  const fallbackCatalog = getCatalog(DEFAULT_LANGUAGE);
+  const fallbackMessage = fallbackCatalog.messages[key];
+  if (typeof fallbackMessage !== 'undefined') {
+    return {
+      message: fallbackMessage,
+      language: DEFAULT_LANGUAGE,
+      fallback: true,
+    };
+  }
+
+  return {
+    message: `[missing:${key}]`,
+    language: DEFAULT_LANGUAGE,
+    fallback: true,
+    missing: true,
+  };
+}
+
+function translate(language, key, params = {}) {
+  const resolved = resolveMessage(language, key);
+  const template = selectPluralTemplate(resolved.message, params);
+  return interpolate(template, params);
+}
+
+function createTranslator(language = DEFAULT_LANGUAGE) {
+  return {
+    language: getCatalog(language).metadata.language,
+    t(key, params = {}) {
+      return translate(language, key, params);
+    },
+  };
+}
+
+module.exports = {
+  CATALOGS,
+  assertCatalogCompleteness,
+  createTranslator,
+  getCatalog,
+  interpolate,
+  listMessageKeys,
+  resolveMessage,
+  sanitizeInterpolationValue,
+  translate,
+  validateCatalogCompleteness,
+};

package/src/create-quiver/lib/i18n/language.js

@@ -0,0 +1,279 @@
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const DEFAULT_LANGUAGE = 'en';
+const SUPPORTED_LANGUAGES = Object.freeze(['en', 'es']);
+const PROJECT_CONFIG_RELATIVE_PATH = path.join('.quiver', 'config.json');
+const GLOBAL_CONFIG_RELATIVE_PATH = path.join('.quiver', 'config.json');
+
+function isSupportedLanguage(language) {
+  return SUPPORTED_LANGUAGES.includes(language);
+}
+
+function normalizeLanguage(value) {
+  const raw = String(value || '').trim();
+  if (!raw) {
+    return '';
+  }
+
+  const firstLanguage = raw.split(':').find((part) => part.trim()) || raw;
+  const normalized = firstLanguage
+    .trim()
+    .replace(/_/g, '-')
+    .split('.')[0]
+    .split('@')[0]
+    .toLowerCase();
+  const primary = normalized.split('-')[0];
+
+  return isSupportedLanguage(primary) ? primary : '';
+}
+
+function projectLanguageConfigPath(projectRoot) {
+  return path.join(projectRoot, PROJECT_CONFIG_RELATIVE_PATH);
+}
+
+function globalLanguageConfigPath(homeDir = os.homedir()) {
+  return path.join(homeDir, GLOBAL_CONFIG_RELATIVE_PATH);
+}
+
+function readJsonFile(filePath) {
+  if (!filePath || !fs.existsSync(filePath)) {
+    return null;
+  }
+  return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+}
+
+function readLanguageConfig(filePath) {
+  const config = readJsonFile(filePath);
+  if (!config || typeof config !== 'object' || Array.isArray(config)) {
+    return {
+      exists: Boolean(config),
+      language: '',
+      raw: config,
+    };
+  }
+
+  return {
+    exists: true,
+    language: typeof config.language === 'string' ? config.language : '',
+    raw: config,
+  };
+}
+
+function assertWritableLanguage(language) {
+  const normalized = normalizeLanguage(language);
+  if (!normalized || normalized !== String(language || '').trim().toLowerCase()) {
+    throw new Error(`unsupported language: ${language}. Supported languages: ${SUPPORTED_LANGUAGES.join(', ')}`);
+  }
+  return normalized;
+}
+
+function writeLanguageConfig(filePath, language) {
+  const normalized = assertWritableLanguage(language);
+  const current = readJsonFile(filePath);
+  const base = current && typeof current === 'object' && !Array.isArray(current) ? current : {};
+  const next = {
+    ...base,
+    language: normalized,
+  };
+
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, `${JSON.stringify(next, null, 2)}\n`);
+  return next;
+}
+
+function readProjectLanguageConfig(projectRoot) {
+  return readLanguageConfig(projectLanguageConfigPath(projectRoot));
+}
+
+function writeProjectLanguageConfig(projectRoot, language) {
+  return writeLanguageConfig(projectLanguageConfigPath(projectRoot), language);
+}
+
+function readGlobalLanguageConfig(homeDir = os.homedir()) {
+  return readLanguageConfig(globalLanguageConfigPath(homeDir));
+}
+
+function writeGlobalLanguageConfig(language, homeDir = os.homedir()) {
+  return writeLanguageConfig(globalLanguageConfigPath(homeDir), language);
+}
+
+function detectLocaleLanguage(options = {}) {
+  const env = options.env || process.env;
+  const intlLocale = Object.prototype.hasOwnProperty.call(options, 'intlLocale')
+    ? options.intlLocale
+    : Intl.DateTimeFormat().resolvedOptions().locale;
+  const candidates = [
+    ['locale:LC_ALL', env.LC_ALL],
+    ['locale:LC_MESSAGES', env.LC_MESSAGES],
+    ['locale:LANG', env.LANG],
+  ];
+
+  const languageValues = String(env.LANGUAGE || '')
+    .split(':')
+    .filter(Boolean)
+    .map((value) => ['locale:LANGUAGE', value]);
+  candidates.push(...languageValues);
+  candidates.push(['locale:Intl', intlLocale]);
+
+  for (const [source, value] of candidates) {
+    const language = normalizeLanguage(value);
+    if (language) {
+      return {
+        language,
+        source,
+        requestedLanguage: value,
+      };
+    }
+  }
+
+  return {
+    language: '',
+    source: '',
+    requestedLanguage: '',
+  };
+}
+
+function unsupportedLanguageWarning(source, requestedLanguage) {
+  return {
+    code: 'UNSUPPORTED_LANGUAGE',
+    source,
+    requestedLanguage: String(requestedLanguage || ''),
+    fallbackLanguage: DEFAULT_LANGUAGE,
+    supportedLanguages: [...SUPPORTED_LANGUAGES],
+  };
+}
+
+function resolveProvidedLanguage(source, value) {
+  if (typeof value !== 'string' || !value.trim()) {
+    return null;
+  }
+
+  const language = normalizeLanguage(value);
+  if (language) {
+    return {
+      language,
+      source,
+      requestedLanguage: value,
+      warnings: [],
+    };
+  }
+
+  return {
+    language: DEFAULT_LANGUAGE,
+    source: 'fallback',
+    requestedSource: source,
+    requestedLanguage: value,
+    warnings: [unsupportedLanguageWarning(source, value)],
+  };
+}
+
+function resolveLanguage(options = {}) {
+  const env = options.env || process.env;
+  const projectRoot = options.projectRoot || process.cwd();
+  const homeDir = typeof options.homeDir === 'string' && options.homeDir
+    ? options.homeDir
+    : os.homedir();
+
+  const cli = resolveProvidedLanguage('--lang', options.cliLanguage);
+  if (cli) return cli;
+
+  const envLanguage = resolveProvidedLanguage('QUIVER_LANG', env.QUIVER_LANG);
+  if (envLanguage) return envLanguage;
+
+  const projectConfig = readProjectLanguageConfig(projectRoot);
+  const projectLanguage = resolveProvidedLanguage(PROJECT_CONFIG_RELATIVE_PATH, projectConfig.language);
+  if (projectLanguage) return projectLanguage;
+
+  const globalConfig = readGlobalLanguageConfig(homeDir);
+  const globalLanguage = resolveProvidedLanguage(`~/${GLOBAL_CONFIG_RELATIVE_PATH}`, globalConfig.language);
+  if (globalLanguage) return globalLanguage;
+
+  const locale = detectLocaleLanguage({
+    env,
+    intlLocale: options.intlLocale,
+  });
+  if (locale.language) {
+    return {
+      ...locale,
+      warnings: [],
+    };
+  }
+
+  return {
+    language: DEFAULT_LANGUAGE,
+    source: 'default',
+    requestedLanguage: '',
+    warnings: [],
+  };
+}
+
+function extractCliLanguageFlag(argv) {
+  const nextArgv = [];
+  let language = '';
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+
+    if (arg === '--') {
+      nextArgv.push(...argv.slice(index));
+      break;
+    }
+
+    if (arg === '--lang') {
+      const value = argv[index + 1];
+      if (!value || String(value).startsWith('--')) {
+        throw new Error('missing value for --lang');
+      }
+      language = value;
+      index += 1;
+      continue;
+    }
+
+    if (String(arg).startsWith('--lang=')) {
+      const value = String(arg).slice('--lang='.length);
+      if (!value) {
+        throw new Error('missing value for --lang');
+      }
+      language = value;
+      continue;
+    }
+
+    nextArgv.push(arg);
+  }
+
+  return {
+    argv: nextArgv,
+    language,
+  };
+}
+
+function formatLanguageWarning(warning) {
+  if (!warning || warning.code !== 'UNSUPPORTED_LANGUAGE') {
+    return '';
+  }
+
+  return `create-quiver: unsupported language "${warning.requestedLanguage}" from ${warning.source}; falling back to ${warning.fallbackLanguage}. Supported languages: ${warning.supportedLanguages.join(', ')}.`;
+}
+
+module.exports = {
+  DEFAULT_LANGUAGE,
+  GLOBAL_CONFIG_RELATIVE_PATH,
+  PROJECT_CONFIG_RELATIVE_PATH,
+  SUPPORTED_LANGUAGES,
+  detectLocaleLanguage,
+  extractCliLanguageFlag,
+  formatLanguageWarning,
+  globalLanguageConfigPath,
+  isSupportedLanguage,
+  normalizeLanguage,
+  projectLanguageConfigPath,
+  readGlobalLanguageConfig,
+  readLanguageConfig,
+  readProjectLanguageConfig,
+  resolveLanguage,
+  writeGlobalLanguageConfig,
+  writeLanguageConfig,
+  writeProjectLanguageConfig,
+};