i18nsmith 0.1.0

package/src/commands/translate/executor.ts

@@ -0,0 +1,188 @@
+/**
+ * Translation execution logic with retry, batching, and placeholder validation
+ */
+
+import chalk from 'chalk';
+import pLimit from 'p-limit';
+import pRetry from 'p-retry';
+import type { PlaceholderValidator, TranslationPlan, TranslationService, TranslationLocalePlan } from '@i18nsmith/core';
+import { loadTranslator, type Translator, type TranslatorLoadOptions } from '@i18nsmith/translation';
+import type { TranslateLocaleResult, PlaceholderIssue } from './types.js';
+
+export interface ExecuteTranslationsInput {
+  plan: TranslationPlan;
+  translationService: TranslationService;
+  provider: {
+    name: string;
+    loaderOptions: TranslatorLoadOptions;
+  };
+  overwrite: boolean;
+  skipEmpty: boolean;
+  placeholderValidator: PlaceholderValidator;
+  strictPlaceholders: boolean;
+}
+
+export interface ExecuteTranslationsResult {
+  results: TranslateLocaleResult[];
+  stats: Awaited<ReturnType<TranslationService['flush']>>;
+}
+
+/**
+ * Execute translations for all locales in the plan
+ */
+export async function executeTranslations(
+  input: ExecuteTranslationsInput
+): Promise<ExecuteTranslationsResult> {
+  const translator = await loadTranslator(input.provider.loaderOptions);
+  const results: TranslateLocaleResult[] = [];
+  const limit = pLimit(input.provider.loaderOptions.concurrency ?? 4);
+
+  try {
+    const translationPromises = input.plan.locales.map((localePlan) =>
+      limit(async () => {
+        const { updates, placeholderIssues } = await translateLocalePlan(
+          translator,
+          localePlan,
+          input.plan.sourceLocale,
+          input.provider.loaderOptions.batchSize ?? 25,
+          input.placeholderValidator,
+          input.strictPlaceholders
+        );
+        const writeSummary = await input.translationService.writeTranslations(localePlan.locale, updates, {
+          overwrite: input.overwrite,
+          skipEmpty: input.skipEmpty,
+        });
+        results.push({
+          ...writeSummary,
+          characters: localePlan.totalCharacters,
+          placeholderIssues,
+        });
+      })
+    );
+
+    await Promise.all(translationPromises);
+
+    const stats = await input.translationService.flush();
+    // Sort results to match the plan's locale order for consistent output
+    results.sort((a, b) => {
+      const aIndex = input.plan.locales.findIndex((p) => p.locale === a.locale);
+      const bIndex = input.plan.locales.findIndex((p) => p.locale === b.locale);
+      return aIndex - bIndex;
+    });
+    return { results, stats };
+  } finally {
+    await translator.dispose?.();
+  }
+}
+
+/**
+ * Translate a single locale plan with batching and retry logic
+ */
+async function translateLocalePlan(
+  translator: Translator,
+  localePlan: TranslationLocalePlan,
+  sourceLocale: string,
+  batchSize: number,
+  placeholderValidator: PlaceholderValidator,
+  strictPlaceholders: boolean
+): Promise<{ updates: { key: string; value: string }[]; placeholderIssues: PlaceholderIssue[] }> {
+  const updates: { key: string; value: string }[] = [];
+  const placeholderIssues: PlaceholderIssue[] = [];
+
+  for (const chunk of chunkTasks(localePlan.tasks, batchSize)) {
+    const translationMap = new Map<string, string>();
+
+    // Pre-fill with reused values
+    chunk.forEach((task) => {
+      if (task.reusedValue) {
+        translationMap.set(task.key, task.reusedValue.value);
+      }
+    });
+
+    const tasksRequiringTranslation = chunk.filter((task) => !task.reusedValue);
+    if (tasksRequiringTranslation.length > 0) {
+      const sourceTexts = tasksRequiringTranslation.map((task) => task.sourceValue);
+      const translated = await pRetry(() => translator.translate(sourceTexts, sourceLocale, localePlan.locale), {
+        retries: 3,
+        onFailedAttempt: (error) => {
+          console.log(
+            chalk.yellow(
+              `Attempt ${error.attemptNumber} failed translating ${localePlan.locale}. There are ${error.retriesLeft} retries left.`
+            )
+          );
+        },
+      });
+
+      if (!Array.isArray(translated) || translated.length !== sourceTexts.length) {
+        throw new Error(
+          `Translator returned ${translated.length} result(s) for ${sourceTexts.length} input(s) while translating ${localePlan.locale}.`
+        );
+      }
+
+      tasksRequiringTranslation.forEach((task, index) => {
+        const candidate = translated[index] ?? '';
+        const comparison = placeholderValidator.compare(task.sourceValue, candidate ?? '');
+
+        if (task.placeholders.length && comparison.missing.length) {
+          placeholderIssues.push({
+            key: task.key,
+            locale: localePlan.locale,
+            type: 'missing',
+            placeholders: comparison.missing,
+          });
+          if (!strictPlaceholders) {
+            console.log(
+              chalk.yellow(
+                `Translator output for ${task.key} (${localePlan.locale}) is missing placeholder${
+                  comparison.missing.length === 1 ? '' : 's'
+                }: ${comparison.missing.join(', ')}. Falling back to source text.`
+              )
+            );
+          }
+          translationMap.set(task.key, task.sourceValue);
+          return;
+        }
+
+        if (comparison.extra.length) {
+          placeholderIssues.push({
+            key: task.key,
+            locale: localePlan.locale,
+            type: 'extra',
+            placeholders: comparison.extra,
+          });
+          if (!strictPlaceholders) {
+            console.log(
+              chalk.yellow(
+                `Translator output for ${task.key} (${localePlan.locale}) introduced unexpected placeholder${
+                  comparison.extra.length === 1 ? '' : 's'
+                }: ${comparison.extra.join(', ')}`
+              )
+            );
+          }
+        }
+
+        translationMap.set(task.key, candidate ?? '');
+      });
+    }
+
+    chunk.forEach((task) => {
+      updates.push({ key: task.key, value: translationMap.get(task.key) ?? '' });
+    });
+  }
+
+  return { updates, placeholderIssues };
+}
+
+/**
+ * Split an array into chunks of a given size
+ */
+export function chunkTasks<T>(items: T[], size: number): T[][] {
+  if (size <= 0) {
+    return [items];
+  }
+  const result: T[][] = [];
+  for (let i = 0; i < items.length; i += size) {
+    result.push(items.slice(i, i + size));
+  }
+  return result;
+}

