i18nizer 0.4.0-b → 0.5.0

package/README.md

@@ -226,6 +226,94 @@ Legacy standalone mode (without `i18nizer start`):
 
 ---
 
+## ⚙️ Configuration
+
+### Translation Function Injection (`autoInjectT`)
+
+i18nizer can automatically inject translation hooks into your components:
+
+```ts
+const t = useTranslations("ComponentName");
+```
+
+This behavior is controlled by `behavior.autoInjectT` in `i18nizer.config.yml`:
+
+**Next.js Projects** (disabled by default):
+```yaml
+behavior:
+  autoInjectT: false  # Disabled to avoid breaking Server Components
+```
+
+- Server Components cannot use hooks like `useTranslations`
+- i18nizer will replace strings with `t("key")` but won't inject the hook
+- You manually add the translation hook where appropriate
+
+**React Projects** (enabled by default):
+```yaml
+behavior:
+  autoInjectT: true  # Safe for Client Components
+```
+
+- Full automation: injects hooks and replaces strings
+- Works seamlessly with React components
+
+**Why disabled for Next.js?**
+- Automatically detecting Server vs Client Components is ambiguous
+- Injecting hooks in Server Components causes runtime errors
+- User has full control over translation function placement
+
+You can override this setting in your `i18nizer.config.yml` if you know your setup.
+
+### AI-Powered English Key Generation (`useAiForKeys`)
+
+i18nizer uses AI to generate **English camelCase keys** regardless of your source language:
+
+```yaml
+behavior:
+  useAiForKeys: true  # Default: enabled
+```
+
+**Benefits:**
+- **Consistent keys**: Keys are always in English, even if your source text is in Spanish, French, German, etc.
+- **Readable**: `welcomeBack` instead of `bienvenidoDeNuevo`
+- **Stable**: Keys are cached per source text for deterministic behavior across runs
+- **Minimal diffs**: Same source text always produces the same key
+
+**How it works:**
+1. First run: AI generates an English key for each source text
+2. Key is cached with the source text hash
+3. Subsequent runs: Cached key is reused (no AI call needed)
+4. Fallback: If AI is unavailable, uses deterministic camelCase generation
+
+**Example:**
+
+Source text (Spanish):
+```tsx
+<h1>Bienvenido de nuevo</h1>
+<button>Iniciar sesión</button>
+```
+
+Generated keys (English):
+```json
+{
+  "welcomeBack": "Bienvenido de nuevo",
+  "signIn": "Iniciar sesión"
+}
+```
+
+**Disabling AI key generation:**
+
+If you prefer deterministic key generation based on source text:
+
+```yaml
+behavior:
+  useAiForKeys: false
+```
+
+Note: Keys will be in the source language (e.g., `bienvenidoDeNuevo` for Spanish text).
+
+---
+
 ## ✨ Features
 
 ### Phase 1 (Current)
@@ -235,13 +323,14 @@ Legacy standalone mode (without `i18nizer start`):
 - **Framework presets** (Next.js + next-intl, React + react-i18next)
 - **Intelligent caching** to avoid redundant AI translation requests
 - **String deduplication** with deterministic key reuse
+- **AI-powered English key generation** for consistent, readable keys regardless of source language
 - **Configurable behavior** (allowed functions, props, member functions)
 - **Dry-run mode** to preview changes
 - **JSON output preview** with `--show-json`
 - Project-wide or single-file translation
 - Works with **JSX & TSX**
 - Rewrites components automatically (`t("key")`)
-- Always generates **English camelCase keys**
+- Generates **English camelCase keys** (AI-assisted with deterministic fallback)
 - Supports **any number of locales**
 - Isolated TypeScript parsing (no project tsconfig required)
 - Friendly logs with colors and spinners

package/dist/commands/translate.js

@@ -48,6 +48,7 @@ export default class Translate extends Command {
             description: "Display generated translation JSON output",
         }),
     };
