@scoutello/i18n-magic 0.54.0 → 0.56.0

package/src/lib/utils.ts

@@ -3,6 +3,7 @@ import { Parser } from "i18next-scanner"
 import { minimatch } from "minimatch"
 import fs from "node:fs"
 import path from "node:path"
+import { performance } from "node:perf_hooks"
 import type OpenAI from "openai"
 import prompts from "prompts"
 import { languages } from "./languges.js"
@@ -527,7 +528,9 @@ export const findExistingTranslation = async (
   for (const namespace of namespaces) {
     try {
       const existingKeys = await loadLocalesFile(loadPath, locale, namespace)
-      if (existingKeys[key]) {
+      // Use explicit existence check instead of truthy check
+      // to handle empty string values correctly
+      if (Object.prototype.hasOwnProperty.call(existingKeys, key)) {
         return existingKeys[key]
       }
     } catch (error) {
@@ -567,7 +570,12 @@ export const findExistingTranslations = async (
   for (const key of keys) {
     let found = false
     for (const namespace of namespaces) {
-      if (namespaceKeys[namespace]?.[key]) {
+      // Use explicit existence check instead of truthy check
+      // to handle empty string values correctly
+      if (
+        namespaceKeys[namespace] &&
+        Object.prototype.hasOwnProperty.call(namespaceKeys[namespace], key)
+      ) {
         results[key] = namespaceKeys[namespace][key]
         found = true
         break
@@ -692,29 +700,49 @@ export class TranslationError extends Error {
  * This function adds to the specified language locale, and will also translate
  * and save to other locales if OpenAI is configured.
  */
-export const addTranslationKey = async ({
-  key,
-  value,
-  language = "en",
+/**
+ * Add multiple translation keys in batch. This is optimized for performance:
+ * - Single codebase scan for all keys
+ * - Batched file I/O operations
+ * - Batched translations per locale
+ */
+export const addTranslationKeys = async ({
+  keys,
   config,
 }: {
-  key: string
-  value: string
-  language?: string
+  keys: Array<{ key: string; value: string; language?: string }>
   config: Configuration
 }) => {
+  const startTime = performance.now()
   const { loadPath, savePath, defaultNamespace, namespaces, globPatterns, defaultLocale, openai, context, model } = config
 
-  // Try to find which namespaces this key is used in by scanning the codebase
-  const affectedNamespaces: string[] = []
-  
+  if (keys.length === 0) {
+    return { results: [], performance: { totalTime: 0, scanTime: 0, translationTime: 0, fileIOTime: 0 } }
+  }
+
+  const log = console.log
+  log(`🚀 Batch adding ${keys.length} translation key(s)...`)
+
+  // Step 1: Single codebase scan for all keys (most expensive operation)
+  const scanStartTime = performance.now()
+  let keysWithNamespaces: Array<{ key: string; namespaces: string[]; file: string }> = []
   try {
-    // Scan the codebase to find where this key is already being used
-    const keysWithNamespaces = await getKeysWithNamespaces({
+    keysWithNamespaces = await getKeysWithNamespaces({
       globPatterns,
       defaultNamespace,
     })
+  } catch (error) {
+    console.error(`Warning: Failed to scan codebase for key usage: ${error}`)
+  }
+  const scanTime = performance.now() - scanStartTime
+  log(`⏱️  Codebase scan completed in ${scanTime.toFixed(2)}ms`)
 
+  // Step 2: Determine namespaces for each key
+  const keyToNamespaces = new Map<string, Set<string>>()
+  
+  for (const { key, language = "en" } of keys) {
+    const affectedNamespaces: string[] = []
+    
     // Find entries for this specific key
     const keyEntries = keysWithNamespaces.filter(
       (entry) => entry.key === key || entry.key === `${defaultNamespace}:${key}`
@@ -730,112 +758,232 @@ export const addTranslationKey = async ({
 
     if (foundNamespaces.size > 0) {
       affectedNamespaces.push(...Array.from(foundNamespaces))
-      console.log(
-        `🔍 Found key "${key}" in use across ${affectedNamespaces.length} namespace(s): ${affectedNamespaces.join(", ")}`
-      )
+    } else {
+      // If the key is not found in the codebase, use the default namespace
+      affectedNamespaces.push(defaultNamespace)
     }
-  } catch (error) {
-    // If scanning fails, continue with fallback logic
-    console.error(`Warning: Failed to scan codebase for key usage: ${error}`)
-  }
 
-  if (affectedNamespaces.length === 0) {
-    // If the key is not found in the codebase, use the default namespace
-    affectedNamespaces.push(defaultNamespace)
-    console.log(
-      `📝 Key "${key}" not found in codebase. Adding to default namespace "${defaultNamespace}".`
-    )
+    keyToNamespaces.set(key, new Set(affectedNamespaces))
   }
 
-  // Use the specified language as the locale for adding keys
-  const locale = language
-
-  // Use console.error for logging when called from MCP server (console.log is suppressed)
-  const log = console.log
-
-  // Track which locales were successfully saved
-  const savedLocales = new Set<string>([locale])
-
-  for (const targetNamespace of affectedNamespaces) {
-    log(`➕ Adding translation key "${key}" to namespace "${targetNamespace}" (${locale})`)
-
-    // Load existing keys for the specified locale
-    let existingKeys: Record<string, string>
-    try {
-      existingKeys = await loadLocalesFile(loadPath, locale, targetNamespace)
-    } catch (error) {
-      // If file doesn't exist, start with empty object
-      log(`📄 Creating new namespace file for ${locale}/${targetNamespace}`)
-      existingKeys = {}
+  // Step 3: Group keys by namespace and locale
+  const namespaceLocaleToKeys = new Map<string, Array<{ key: string; value: string; language: string }>>()
+  
+  for (const { key, value, language = "en" } of keys) {
+    const namespaces = keyToNamespaces.get(key) || new Set([defaultNamespace])
+    for (const namespace of namespaces) {
+      const mapKey = `${namespace}:${language}`
+      if (!namespaceLocaleToKeys.has(mapKey)) {
+        namespaceLocaleToKeys.set(mapKey, [])
+      }
+      namespaceLocaleToKeys.get(mapKey)!.push({ key, value, language })
     }
+  }
 
-    // Check if key already exists
-    if (existingKeys[key]) {
-      log(`⚠️  Key "${key}" already exists in ${locale}/${targetNamespace} with value: "${existingKeys[key]}"`)
-      log(`   Updating to new value: "${value}"`)
+  // Step 4: Collect all unique namespaces that will be affected
+  const affectedNamespaces = new Set<string>()
+  for (const namespaces of keyToNamespaces.values()) {
+    for (const ns of namespaces) {
+      affectedNamespaces.add(ns)
     }
+  }
 
-    // Add or update the key
-    existingKeys[key] = value
+  // Step 5: Batch load ALL locale files for affected namespaces (not just input language)
+  // This ensures we preserve existing keys in all locales
+  const fileIOStartTime = performance.now()
+  const localeFiles = new Map<string, Record<string, string>>()
+  const loadPromises: Promise<void>[] = []
+  
+  // Load files for all locales × all affected namespaces
+  for (const namespace of affectedNamespaces) {
+    for (const locale of config.locales) {
+      const fileKey = `${locale}:${namespace}`
+      
+      if (!localeFiles.has(fileKey)) {
+        loadPromises.push(
+          loadLocalesFile(loadPath, locale, namespace)
+            .then((keys) => {
+              localeFiles.set(fileKey, keys)
+            })
+            .catch(() => {
+              localeFiles.set(fileKey, {})
+            })
+        )
+      }
+    }
+  }
+  
+  await Promise.all(loadPromises)
+  const fileIOTime = performance.now() - fileIOStartTime
+  log(`⏱️  File I/O (load) completed in ${fileIOTime.toFixed(2)}ms`)
+
+  // Step 6: Add new keys to the input language locale files
+  for (const [namespaceLocale, keyValues] of namespaceLocaleToKeys) {
+    const [namespace, locale] = namespaceLocale.split(":")
+    const fileKey = `${locale}:${namespace}`
+    const existingKeys = localeFiles.get(fileKey) || {}
+    
+    for (const { key, value } of keyValues) {
+      existingKeys[key] = value
+    }
+    
+    localeFiles.set(fileKey, existingKeys)
+  }
 
-    // Save the updated keys using the writeLocalesFile function
-    await writeLocalesFile(savePath, locale, targetNamespace, existingKeys)
-    log(`✅ Successfully saved key to ${locale}/${targetNamespace}`)
+  // Step 7: Batch translate if OpenAI is configured
+  const translationStartTime = performance.now()
+  const translationCache = new Map<string, Record<string, string>>()
+  
+  if (openai) {
+    // Group keys by input language
+    const keysByLanguage = new Map<string, Array<{ key: string; value: string; namespaces: Set<string> }>>()
+    
+    for (const { key, value, language = "en" } of keys) {
+      if (!keysByLanguage.has(language)) {
+        keysByLanguage.set(language, [])
+      }
+      keysByLanguage.get(language)!.push({
+        key,
+        value,
+        namespaces: keyToNamespaces.get(key) || new Set([defaultNamespace]),
+      })
+    }
 
-    // If OpenAI is configured, translate to other locales automatically
-    if (openai) {
-      const otherLocales = config.locales.filter(l => l !== locale)
+    // Translate each language group to all other locales
+    const translationPromises: Promise<void>[] = []
+    
+    for (const [inputLanguage, keyValues] of keysByLanguage) {
+      const otherLocales = config.locales.filter(l => l !== inputLanguage)
       
-      if (otherLocales.length > 0) {
-        log(`🌐 Translating key "${key}" to ${otherLocales.length} other locale(s)...`)
+      for (const targetLocale of otherLocales) {
+        const keysToTranslate = Object.fromEntries(
+          keyValues.map(({ key, value }) => [key, value])
+        )
         
-        try {
-          // Translate to all other locales in parallel
-          await Promise.all(
-            otherLocales.map(async (targetLocale) => {
-              try {
-                const translatedValue = await translateKey({
-                  inputLanguage: locale,
-                  outputLanguage: targetLocale,
-                  context: context || "",
-                  object: { [key]: value },
-                  openai,
-                  model,
-                })
-
-                // Load existing keys for the target locale
-                let targetLocaleKeys: Record<string, string>
-                try {
-                  targetLocaleKeys = await loadLocalesFile(loadPath, targetLocale, targetNamespace)
-                } catch (error) {
-                  log(`📄 Creating new namespace file for ${targetLocale}/${targetNamespace}`)
-                  targetLocaleKeys = {}
-                }
-
-                // Add the translated key
-                targetLocaleKeys[key] = translatedValue[key]
-
-                // Save the updated keys
-                await writeLocalesFile(savePath, targetLocale, targetNamespace, targetLocaleKeys)
-                savedLocales.add(targetLocale)
-                log(`✅ Successfully translated and saved key to ${targetLocale}/${targetNamespace}`)
-              } catch (error) {
-                log(`⚠️  Failed to translate key to ${targetLocale}: ${error instanceof Error ? error.message : "Unknown error"}`)
-              }
+        translationPromises.push(
+          translateKey({
+            inputLanguage,
+            outputLanguage: targetLocale,
+            context: context || "",
+            object: keysToTranslate,
+            openai,
+            model,
+          })
+            .then((translated) => {
+              translationCache.set(`${inputLanguage}:${targetLocale}`, translated)
             })
-          )
-        } catch (error) {
-          log(`⚠️  Translation error: ${error instanceof Error ? error.message : "Unknown error"}`)
-          log(`   You can run 'i18n-magic sync' to translate this key later`)
+            .catch((error) => {
+              log(`⚠️  Failed to translate ${keyValues.length} key(s) from ${inputLanguage} to ${targetLocale}: ${error instanceof Error ? error.message : "Unknown error"}`)
+            })
+        )
+      }
+    }
+    
+    await Promise.all(translationPromises)
+    
+    // Add translated keys to locale files (merge with existing keys)
+    for (const [inputLanguage, keyValues] of keysByLanguage) {
+      const otherLocales = config.locales.filter(l => l !== inputLanguage)
+      
+      for (const targetLocale of otherLocales) {
+        const translated = translationCache.get(`${inputLanguage}:${targetLocale}`)
+        if (!translated) continue
+        
+        for (const { key, namespaces } of keyValues) {
+          if (translated[key]) {
+            for (const namespace of namespaces) {
+              const fileKey = `${targetLocale}:${namespace}`
+              // File should already be loaded from step 5, but ensure it exists
+              if (!localeFiles.has(fileKey)) {
+                localeFiles.set(fileKey, {})
+              }
+              // Merge translated key with existing keys (don't overwrite the whole file)
+              localeFiles.get(fileKey)![key] = translated[key]
+            }
+          }
         }
       }
     }
   }
+  
+  const translationTime = performance.now() - translationStartTime
+  if (openai && translationTime > 0) {
+    log(`⏱️  Translation completed in ${translationTime.toFixed(2)}ms`)
+  }
+
+  // Step 8: Batch write all files
+  const writeStartTime = performance.now()
+  const writePromises: Promise<void>[] = []
+  
+  for (const [fileKey, keys] of localeFiles) {
+    const [locale, namespace] = fileKey.split(":")
+    writePromises.push(
+      writeLocalesFile(savePath, locale, namespace, keys)
+    )
+  }
+  
+  await Promise.all(writePromises)
+  const writeTime = performance.now() - writeStartTime
+  log(`⏱️  File I/O (write) completed in ${writeTime.toFixed(2)}ms`)
+
+  const totalTime = performance.now() - startTime
+  log(`✅ Batch operation completed in ${totalTime.toFixed(2)}ms (${(totalTime / keys.length).toFixed(2)}ms per key)`)
+
+  // Build results
+  const results = keys.map(({ key, value, language = "en" }) => {
+    const namespaces = Array.from(keyToNamespaces.get(key) || new Set([defaultNamespace]))
+    const savedLocales = new Set<string>([language])
+    
+    if (openai) {
+      config.locales.forEach(locale => {
+        if (locale !== language) {
+          const translated = translationCache.get(`${language}:${locale}`)
+          if (translated?.[key]) {
+            savedLocales.add(locale)
+          }
+        }
+      })
+    }
+    
+    return {
+      key,
+      value,
+      namespace: namespaces.join(", "),
+      locale: Array.from(savedLocales).sort().join(", "),
+    }
+  })
 
   return {
-    key,
-    value,
-    namespace: affectedNamespaces.join(", "),
-    locale: Array.from(savedLocales).sort().join(", "),
+    results,
+    performance: {
+      totalTime,
+      scanTime,
+      translationTime,
+      fileIOTime: fileIOTime + writeTime,
+    },
   }
 }
+
+export const addTranslationKey = async ({
+  key,
+  value,
+  language = "en",
+  config,
+}: {
+  key: string
+  value: string
+  language?: string
+  config: Configuration
+}) => {
+  const startTime = performance.now()
+  const result = await addTranslationKeys({
+    keys: [{ key, value, language }],
+    config,
+  })
+  const totalTime = performance.now() - startTime
+  
+  const log = console.log
+  log(`⏱️  Single key operation completed in ${totalTime.toFixed(2)}ms`)
+  
+  return result.results[0]
+}

package/src/mcp-server.ts

@@ -5,7 +5,7 @@ import {
   ListToolsRequestSchema,
 } from "@modelcontextprotocol/sdk/types.js"
 import { z } from "zod"
-import { addTranslationKey, getMissingKeys, loadConfig, loadLocalesFile } from "./lib/utils.js"
+import { addTranslationKey, addTranslationKeys, getMissingKeys, loadConfig, loadLocalesFile } from "./lib/utils.js"
 import type { Configuration } from "./lib/types.js"
 import path from "path"
 import fs from "fs"
@@ -71,6 +71,15 @@ const AddTranslationKeySchema = z.object({
   language: z.string().optional().describe("The language code of the provided value (e.g., \"en\", \"de\", \"fr\"). Defaults to \"en\" (English) if not specified."),
 })
 
+// Zod schema for the add_translation_keys (batch) tool parameters
+const AddTranslationKeysSchema = z.object({
+  keys: z.array(z.object({
+    key: z.string().describe("The translation key to add (e.g., \"welcomeMessage\")"),
+    value: z.string().describe("The text value for this translation key"),
+    language: z.string().optional().describe("The language code of the provided value (e.g., \"en\", \"de\", \"fr\"). Defaults to \"en\" (English) if not specified."),
+  })).describe("Array of translation keys to add in batch. Use this for adding multiple keys at once for better performance."),
+})
+
 // Zod schema for the list_untranslated_keys tool parameters
 const ListUntranslatedKeysSchema = z.object({
   namespace: z
@@ -184,7 +193,7 @@ class I18nMagicServer {
         tools: [
           {
             name: "add_translation_key",
-            description:  "Add a new translation key with a text value. You can optionally specify the language of the value you're providing (defaults to English).",
+            description:  "Add a new translation key with a text value. You can optionally specify the language of the value you're providing (defaults to English). For adding multiple keys at once, use add_translation_keys instead for better performance.",
             inputSchema: {
               type: "object",
               properties: {
@@ -207,6 +216,38 @@ class I18nMagicServer {
               required: ["key", "value"],
             },
           },
+          {
+            name: "add_translation_keys",
+            description: "Add multiple translation keys in batch. This is optimized for performance - when adding 2 or more keys, prefer this over multiple add_translation_key calls. It performs a single codebase scan, batches file I/O operations, and batches translations for much better performance.",
+            inputSchema: {
+              type: "object",
+              properties: {
+                keys: {
+                  type: "array",
+                  description: "Array of translation keys to add in batch",
+                  items: {
+                    type: "object",
+                    properties: {
+                      key: {
+                        type: "string",
+                        description: "The translation key to add (e.g., \"welcomeMessage\")",
+                      },
+                      value: {
+                        type: "string",
+                        description: "The text value for this translation key",
+                      },
+                      language: {
+                        type: "string",
+                        description: "The language code of the provided value (e.g., \"en\" for English, \"de\" for German, \"fr\" for French). Defaults to \"en\" if not specified.",
+                      },
+                    },
+                    required: ["key", "value"],
+                  },
+                },
+              },
+              required: ["keys"],
+            },
+          },
           {
             name: "list_untranslated_keys",
             description:
@@ -399,6 +440,131 @@ class I18nMagicServer {
         }
       }
 
+      if (request.params.name === "add_translation_keys") {
+        try {
+          // Validate parameters
+          const params = AddTranslationKeysSchema.parse(request.params.arguments)
+
+          if (!params.keys || params.keys.length === 0) {
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: JSON.stringify(
+                    {
+                      success: false,
+                      error: "No keys provided. The 'keys' array must contain at least one key-value pair.",
+                    },
+                    null,
+                    2,
+                  ),
+                },
+              ],
+              isError: true,
+            }
+          }
+
+          // Ensure config is loaded
+          const config = await this.ensureConfig()
+
+          // Capture console.log output for diagnostics
+          const originalConsoleLog = console.log
+          const logMessages: string[] = []
+          console.log = (...args: any[]) => {
+            const message = args.map(arg => 
+              typeof arg === 'object' ? JSON.stringify(arg) : String(arg)
+            ).join(' ')
+            logMessages.push(message)
+            // Also log to stderr for debugging
+            console.error(`[i18n-magic] ${message}`)
+          }
+
+          let result
+          try {
+            // Add the translation keys in batch
+            result = await addTranslationKeys({
+              keys: params.keys.map(k => ({
+                key: k.key,
+                value: k.value,
+                language: k.language || "en",
+              })),
+              config,
+            })
+          } finally {
+            // Restore console.log
+            console.log = originalConsoleLog
+          }
+
+          return {
+            content: [
+              {
+                type: "text",
+                text: JSON.stringify(
+                  {
+                    success: true,
+                    message: `Successfully added ${result.results.length} translation key(s) in batch`,
+                    results: result.results,
+                    performance: result.performance,
+                    summary: {
+                      totalKeys: result.results.length,
+                      totalTime: `${result.performance.totalTime.toFixed(2)}ms`,
+                      averageTimePerKey: `${(result.performance.totalTime / result.results.length).toFixed(2)}ms`,
+                      scanTime: `${result.performance.scanTime.toFixed(2)}ms`,
+                      translationTime: `${result.performance.translationTime.toFixed(2)}ms`,
+                      fileIOTime: `${result.performance.fileIOTime.toFixed(2)}ms`,
+                    },
+                    diagnostics: logMessages.join('\n'),
+                  },
+                  null,
+                  2,
+                ),
+              },
+            ],
+          }
+        } catch (error) {
+          const errorMessage =
+            error instanceof Error ? error.message : "Unknown error occurred"
+          
+          // Get more detailed error information
+          let errorDetails = errorMessage
+          if (error instanceof Error) {
+            // Check if there's a cause
+            const cause = (error as any).cause
+            if (cause instanceof Error) {
+              errorDetails = `${errorMessage}\nCause: ${cause.message}\nStack: ${cause.stack}`
+            } else if (cause) {
+              errorDetails = `${errorMessage}\nCause: ${JSON.stringify(cause)}`
+            }
+            // Include stack trace
+            if (error.stack) {
+              errorDetails = `${errorDetails}\nStack: ${error.stack}`
+            }
+          }
+          
+          // Log detailed error to stderr for debugging
+          console.error(`[i18n-magic MCP] Error adding translation keys in batch:`)
+          console.error(errorDetails)
+          
+          return {
+            content: [
+              {
+                type: "text",
+                text: JSON.stringify(
+                  {
+                    success: false,
+                    error: errorMessage,
+                    details: errorDetails,
+                  },
+                  null,
+                  2,
+                ),
+              },
+            ],
+            isError: true,
+          }
+        }
+      }
+
       if (request.params.name === "list_untranslated_keys") {
         try {
           // Validate parameters