package/src/commands/translate/index.ts

@@ -0,0 +1,220 @@
+/**
+ * Translate command - fill missing locale entries via translation adapters
+ */
+
+import chalk from 'chalk';
+import inquirer from 'inquirer';
+import type { Command } from 'commander';
+import {
+  DEFAULT_PLACEHOLDER_FORMATS,
+  PlaceholderValidator,
+  loadConfig,
+  TranslationService,
+  TranslationPlan,
+} from '@i18nsmith/core';
+import type { TranslationConfig } from '@i18nsmith/core';
+import { TranslatorLoadError, type TranslatorLoadOptions } from '@i18nsmith/translation';
+
+import type { TranslateCommandOptions, TranslateSummary, ProviderSettings } from './types.js';
+import { emitTranslateOutput, maybePrintEstimate } from './reporter.js';
+import { handleCsvExport, handleCsvImport } from './csv-handler.js';
+import { executeTranslations } from './executor.js';
+
+// Re-export types for external use
+export * from './types.js';
+
+/**
+ * Parse comma-separated locale values
+ */
+function collectLocales(value: string | string[], previous: string[]): string[] {
+  const tokens = (Array.isArray(value) ? value : value.split(','))
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+  return [...previous, ...tokens];
+}
+
+/**
+ * Resolve provider settings from config and options
+ */
+function resolveProviderSettings(
+  translationConfig: TranslationConfig | undefined,
+  override?: string
+): ProviderSettings & { loaderOptions: TranslatorLoadOptions } {
+  const providerName = (override ?? translationConfig?.provider ?? 'manual').trim();
+  const moduleSpecifier = translationConfig?.module;
+  let secret: string | undefined;
+  if (translationConfig?.secretEnvVar) {
+    secret = process.env[translationConfig.secretEnvVar];
+  }
+
+  const loaderOptions: TranslatorLoadOptions = {
+    provider: providerName,
+    module: moduleSpecifier,
+    apiKey: translationConfig?.apiKey,
+    secret,
+    concurrency: translationConfig?.concurrency,
+    batchSize: translationConfig?.batchSize,
+    config: translationConfig ? { ...translationConfig } : undefined,
+  };
+
+  return {
+    name: providerName,
+    loaderOptions,
+  };
+}
+
+/**
+ * Prompt for translation confirmation
+ */
+async function confirmTranslate(plan: TranslationPlan, providerName: string): Promise<boolean> {
+  const { proceed } = await inquirer.prompt<{ proceed: boolean }>([
+    {
+      type: 'confirm',
+      name: 'proceed',
+      default: false,
+      message: `Translate ${plan.totalTasks} key${plan.totalTasks === 1 ? '' : 's'} (${plan.totalCharacters} chars) across ${plan.locales.length} locale${plan.locales.length === 1 ? '' : 's'} via ${providerName}?`,
+    },
+  ]);
+  return proceed;
+}
+
+/**
+ * Register the translate command
+ */
+export function registerTranslate(program: Command): void {
+  program
+    .command('translate')
+    .description('Fill missing locale entries by invoking configured translation adapters')
+    .option('-c, --config <path>', 'Path to i18nsmith config file', 'i18n.config.json')
+    .option('--json', 'Print raw JSON results', false)
+    .option('--report <path>', 'Write JSON summary to a file')
+    .option('--write', 'Write translated values to locale files (defaults to dry-run)', false)
+    .option('--locales <codes...>', 'Comma-separated list of locale codes to translate', collectLocales, [])
+    .option('--provider <name>', 'Override the translation provider configured in i18n.config.json')
+    .option('--force', 'Retranslate keys even if a locale already has a value', false)
+    .option('--estimate', 'Attempt to estimate cost when running in dry-run mode', false)
+    .option('--no-skip-empty', 'Allow writing empty translator results (default skips them)')
+    .option('-y, --yes', 'Skip interactive confirmation when applying translations', false)
+    .option('--strict-placeholders', 'Fail if translated output has placeholder mismatches (for CI)', false)
+    .option('--export <path>', 'Export missing translations to a CSV file for external translation')
+    .option('--import <path>', 'Import translations from a CSV file and merge into locale files')
+    .action(async (options: TranslateCommandOptions) => {
+      // Handle CSV export mode
+      if (options.export) {
+        await handleCsvExport(options);
+        return;
+      }
+
+      // Handle CSV import mode
+      if (options.import) {
+        await handleCsvImport(options);
+        return;
+      }
+
+      console.log(
+        chalk.blue(options.write ? 'Translating locale files...' : 'Planning translations (dry-run)...')
+      );
+
+      try {
+        const config = await loadConfig(options.config);
+        const translationService = new TranslationService(config);
+        const plan = await translationService.buildPlan({
+          locales: options.locales,
+          force: options.force,
+        });
+        const placeholderValidator = new PlaceholderValidator(
+          config.sync?.placeholderFormats?.length ? config.sync.placeholderFormats : DEFAULT_PLACEHOLDER_FORMATS
+        );
+
+        if (!plan.totalTasks) {
+          console.log(chalk.green('✓ No missing translations detected.'));
+          return;
+        }
+
+        const providerSettings = resolveProviderSettings(config.translation, options.provider);
+        const summary: TranslateSummary = {
+          provider: providerSettings.name,
+          dryRun: !options.write,
+          plan,
+          locales: [],
+          localeStats: [],
+          totalCharacters: plan.totalCharacters,
+        };
+
+        if (!options.write) {
+          if (options.estimate && providerSettings.name !== 'manual') {
+            await maybePrintEstimate(plan, providerSettings);
+          }
+
+          await emitTranslateOutput(summary, options);
+          return;
+        }
+
+        if (providerSettings.name === 'manual') {
+          throw new Error(
+            'No translation provider configured. Update "translation.provider" in i18n.config.json or pass --provider.'
+          );
+        }
+
+        if (options.write && !options.yes) {
+          if (!process.stdout.isTTY) {
+            throw new Error('Interactive confirmation required in non-TTY environment. Re-run with --yes to proceed.');
+          }
+          const confirmed = await confirmTranslate(plan, providerSettings.name);
+          if (!confirmed) {
+            console.log(chalk.yellow('Translation aborted by user.'));
+            return;
+          }
+        }
+
+        const skipEmpty = options.skipEmpty !== false;
+        const strictPlaceholders = options.strictPlaceholders ?? false;
+        const localeResults = await executeTranslations({
+          plan,
+          translationService,
+          provider: providerSettings,
+          overwrite: options.force ?? false,
+          skipEmpty,
+          placeholderValidator,
+          strictPlaceholders,
+        });
+
+        summary.locales = localeResults.results;
+        summary.localeStats = localeResults.stats;
+
+        // Check for placeholder issues in strict mode
+        const allPlaceholderIssues = localeResults.results.flatMap((r) => r.placeholderIssues);
+        if (strictPlaceholders && allPlaceholderIssues.length > 0) {
+          console.error(
+            chalk.red(
+              `\n✗ ${allPlaceholderIssues.length} placeholder issue(s) detected in translated output:`
+            )
+          );
+          allPlaceholderIssues.slice(0, 10).forEach((issue) => {
+            console.error(
+              chalk.red(
+                `  • ${issue.key} (${issue.locale}): ${issue.type} placeholder${
+                  issue.placeholders.length === 1 ? '' : 's'
+                } ${issue.placeholders.join(', ')}`
+              )
+            );
+          });
+          if (allPlaceholderIssues.length > 10) {
+            console.error(chalk.red(`  ... and ${allPlaceholderIssues.length - 10} more issues`));
+          }
+          process.exitCode = 1;
+        }
+
+        await emitTranslateOutput(summary, options);
+      } catch (error: unknown) {
+        const translatorError = error instanceof TranslatorLoadError ? error : undefined;
+        const normalizedError =
+          error instanceof Error
+            ? error
+            : new Error(typeof error === 'string' ? error : JSON.stringify(error));
+
+        console.error(chalk.red('Translate failed:'), translatorError?.message ?? normalizedError.message);
+        process.exitCode = 1;
+      }
+    });
+}