+    // eslint-disable-next-line complexity
     async run() {
         const { args, flags } = await this.parse(Translate);
         const cwd = process.cwd();
@@ -101,11 +102,11 @@ export default class Translate extends Command {
         // Initialize cache and deduplicator
         const projectDir = getProjectDir(cwd);
         const cache = new TranslationCache(projectDir);
-        const deduplicator = new Deduplicator(cache);
+        const deduplicator = new Deduplicator(cache, config.behavior.useAiForKeys, provider);
         let totalExtracted = 0;
         let totalReused = 0;
         let totalCached = 0;
-        // Process each file
+        // Process each file sequentially
         for (const filePath of filesToProcess) {
             const componentName = path.basename(filePath).replace(/\.(tsx|jsx)$/, "");
             const spinner = ora(`Processing ${componentName}...`).start();
@@ -122,22 +123,23 @@ export default class Translate extends Command {
                     continue;
                 }
                 totalExtracted += texts.length;
-                // Deduplicate and assign keys
-                const mappedTexts = texts.map((t) => {
-                    const result = deduplicator.deduplicate(t.text, componentName, config.behavior.detectDuplicates);
+                // Deduplicate and assign keys (now async)
+                // eslint-disable-next-line no-await-in-loop
+                const mappedTexts = await Promise.all(texts.map(async (t) => {
+                    const result = await deduplicator.deduplicate(t.text, componentName, config.behavior.detectDuplicates);
                     if (result.isReused)
                         totalReused++;
                     if (result.isCached)
                         totalCached++;
                     return {
+                        isCached: result.isCached,
                         key: result.key,
                         node: t.node,
                         placeholders: t.placeholders,
                         tempKey: t.tempKey,
                         text: t.text,
-                        isCached: result.isCached,
                     };
-                });
+                }));
                 // Build translations JSON
                 const i18nJson = {};
                 for (const mapped of mappedTexts) {
@@ -169,6 +171,7 @@ export default class Translate extends Command {
                             text: t.text,
                         })),
                     });
+                    // eslint-disable-next-line no-await-in-loop
                     const raw = await generateTranslations(prompt, provider);
                     if (!raw)
                         throw new Error("AI did not return any data");
