@idealyst/translate 1.2.3

package/src/babel/reporter.ts

@@ -0,0 +1,287 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import type {
+  TranslatePluginOptions,
+  ExtractedKey,
+  TranslationsReport,
+  MissingTranslation,
+  LoadedTranslations,
+} from './types';
+
+/**
+ * Check if an object has a nested key
+ */
+function hasNestedKey(obj: Record<string, unknown>, keyPath: string): boolean {
+  const parts = keyPath.split('.');
+  let current: unknown = obj;
+
+  for (const part of parts) {
+    if (current === undefined || current === null) return false;
+    if (typeof current !== 'object') return false;
+    current = (current as Record<string, unknown>)[part];
+  }
+
+  return current !== undefined;
+}
+
+/**
+ * Flatten an object's keys into dot-notation
+ */
+function flattenKeys(obj: Record<string, unknown>, prefix: string = ''): string[] {
+  const keys: string[] = [];
+
+  for (const [key, value] of Object.entries(obj)) {
+    const fullKey = prefix ? `${prefix}.${key}` : key;
+
+    if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+      keys.push(...flattenKeys(value as Record<string, unknown>, fullKey));
+    } else {
+      keys.push(fullKey);
+    }
+  }
+
+  return keys;
+}
+
+/**
+ * Parse a key into namespace and local key
+ */
+function parseKey(
+  fullKey: string,
+  defaultNamespace: string = 'translation'
+): { namespace: string; localKey: string } {
+  if (fullKey.includes(':')) {
+    const [namespace, ...rest] = fullKey.split(':');
+    return { namespace, localKey: rest.join(':') };
+  }
+
+  const segments = fullKey.split('.');
+  if (segments.length > 1) {
+    return { namespace: segments[0], localKey: segments.slice(1).join('.') };
+  }
+
+  return { namespace: defaultNamespace, localKey: fullKey };
+}
+
+/**
+ * Extract language code from file path
+ */
+function extractLanguageFromPath(filePath: string): string {
+  const parts = filePath.split(path.sep);
+  const filename = path.basename(filePath, '.json');
+
+  if (filename.match(/^[a-z]{2}(-[A-Z]{2})?$/)) {
+    return filename;
+  }
+
+  const parentDir = parts[parts.length - 2];
+  if (parentDir && parentDir.match(/^[a-z]{2}(-[A-Z]{2})?$/)) {
+    return parentDir;
+  }
+
+  return filename;
+}
+
+/**
+ * Extract namespace from file path
+ */
+function extractNamespaceFromPath(filePath: string): string {
+  const filename = path.basename(filePath, '.json');
+
+  if (filename.match(/^[a-z]{2}(-[A-Z]{2})?$/)) {
+    return 'translation';
+  }
+
+  return filename;
+}
+
+/**
+ * Load translation files from glob patterns
+ */
+export function loadTranslations(
+  patterns: string[],
+  verbose: boolean = false
+): LoadedTranslations {
+  const result: LoadedTranslations = {};
+
+  // Dynamic import glob if available
+  let globSync: ((pattern: string) => string[]) | null = null;
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const glob = require('glob');
+    globSync = glob.sync;
+  } catch {
+    globSync = null;
+  }
+
+  for (const pattern of patterns) {
+    let files: string[] = [];
+
+    if (globSync) {
+      try {
+        files = globSync(pattern);
+      } catch (err) {
+        if (verbose) {
+          console.warn(`[@idealyst/translate] Failed to glob pattern: ${pattern}`, err);
+        }
+        continue;
+      }
+    } else if (fs.existsSync(pattern)) {
+      files = [pattern];
+    }
+
+    for (const file of files) {
+      try {
+        const content = JSON.parse(fs.readFileSync(file, 'utf-8'));
+        const lang = extractLanguageFromPath(file);
+        const namespace = extractNamespaceFromPath(file);
+
+        if (!result[lang]) result[lang] = {};
+        result[lang][namespace] = content;
+
+        if (verbose) {
+          console.log(`[@idealyst/translate] Loaded: ${file} -> ${lang}/${namespace}`);
+        }
+      } catch (err) {
+        if (verbose) {
+          console.warn(`[@idealyst/translate] Failed to load: ${file}`, err);
+        }
+      }
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Generate a translations report from extracted keys
+ */
+export function generateReport(
+  extractedKeys: ExtractedKey[],
+  options: TranslatePluginOptions
+): TranslationsReport {
+  const {
+    translationFiles,
+    languages: configLanguages,
+    defaultNamespace = 'translation',
+    verbose = false,
+  } = options;
+
+  const translations = loadTranslations(translationFiles, verbose);
+  const languages = configLanguages || Object.keys(translations);
+
+  const staticKeys = extractedKeys.filter((k) => !k.isDynamic);
+  const dynamicKeys = extractedKeys.filter((k) => k.isDynamic);
+  const uniqueKeys = [...new Set(staticKeys.map((k) => k.key))];
+
+  // Find missing translations per language
+  const missing: Record<string, MissingTranslation[]> = {};
+  for (const lang of languages) {
+    missing[lang] = [];
+    const langTranslations = translations[lang] || {};
+
+    for (const key of uniqueKeys) {
+      const { namespace, localKey } = parseKey(key, defaultNamespace);
+      const nsTranslations = langTranslations[namespace] || {};
+
+      if (!hasNestedKey(nsTranslations as Record<string, unknown>, localKey)) {
+        const usages = staticKeys.filter((k) => k.key === key);
+        missing[lang].push({
+          key,
+          namespace,
+          usedIn: usages.map((u) => ({
+            file: u.file,
+            line: u.line,
+            column: u.column,
+          })),
+          defaultValue: usages[0]?.defaultValue,
+        });
+      }
+    }
+  }
+
+  // Find unused translations per language
+  const unused: Record<string, string[]> = {};
+  for (const lang of languages) {
+    unused[lang] = [];
+    const langTranslations = translations[lang] || {};
+
+    for (const namespace of Object.keys(langTranslations)) {
+      const keys = flattenKeys(
+        langTranslations[namespace] as Record<string, unknown>,
+        namespace
+      );
+      for (const translationKey of keys) {
+        if (!uniqueKeys.includes(translationKey)) {
+          unused[lang].push(translationKey);
+        }
+      }
+    }
+  }
+
+  // Calculate coverage
+  const coveragePercent: Record<string, number> = {};
+  for (const lang of languages) {
+    const totalKeys = uniqueKeys.length;
+    const missingCount = missing[lang].length;
+    coveragePercent[lang] =
+      totalKeys > 0 ? Math.round(((totalKeys - missingCount) / totalKeys) * 100) : 100;
+  }
+
+  return {
+    timestamp: new Date().toISOString(),
+    totalKeys: uniqueKeys.length,
+    dynamicKeys,
+    extractedKeys: staticKeys,
+    languages,
+    missing,
+    unused,
+    summary: {
+      totalMissing: Object.values(missing).flat().length,
+      totalUnused: Object.values(unused).flat().length,
+      coveragePercent,
+    },
+  };
+}
+
+/**
+ * Write a translations report to disk
+ */
+export function writeReport(report: TranslationsReport, outputPath: string): void {
+  const dir = path.dirname(outputPath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  fs.writeFileSync(outputPath, JSON.stringify(report, null, 2), 'utf-8');
+}
+
+/**
+ * Print report summary to console
+ */
+export function printReportSummary(report: TranslationsReport): void {
+  console.log('\n[@idealyst/translate] Translation Report Summary');
+  console.log('='.repeat(50));
+  console.log(`Total keys: ${report.totalKeys}`);
+  console.log(`Dynamic keys: ${report.dynamicKeys.length}`);
+  console.log(`Languages: ${report.languages.join(', ')}`);
+  console.log('');
+
+  for (const lang of report.languages) {
+    const coverage = report.summary.coveragePercent[lang];
+    const missingCount = report.missing[lang]?.length || 0;
+    const unusedCount = report.unused[lang]?.length || 0;
+
+    console.log(`${lang}: ${coverage}% coverage`);
+    if (missingCount > 0) {
+      console.log(`  - ${missingCount} missing translation(s)`);
+    }
+    if (unusedCount > 0) {
+      console.log(`  - ${unusedCount} unused translation(s)`);
+    }
+  }
+
+  console.log('');
+  console.log(`Total missing: ${report.summary.totalMissing}`);
+  console.log(`Total unused: ${report.summary.totalUnused}`);
+  console.log('='.repeat(50));
+}

package/src/babel/types.ts

@@ -0,0 +1,214 @@
+/**
+ * Options for the @idealyst/translate Babel plugin
+ */
+export interface TranslatePluginOptions {
+  /**
+   * Paths to translation JSON files
+   * Supports glob patterns: ['./locales/*.json', './src/locales/**\/*.json']
+   */
+  translationFiles: string[];
+
+  /**
+   * Output path for the translation report
+   * @default '.idealyst/translations-report.json'
+   */
+  reportPath?: string;
+
+  /**
+   * Languages to check against
+   * If not provided, inferred from translation file names/directories
+   */
+  languages?: string[];
+
+  /**
+   * Default namespace used when namespace is not specified in the key
+   * @default 'translation'
+   */
+  defaultNamespace?: string;
+
+  /**
+   * Whether to fail the build if missing translations are found
+   * @default false
+   */
+  failOnMissing?: boolean;
+
+  /**
+   * Whether to emit console warnings for missing translations
+   * @default true
+   */
+  emitWarnings?: boolean;
+
+  /**
+   * Whether to include source locations in the report
+   * @default true
+   */
+  includeLocations?: boolean;
+
+  /**
+   * Enable verbose logging
+   * @default false
+   */
+  verbose?: boolean;
+}
+
+/**
+ * A translation key extracted from source code
+ */
+export interface ExtractedKey {
+  /**
+   * Full key path including namespace: "common.buttons.submit" or "common:buttons.submit"
+   */
+  key: string;
+
+  /**
+   * Namespace portion: "common"
+   */
+  namespace: string;
+
+  /**
+   * Key without namespace: "buttons.submit"
+   */
+  localKey: string;
+
+  /**
+   * Source file path
+   */
+  file: string;
+
+  /**
+   * Line number in source
+   */
+  line: number;
+
+  /**
+   * Column number in source
+   */
+  column: number;
+
+  /**
+   * Default value if provided in code
+   */
+  defaultValue?: string;
+
+  /**
+   * Whether this is a dynamic key (contains variables, cannot be statically analyzed)
+   */
+  isDynamic: boolean;
+}
+
+/**
+ * A missing translation entry
+ */
+export interface MissingTranslation {
+  /**
+   * The missing key
+   */
+  key: string;
+
+  /**
+   * Namespace
+   */
+  namespace: string;
+
+  /**
+   * Files where this key is used
+   */
+  usedIn: Array<{
+    file: string;
+    line: number;
+    column: number;
+  }>;
+
+  /**
+   * Default value if provided in code
+   */
+  defaultValue?: string;
+}
+
+/**
+ * Translation coverage statistics
+ */
+export interface CoverageStats {
+  /**
+   * Total number of unique static keys found in code
+   */
+  totalKeys: number;
+
+  /**
+   * Number of keys missing translation for this language
+   */
+  missingCount: number;
+
+  /**
+   * Percentage of keys that have translations (0-100)
+   */
+  coveragePercent: number;
+}
+
+/**
+ * The full translations report output
+ */
+export interface TranslationsReport {
+  /**
+   * Report generation timestamp (ISO 8601)
+   */
+  timestamp: string;
+
+  /**
+   * Total number of unique static keys extracted
+   */
+  totalKeys: number;
+
+  /**
+   * Keys that couldn't be statically analyzed (dynamic keys)
+   */
+  dynamicKeys: ExtractedKey[];
+
+  /**
+   * All extracted static keys
+   */
+  extractedKeys: ExtractedKey[];
+
+  /**
+   * Languages analyzed
+   */
+  languages: string[];
+
+  /**
+   * Missing translations per language
+   * { "es": [...], "fr": [...] }
+   */
+  missing: Record<string, MissingTranslation[]>;
+
+  /**
+   * Unused translations per language (keys in JSON but not in code)
+   * { "en": ["legacy.oldKey"], ... }
+   */
+  unused: Record<string, string[]>;
+
+  /**
+   * Summary statistics
+   */
+  summary: {
+    /**
+     * Total missing translations across all languages
+     */
+    totalMissing: number;
+
+    /**
+     * Total unused translations across all languages
+     */
+    totalUnused: number;
+
+    /**
+     * Coverage percentage per language
+     */
+    coveragePercent: Record<string, number>;
+  };
+}
+
+/**
+ * Loaded translations structure
+ * { [language]: { [namespace]: { nested: { key: "value" } } } }
+ */
+export type LoadedTranslations = Record<string, Record<string, Record<string, unknown>>>;

package/src/components/Trans.tsx

@@ -0,0 +1,72 @@
+import React from 'react';
+import { Trans as I18nextTrans } from 'react-i18next';
+import type { TransProps } from './types';
+
+/**
+ * Component for rendering translations with rich text and interpolation
+ *
+ * @example Basic usage
+ * ```tsx
+ * import { Trans } from '@idealyst/translate';
+ *
+ * // Translation: "Hello, {{name}}!"
+ * <Trans i18nKey="greeting" values={{ name: 'World' }} />
+ * ```
+ *
+ * @example With components
+ * ```tsx
+ * // Translation: "Click <bold>here</bold> for <link>help</link>"
+ * <Trans
+ *   i18nKey="helpText"
+ *   components={{
+ *     bold: <strong />,
+ *     link: <a href="/help" />,
+ *   }}
+ * />
+ * ```
+ *
+ * @example With pluralization
+ * ```tsx
+ * // Translation: "{{count}} item" / "{{count}} items"
+ * <Trans i18nKey="itemCount" count={5} />
+ * ```
+ *
+ * @example With children for interpolation
+ * ```tsx
+ * // Translation: "Read <0>our terms</0> and <1>privacy policy</1>"
+ * <Trans i18nKey="legal">
+ *   <a href="/terms">our terms</a>
+ *   <a href="/privacy">privacy policy</a>
+ * </Trans>
+ * ```
+ */
+export function Trans({
+  i18nKey,
+  ns,
+  defaults,
+  components,
+  values,
+  count,
+  context,
+  parent,
+  children,
+  shouldUnescape,
+}: TransProps) {
+  return (
+    <I18nextTrans
+      i18nKey={i18nKey}
+      ns={ns}
+      defaults={defaults}
+      components={components}
+      values={values}
+      count={count}
+      context={context}
+      parent={parent}
+      shouldUnescape={shouldUnescape}
+    >
+      {children}
+    </I18nextTrans>
+  );
+}
+
+export default Trans;

package/src/components/index.ts

@@ -0,0 +1,2 @@
+export { Trans, default } from './Trans';
+export type { TransProps } from './types';

package/src/components/types.ts

@@ -0,0 +1,64 @@
+import type { ReactElement, ReactNode } from 'react';
+import type { Namespace } from 'i18next';
+
+/**
+ * Props for the Trans component
+ */
+export interface TransProps {
+  /**
+   * Translation key
+   */
+  i18nKey: string;
+
+  /**
+   * Namespace for the translation
+   */
+  ns?: Namespace;
+
+  /**
+   * Default value if key is not found
+   */
+  defaults?: string;
+
+  /**
+   * Component map for interpolation
+   * Keys correspond to tags in the translation string
+   *
+   * @example
+   * Translation: "Click <bold>here</bold> for <link>help</link>"
+   * Components: { bold: <strong />, link: <a href="/help" /> }
+   */
+  components?: Record<string, ReactElement>;
+
+  /**
+   * Values for interpolation
+   */
+  values?: Record<string, unknown>;
+
+  /**
+   * Count for pluralization
+   */
+  count?: number;
+
+  /**
+   * Context for contextual translations
+   */
+  context?: string;
+
+  /**
+   * Tag name for the wrapper element
+   * @default React.Fragment
+   */
+  parent?: string | null;
+
+  /**
+   * Children elements that can be used for interpolation
+   */
+  children?: ReactNode;
+
+  /**
+   * Whether to unescape HTML entities
+   * @default false
+   */
+  shouldUnescape?: boolean;
+}

package/src/config/index.ts

@@ -0,0 +1,2 @@
+export { defineConfig } from './types';
+export type { TranslateConfig } from './types';

package/src/config/types.ts

@@ -0,0 +1,10 @@
+import type { TranslateConfig } from '../provider/types';
+
+/**
+ * Define a translation configuration with type safety
+ */
+export function defineConfig(config: TranslateConfig): TranslateConfig {
+  return config;
+}
+
+export type { TranslateConfig };

package/src/hooks/index.ts

@@ -0,0 +1,8 @@
+export { useTranslation, default as useTranslationDefault } from './useTranslation';
+export { useLanguage } from './useLanguage';
+export type {
+  UseTranslationOptions,
+  UseTranslationResult,
+  TranslationOptions,
+  UseLanguageResult,
+} from './types';