package/src/commands/translate/reporter.ts

@@ -0,0 +1,138 @@
+/**
+ * Output formatting and reporting utilities for the translate command
+ */
+
+import fs from 'fs/promises';
+import path from 'path';
+import chalk from 'chalk';
+import type { TranslationPlan } from '@i18nsmith/core';
+import { loadTranslator, type TranslatorLoadOptions } from '@i18nsmith/translation';
+import type {
+  TranslateSummary,
+  TranslateLocaleResult,
+  TranslateCommandOptions,
+  ProviderSettings,
+} from './types.js';
+
+/**
+ * Emit the translation output (report file, JSON, or console)
+ */
+export async function emitTranslateOutput(
+  summary: TranslateSummary,
+  options: TranslateCommandOptions
+): Promise<void> {
+  if (options.report) {
+    const outputPath = path.resolve(process.cwd(), options.report);
+    await fs.mkdir(path.dirname(outputPath), { recursive: true });
+    await fs.writeFile(outputPath, JSON.stringify(summary, null, 2));
+    console.log(chalk.green(`Translate report written to ${outputPath}`));
+  }
+
+  if (options.json) {
+    console.log(JSON.stringify(summary, null, 2));
+    return;
+  }
+
+  printPlanSummary(summary.plan);
+
+  if (!summary.dryRun) {
+    printExecutionSummary(summary.locales);
+    const mutations = summary.localeStats.reduce(
+      (total, stat) => total + stat.added.length + stat.updated.length,
+      0
+    );
+    if (mutations === 0) {
+      console.log(chalk.yellow('No locale files were updated. Translator may have skipped all entries.'));
+    }
+  } else {
+    console.log(chalk.yellow('Run again with --write to apply translations.'));
+  }
+}
+
+/**
+ * Print a summary of the translation plan
+ */
+export function printPlanSummary(plan: TranslationPlan): void {
+  console.log(
+    chalk.green(
+      `Source locale ${plan.sourceLocale}; ${plan.totalTasks} missing entr${plan.totalTasks === 1 ? 'y' : 'ies'} across ${plan.locales.length} locale${plan.locales.length === 1 ? '' : 's'}.`
+    )
+  );
+
+  if (!plan.locales.length) {
+    console.log(chalk.green('All configured locales are up to date.'));
+    return;
+  }
+
+  plan.locales.forEach((localePlan) => {
+    const reuseCount = localePlan.tasks.filter((task) => task.reusedValue).length;
+    const reuseMessage = reuseCount > 0 ? chalk.gray(` (${reuseCount} reusable)`) : '';
+    console.log(
+      `  • ${localePlan.locale}: ${localePlan.tasks.length} key${
+        localePlan.tasks.length === 1 ? '' : 's'
+      } (${localePlan.totalCharacters} chars)${reuseMessage}`
+    );
+  });
+}
+
+/**
+ * Print the execution summary after translations are applied
+ */
+export function printExecutionSummary(results: TranslateLocaleResult[]): void {
+  if (!results.length) {
+    console.log(chalk.yellow('No translations were written.'));
+    return;
+  }
+
+  console.log(chalk.blue('\nTranslation results:'));
+  results.forEach((result) => {
+    console.log(
+      `  • ${result.locale}: ${result.written} written, ${result.skipped} skipped, ${result.emptySkipped} empty (${result.characters} chars)`
+    );
+  });
+}
+
+/**
+ * Print cost estimation if available
+ */
+export async function maybePrintEstimate(
+  plan: TranslationPlan,
+  provider: ProviderSettings & { loaderOptions: TranslatorLoadOptions }
+): Promise<void> {
+  console.log(chalk.blue('\n📊 Cost Estimation:'));
+  console.log(chalk.gray(`  Provider: ${provider.name}`));
+  console.log(chalk.gray(`  Total characters: ${plan.totalCharacters.toLocaleString()}`));
+  console.log(chalk.gray(`  Locales: ${plan.locales.length}`));
+
+  try {
+    const translator = await loadTranslator(provider.loaderOptions);
+    if (typeof translator.estimateCost === 'function') {
+      const estimate = await translator.estimateCost(plan.totalCharacters, { localeCount: plan.locales.length });
+      const formattedCost = typeof estimate === 'number'
+        ? `$${estimate.toFixed(4)}`
+        : String(estimate);
+      console.log(chalk.green(`  Estimated cost: ${formattedCost}`));
+    } else {
+      console.log(chalk.yellow('  Provider does not expose cost estimation.'));
+      printGenericEstimate(plan);
+    }
+    await translator.dispose?.();
+  } catch (error) {
+    console.log(chalk.yellow(`  Unable to estimate via provider: ${(error as Error).message}`));
+    printGenericEstimate(plan);
+  }
+}
+
+/**
+ * Print a generic cost estimate based on common cloud provider rates
+ */
+export function printGenericEstimate(plan: TranslationPlan): void {
+  // Generic estimation based on common cloud provider rates (rough average)
+  // Google/AWS/Azure typically charge ~$20 per million characters
+  const ratePerMillion = 20;
+  const charsByLocale = plan.totalCharacters;
+  const totalChars = charsByLocale * plan.locales.length;
+  const estimated = (totalChars / 1_000_000) * ratePerMillion;
+  console.log(chalk.gray(`  Generic estimate (at ~$20/M chars): $${estimated.toFixed(4)}`));
+  console.log(chalk.gray('  (Actual costs vary by provider and tier)'));
+}