@@ -178,7 +181,6 @@ export default class Translate extends Command {
                     for (const mapped of textsNeedingTranslation) {
                         const aiTranslations = namespace[mapped.tempKey];
                         if (aiTranslations) {
-                            const aiKey = aiTranslations.key;
                             for (const locale of locales) {
                                 i18nJson[mapped.key][locale] = aiTranslations[locale] ?? mapped.text;
                             }
@@ -210,7 +212,10 @@ export default class Translate extends Command {
                         writeLocaleFiles(componentName, { [componentName]: i18nJson }, locales);
                     }
                     // Rewrite component
-                    insertUseTranslations(sourceFile, componentName);
+                    // Only inject t function if autoInjectT is enabled
+                    if (config.behavior.autoInjectT) {
+                        insertUseTranslations(sourceFile, componentName);
+                    }
                     replaceTempKeysWithT(mappedTexts.map((m) => ({
                         key: m.key,
                         node: m.node,

package/dist/core/ai/client.js

@@ -3,7 +3,7 @@ import { InferenceClient as HFClient } from "@huggingface/inference";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import OpenAI from "openai";
+import { OpenAI } from "openai";
 const CONFIG_FILE = path.join(os.homedir(), ".i18nizer", "api-keys.json");
 function loadApiKeys() {
     if (!fs.existsSync(CONFIG_FILE)) {

package/dist/core/ai/generate-english-key.js

@@ -0,0 +1,46 @@
+import { generateTranslations } from "./client.js";
+/**
+ * Generate an English camelCase key from text using AI
+ * This ensures keys are always in English regardless of source language
+ */
+export async function generateEnglishKey(text, provider = "huggingface") {
+    const prompt = `
+You are an i18n key generator. Generate a concise, meaningful camelCase key in English for the following text.
+
+RULES:
+- Output ONLY the camelCase key, nothing else
+- Key should be 2-4 words maximum
+- Key must be in English
+- Key should describe the content/purpose
+- Do NOT include quotes, explanations, or any other text
+
+TEXT: "${text.replaceAll('"', '\\"')}"
+
+EXAMPLES:
+TEXT: "Bienvenido de nuevo" -> welcomeBack
+TEXT: "Por favor inicia sesión" -> pleaseSignIn
+TEXT: "Enviar formulario" -> submitForm
+TEXT: "Seleccionar ciudad" -> selectCity
+
+OUTPUT (key only):`.trim();
+    try {
+        const response = await generateTranslations(prompt, provider);
+        if (!response)
+            return undefined;
+        // Clean the response - remove quotes, whitespace, and any extra text
+        const cleaned = response
+            .trim()
+            .replaceAll(/["'`]/g, "")
+            .replaceAll(/\s+/g, " ")
+            .split(/\s+/)[0]; // Take only the first word/token
+        // Validate it's a valid camelCase identifier
+        if (/^[a-z][a-zA-Z0-9]*$/.test(cleaned)) {
+            return cleaned;
+        }
+        return undefined;
+    }
+    catch (error) {
+        console.error("❌ Error generating English key with AI:", error);
+        return undefined;
+    }
+}

package/dist/core/config/config-manager.js

@@ -100,19 +100,23 @@ function mergeConfig(base, override) {
  */
 export function generateConfig(framework, i18nLibrary) {
     const frameworkPreset = FRAMEWORK_PRESETS[framework];
+    // Start with defaults merged with framework preset
+    const baseConfig = mergeConfig(DEFAULT_CONFIG, frameworkPreset);
+    // Set autoInjectT based on framework (disabled for Next.js by default)
+    if (framework === "nextjs") {
+        baseConfig.behavior.autoInjectT = false;
+    }
     // If i18n library is specified, apply it after framework preset
     // Framework settings take precedence for non-i18n specific fields
     if (i18nLibrary) {
         const i18nConfig = I18N_LIBRARY_CONFIGS[i18nLibrary];
-        // Merge: defaults -> framework -> i18n library (i18n-specific fields only)
-        const merged = mergeConfig(DEFAULT_CONFIG, frameworkPreset);
         return {
-            ...merged,
+            ...baseConfig,
             i18nLibrary: i18nConfig.i18nLibrary,
-            i18n: i18nConfig.i18n ?? merged.i18n,
+            i18n: i18nConfig.i18n ?? baseConfig.i18n,
         };
     }
-    return mergeConfig(DEFAULT_CONFIG, frameworkPreset);
+    return baseConfig;
 }
 /**
  * Write config to file

package/dist/core/deduplication/deduplicator.js

@@ -1,18 +1,23 @@
+import { generateEnglishKey } from "../ai/generate-english-key.js";
 import { generateKey, generateUniqueKey } from "../i18n/generate-key.js";
 /**
  * Deduplicate strings and assign deterministic keys
  */
 export class Deduplicator {
     cache;
+    provider;
+    useAiForKeys;
     usedKeys = new Set();
-    constructor(cache) {
+    constructor(cache, useAiForKeys = true, provider = "huggingface") {
         this.cache = cache;
+        this.provider = provider;
+        this.useAiForKeys = useAiForKeys;
     }
     /**
      * Process a text and return a deterministic key
      * Reuses existing keys if the text was seen before
      */
-    deduplicate(text, componentName, detectDuplicates) {
+    async deduplicate(text, componentName, detectDuplicates) {
         // Check cache first
         const cached = this.cache.get(text);
         if (cached && detectDuplicates) {
@@ -25,7 +30,16 @@ export class Deduplicator {
             };
         }
         // Generate a new deterministic key
-        const baseKey = generateKey(text);
+        let baseKey;
+        if (this.useAiForKeys && !cached) {
+            // Try to generate English key using AI
+            const aiKey = await generateEnglishKey(text, this.provider);
+            baseKey = aiKey ?? generateKey(text);
+        }
+        else {
+            // Use deterministic key generation (fallback or when AI is disabled)
+            baseKey = generateKey(text);
+        }
         const uniqueKey = generateUniqueKey(baseKey, this.usedKeys);
         this.usedKeys.add(uniqueKey);
         return {

package/dist/types/config.js

@@ -16,8 +16,10 @@ export const DEFAULT_CONFIG = {
             "title",
             "tooltip",
         ],
+        autoInjectT: true, // Default enabled for React
         detectDuplicates: true,
         opinionatedStructure: true,
+        useAiForKeys: true, // Use AI to generate English keys
     },
     framework: "react",
     i18n: {

package/oclif.manifest.json

@@ -301,5 +301,5 @@
       ]
     }
   },
-  "version": "0.4.0-b"
+  "version": "0.5.0"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "i18nizer",
   "description": "CLI to extract texts from JSX/TSX and generate i18n JSON with AI translations",
-  "version": "0.4.0-b",
+  "version": "0.5.0",
   "author": "Yoannis Sanchez Soto",
   "bin": "./bin/run.js",
   "bugs": "https://github.com/yossTheDev/i18nizer/issues",