package/src/commands/translate/types.ts

@@ -0,0 +1,56 @@
+/**
+ * Type definitions for the translate command
+ */
+
+import type { TranslationWriteSummary, TranslationPlan } from '@i18nsmith/core';
+import type { TranslationService } from '@i18nsmith/core';
+
+export interface TranslateCommandOptions {
+  config?: string;
+  json?: boolean;
+  report?: string;
+  write?: boolean;
+  locales?: string[];
+  provider?: string;
+  force?: boolean;
+  estimate?: boolean;
+  skipEmpty?: boolean;
+  yes?: boolean;
+  strictPlaceholders?: boolean;
+  export?: string;
+  import?: string;
+}
+
+export interface TranslateLocaleResult extends TranslationWriteSummary {
+  characters: number;
+  placeholderIssues: PlaceholderIssue[];
+}
+
+export interface PlaceholderIssue {
+  key: string;
+  locale: string;
+  type: 'missing' | 'extra';
+  placeholders: string[];
+}
+
+export interface TranslateSummary {
+  provider: string;
+  dryRun: boolean;
+  plan: TranslationPlan;
+  locales: TranslateLocaleResult[];
+  localeStats: Awaited<ReturnType<TranslationService['flush']>>;
+  totalCharacters: number;
+}
+
+export interface ProviderSettings {
+  name: string;
+  options?: Record<string, unknown>;
+}
+
+export interface CsvRow {
+  key: string;
+  sourceLocale: string;
+  sourceValue: string;
+  targetLocale: string;
+  targetValue: string;
+}