@scoutello/i18n-magic 0.65.0 → 0.66.0

package/src/lib/update-translation-key.ts

@@ -0,0 +1,119 @@
+import type { Configuration } from "./types.js"
+import { resolveConfiguredLocale } from "./locale-storage.js"
+import {
+  loadLocalesFile,
+  translateKey,
+  writeLocalesFile,
+} from "./utils.js"
+
+export interface UpdateTranslationKeyResult {
+  key: string
+  value: string
+  sourceLocale: string
+  targetNamespaces: string[]
+  updatedLocales: string[]
+  pendingLocales: string[]
+}
+
+export const updateTranslationKeyOperation = async ({
+  config,
+  key,
+  value,
+  language,
+}: {
+  config: Configuration
+  key: string
+  value: string
+  language?: string
+}): Promise<UpdateTranslationKeyResult> => {
+  const sourceLocale = resolveConfiguredLocale(config, language)
+  const sourceFiles = await Promise.all(
+    config.namespaces.map(async (namespace) => ({
+      namespace,
+      translations: await loadLocalesFile(
+        config.loadPath,
+        sourceLocale,
+        namespace,
+        { silent: true },
+      ),
+    })),
+  )
+  const targetNamespaces = sourceFiles
+    .filter(({ translations }) => Object.hasOwn(translations, key))
+    .map(({ namespace }) => namespace)
+
+  if (targetNamespaces.length === 0) {
+    throw new Error(
+      `Key "${key}" does not exist in the ${sourceLocale} translation files. Use add_translation_key to create it.`,
+    )
+  }
+
+  const pendingLocales = config.openai
+    ? []
+    : config.locales.filter((locale) => locale !== sourceLocale)
+  const updatedLocales = config.openai ? [...config.locales] : [sourceLocale]
+  const translatedValues: Record<string, string> = {
+    [sourceLocale]: value,
+  }
+
+  if (config.openai) {
+    await Promise.all(
+      config.locales
+        .filter((locale) => locale !== sourceLocale)
+        .map(async (locale) => {
+          const translation = await translateKey({
+            context: config.context || "",
+            inputLanguage: sourceLocale,
+            outputLanguage: locale,
+            object: { [key]: value },
+            openai: config.openai,
+            model: config.model,
+          })
+          translatedValues[locale] = translation[key]
+        }),
+    )
+  }
+
+  const snapshots = new Map<string, Record<string, string>>()
+  await Promise.all(
+    updatedLocales.flatMap((locale) =>
+      targetNamespaces.map(async (namespace) => {
+        const sourceSnapshot =
+          locale === sourceLocale
+            ? sourceFiles.find((entry) => entry.namespace === namespace)
+                ?.translations
+            : undefined
+        const existingKeys =
+          sourceSnapshot ??
+          (await loadLocalesFile(config.loadPath, locale, namespace, {
+            silent: true,
+          }))
+        snapshots.set(
+          JSON.stringify([locale, namespace]),
+          { ...existingKeys, [key]: translatedValues[locale] },
+        )
+      }),
+    ),
+  )
+
+  for (const locale of updatedLocales) {
+    for (const namespace of targetNamespaces) {
+      const snapshot = snapshots.get(JSON.stringify([locale, namespace]))
+      if (!snapshot) {
+        throw new Error(
+          `Internal error: no staged snapshot for ${locale}/${namespace}.`,
+        )
+      }
+      await writeLocalesFile(config.savePath, locale, namespace, snapshot)
+    }
+  }
+
+  return {
+    key,
+    value,
+    sourceLocale,
+    targetNamespaces,
+    updatedLocales,
+    pendingLocales,
+  }
+}

package/src/lib/utils.ts

@@ -7,6 +7,15 @@ import { minimatch } from "minimatch"
 import type OpenAI from "openai"
 import prompts from "prompts"
 import { languages } from "./languges.js"
+import {
+  resolveConfiguredLocale,
+  resolveLocaleTemplatePath,
+} from "./locale-storage.js"
+import {
+  parseTranslationResponse,
+  TranslationProviderUnavailableError,
+  TranslationResponseError,
+} from "./translation-response.js"
 import type { Configuration, GlobPatternConfig } from "./types.js"
 
 export const loadConfig = async ({
@@ -17,8 +26,7 @@ export const loadConfig = async ({
   const filePath = path.join(process.cwd(), configPath)
 
   if (!fs.existsSync(filePath)) {
-    console.error("Config file does not exist:", filePath)
-    process.exit(1)
+    throw new Error(`Config file does not exist: ${filePath}`)
   }
 
   try {
@@ -33,32 +41,10 @@ export const loadConfig = async ({
       errorMessage.includes("MODULE_NOT_FOUND") ||
       errorMessage.includes("Cannot find module")
 
-    console.error("Error while loading config:", error)
-
-    if (isModuleNotFound) {
-      console.error("\n💡 Tip: This error usually occurs when:")
-      console.error(
-        "   1. Your config file imports dependencies that aren't installed",
-      )
-      console.error(
-        "   2. Dependencies are installed but have missing peer dependencies",
-      )
-      console.error(
-        "   3. You're using a custom storage solution (e.g., AWS S3) without proper dependencies",
-      )
-      console.error("\n   To fix:")
-      console.error(
-        "   - Check if your config file imports any external packages",
-      )
-      console.error(
-        "   - Ensure all dependencies are properly installed: pnpm install",
-      )
-      console.error(
-        "   - If using AWS SDK, ensure all @smithy/* peer dependencies are installed",
-      )
-    }
-
-    process.exit(1)
+    const hint = isModuleNotFound
+      ? " Check the config imports and installed dependencies."
+      : ""
+    throw new Error(`Error while loading config: ${errorMessage}.${hint}`)
   }
 }
 
@@ -109,6 +95,8 @@ export const translateKey = async ({
 }) => {
   // Split object into chunks of 100 keys
   const entries = Object.entries(object)
+  if (entries.length === 0) return {}
+  if (!openai) throw new TranslationProviderUnavailableError()
   const chunks: Array<[string, string][]> = []
 
   for (let i = 0; i < entries.length; i += 100) {
@@ -129,34 +117,57 @@ export const translateKey = async ({
 
   for (const chunk of chunks) {
     const chunkObject = Object.fromEntries(chunk)
-    const completion = await openai.chat.completions.create({
-      model,
-      messages: [
-        {
-          content: `You are a bot that translates the values of a locales JSON. ${
-            context
-              ? `The user provided some additional context or guidelines about what to fill in the blanks: "${context}". `
-              : ""
-          }The user provides you a JSON with a field named "inputLanguage", which defines the language the values of the JSON are defined in. It also has a field named "outputLanguage", which defines the language you should translate the values to. The last field is named "data", which includes the object with the values to translate. The keys of the values should never be changed. You output only a JSON, which has the same keys as the input, but with translated values. I give you an example input: {"inputLanguage": "English", outputLanguage: "German", "keys": {"hello": "Hello", "world": "World"}}. The output should be {"hello": "Hallo", "world": "Welt"}.`,
-          role: "system",
-        },
-        {
-          content: JSON.stringify({
-            inputLanguage: input,
-            outputLanguage: output,
-            data: chunkObject,
-          }),
-          role: "user",
+    const requestedKeys = chunk.map(([key]) => key)
+    let translatedChunk: Record<string, string> | undefined
+
+    for (let attempt = 0; attempt < 2; attempt++) {
+      const correctivePrompt =
+        attempt === 1
+          ? ` The previous response was invalid. Return exactly these keys with string values and no additional keys: ${JSON.stringify(requestedKeys)}.`
+          : ""
+      const completion = await openai.chat.completions.create({
+        model,
+        messages: [
+          {
+            content: `You are a bot that translates the values of a locales JSON. ${
+              context
+                ? `The user provided some additional context or guidelines about what to fill in the blanks: "${context}". `
+                : ""
+            }The user provides you a JSON with a field named "inputLanguage", which defines the language the values of the JSON are defined in. It also has a field named "outputLanguage", which defines the language you should translate the values to. The last field is named "data", which includes the object with the values to translate. The keys of the values should never be changed. You output only a JSON, which has the same keys as the input, but with translated values. I give you an example input: {"inputLanguage": "English", outputLanguage: "German", "keys": {"hello": "Hello", "world": "World"}}. The output should be {"hello": "Hallo", "world": "Welt"}.${correctivePrompt}`,
+            role: "system",
+          },
+          {
+            content: JSON.stringify({
+              inputLanguage: input,
+              outputLanguage: output,
+              data: chunkObject,
+            }),
+            role: "user",
+          },
+        ],
+        response_format: {
+          type: "json_object",
         },
-      ],
-      response_format: {
-        type: "json_object",
-      },
-    })
+      })
 
-    const translatedChunk = JSON.parse(
-      completion.choices[0].message.content,
-    ) as Record<string, string>
+      try {
+        translatedChunk = parseTranslationResponse(
+          completion.choices[0]?.message.content ?? null,
+          requestedKeys,
+        )
+        break
+      } catch (error) {
+        if (!(error instanceof TranslationResponseError) || attempt === 1) {
+          throw error
+        }
+      }
+    }
+
+    if (!translatedChunk) {
+      throw new TranslationResponseError(
+        "Translation provider did not return a valid response.",
+      )
+    }
 
     // Merge translated chunk with result
     result = { ...result, ...translatedChunk }
@@ -185,9 +196,7 @@ export const loadLocalesFile = async (
   const silent = options?.silent ?? false
 
   if (typeof loadPath === "string") {
-    const resolvedPath = loadPath
-      .replace("{{lng}}", locale)
-      .replace("{{ns}}", namespace)
+    const resolvedPath = resolveLocaleTemplatePath(loadPath, locale, namespace)
 
     // Check if file exists, return empty object if it doesn't
     if (!fs.existsSync(resolvedPath)) {
@@ -227,9 +236,11 @@ export const writeLocalesFile = async (
   data: Record<string, string>,
 ) => {
   if (typeof savePath === "string") {
-    const resolvedSavePath = savePath
-      .replace("{{lng}}", locale)
-      .replace("{{ns}}", namespace)
+    const resolvedSavePath = resolveLocaleTemplatePath(
+      savePath,
+      locale,
+      namespace,
+    )
 
     // Ensure directory exists
     const dir = path.dirname(resolvedSavePath)
@@ -876,6 +887,12 @@ export const addTranslationKeys = async ({
     }
   }
 
+  const validatedKeys = keys.map(({ key, value, language }) => ({
+    key,
+    value,
+    language: resolveConfiguredLocale(config, language),
+  }))
+
   const log = console.log
   const namespaceResolutionDebug =
     process.env.DEBUG_NAMESPACE_RESOLUTION === "1" ||
@@ -923,7 +940,7 @@ export const addTranslationKeys = async ({
     }),
   )
 
-  const preparedKeys = keys.map(({ key, value, language = "en" }) => {
+  const preparedKeys = validatedKeys.map(({ key, value, language }) => {
     const splitKey = key.split(":")
     const hasNamespacedKey = splitKey.length > 1 && namespaces.includes(splitKey[0])
     const normalizedKey = hasNamespacedKey ? splitKey.slice(1).join(":") : key
@@ -1029,6 +1046,7 @@ export const addTranslationKeys = async ({
   const fileIOStartTime = performance.now()
   const localeFiles = new Map<string, Record<string, string>>()
   const originalKeyCounts = new Map<string, number>()
+  const changedFiles = new Set<string>()
   const loadErrors: Array<{ fileKey: string; error: string }> = []
 
   // Load files for all locales × all affected namespaces in parallel (read-only)
@@ -1076,6 +1094,7 @@ export const addTranslationKeys = async ({
     }
 
     localeFiles.set(fileKey, existingKeys)
+    changedFiles.add(fileKey)
   }
 
   // Step 7: Batch translate if OpenAI is configured
@@ -1119,18 +1138,12 @@ export const addTranslationKeys = async ({
             object: keysToTranslate,
             openai,
             model,
-          })
-            .then((translated) => {
-              translationCache.set(
-                `${inputLanguage}:${targetLocale}`,
-                translated,
-              )
-            })
-            .catch((error) => {
-              log(
-                `⚠️  Failed to translate ${keyValues.length} key(s) from ${inputLanguage} to ${targetLocale}: ${error instanceof Error ? error.message : "Unknown error"}`,
-              )
-            }),
+          }).then((translated) => {
+            translationCache.set(
+              `${inputLanguage}:${targetLocale}`,
+              translated,
+            )
+          }),
         )
       }
     }
@@ -1148,7 +1161,7 @@ export const addTranslationKeys = async ({
         if (!translated) continue
 
         for (const { key, namespaces } of keyValues) {
-          if (translated[key]) {
+          if (Object.hasOwn(translated, key)) {
             for (const namespace of namespaces) {
               const fileKey = `${targetLocale}:${namespace}`
               // File MUST already be loaded from step 5 - if not, something went wrong
@@ -1160,6 +1173,7 @@ export const addTranslationKeys = async ({
               }
               // Merge translated key with existing keys (don't overwrite the whole file)
               localeFiles.get(fileKey)![key] = translated[key]
+              changedFiles.add(fileKey)
             }
           }
         }
@@ -1191,6 +1205,7 @@ export const addTranslationKeys = async ({
 
   // All validations passed, now write files sequentially to avoid race conditions
   for (const [fileKey, keys] of localeFiles) {
+    if (!changedFiles.has(fileKey)) continue
     const [locale, namespace] = fileKey.split(":")
     await writeLocalesFile(savePath, locale, namespace, keys)
   }
@@ -1212,7 +1227,7 @@ export const addTranslationKeys = async ({
       config.locales.forEach((locale) => {
         if (locale !== language) {
           const translated = translationCache.get(`${language}:${locale}`)
-          if (translated?.[key]) {
+          if (translated && Object.hasOwn(translated, key)) {
             savedLocales.add(locale)
           }
         }
@@ -1222,6 +1237,7 @@ export const addTranslationKeys = async ({
     return {
       key,
       value,
+      providedLanguage: language,
       namespace: resolvedNamespaces.join(", "),
       locale: Array.from(savedLocales).sort().join(", "),
     }
@@ -1241,7 +1257,7 @@ export const addTranslationKeys = async ({
 export const addTranslationKey = async ({
   key,
   value,
-  language = "en",
+  language,
   config,
 }: {
   key: string

package/src/mcp-server.ts

@@ -10,6 +10,7 @@ import path from "path"
 import { fileURLToPath } from "url"
 import { z } from "zod"
 import type { Configuration } from "./lib/types.js"
+import { updateTranslationKeyOperation } from "./lib/update-translation-key.js"
 import {
   addTranslationKey,
   addTranslationKeys,
@@ -162,7 +163,7 @@ const AddTranslationKeySchema = z.object({
     .string()
     .optional()
     .describe(
-      'The language code of the provided value (e.g., "en", "de", "fr"). Defaults to "en" (English) if not specified.',
+      "The configured language code of the provided value. Defaults to config.defaultLocale if not specified.",
     ),
 })
 
@@ -181,7 +182,7 @@ const AddTranslationKeysSchema = z.object({
           .string()
           .optional()
           .describe(
-            'The language code of the provided value (e.g., "en", "de", "fr"). Defaults to "en" (English) if not specified.',
+            "The configured language code of the provided value. Defaults to config.defaultLocale if not specified.",
           ),
       }),
     )
@@ -210,7 +211,7 @@ const UpdateTranslationKeySchema = z.object({
     .string()
     .optional()
     .describe(
-      'The language code of the provided value (e.g., "en", "de", "fr"). Defaults to "en" (English) if not specified.',
+      "The configured language code of the provided value. Defaults to config.defaultLocale if not specified.",
     ),
 })
 
@@ -299,7 +300,7 @@ class I18nMagicServer {
           {
             name: "add_translation_key",
             description:
-              "Add a new translation key with a text value. The destination translation file is resolved automatically from project configuration and code usage. 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. NOTE: This tool can only ADD keys, it will NEVER remove any existing keys.",
+              "Add a new translation key with a text value. The destination translation file is resolved automatically from project configuration and code usage. The language defaults to the configured defaultLocale. For adding multiple keys at once, use add_translation_keys instead for better performance. NOTE: This tool can only ADD keys, it will NEVER remove any existing keys.",
             inputSchema: {
               type: "object",
               properties: {
@@ -315,7 +316,7 @@ class I18nMagicServer {
                 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.',
+                    "The configured language code of the provided value. Defaults to config.defaultLocale if not specified.",
                 },
               },
               required: ["key", "value"],
@@ -346,7 +347,7 @@ class I18nMagicServer {
                       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.',
+                          "The configured language code of the provided value. Defaults to config.defaultLocale if not specified.",
                       },
                     },
                     required: ["key", "value"],
@@ -385,7 +386,7 @@ class I18nMagicServer {
           {
             name: "update_translation_key",
             description:
-              "Update an existing translation key with a new text value. You can optionally specify the language of the value you're providing (defaults to English). This will update the key across all locales (translating automatically to other languages) everywhere it exists. Use this when you need to fix typos, improve wording, or change the text of an existing translation. If you're not sure if a key exists, use get_translation_key or search_translations first. NOTE: This tool can only UPDATE existing keys, it will NEVER remove any keys.",
+              "Update an existing translation key with a new text value. The language defaults to the configured defaultLocale. With a provider, every locale is translated before writes begin. Without a provider, only the supplied/default locale is updated and other locales are returned as pending. NOTE: This tool can only UPDATE existing keys, it will NEVER remove any keys.",
             inputSchema: {
               type: "object",
               properties: {
@@ -401,7 +402,7 @@ class I18nMagicServer {
                 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.',
+                    "The configured language code of the provided value. Defaults to config.defaultLocale if not specified.",
                 },
               },
               required: ["key", "value"],
@@ -448,7 +449,7 @@ class I18nMagicServer {
               return await addTranslationKey({
                 key: params.key,
                 value: params.value,
-                language: params.language || "en",
+                language: params.language,
                 config,
               })
             })
@@ -467,7 +468,7 @@ class I18nMagicServer {
                     message: `Successfully added translation key "${result.key}"`,
                     key: result.key,
                     value: result.value,
-                    providedLanguage: params.language || "en",
+                    providedLanguage: result.providedLanguage,
                     locales: result.locale,
                     nextStep: result.locale.includes(",")
                       ? "Key was automatically translated to multiple locales"
@@ -564,7 +565,7 @@ class I18nMagicServer {
                 keys: params.keys.map((k) => ({
                   key: k.key,
                   value: k.value,
-                  language: k.language || "en",
+                  language: k.language,
                 })),
                 config,
               })
@@ -892,102 +893,14 @@ class I18nMagicServer {
           console.log = () => {}
 
           try {
-            // Use mutex to prevent concurrent writes
-            await translationMutex.withLock(async () => {
-              // Find which namespaces contain this key
-              const targetNamespaces: string[] = []
-
-              // Find all namespaces where this key exists
-              for (const namespace of config.namespaces) {
-                try {
-                  const keys = await loadLocalesFile(
-                    config.loadPath,
-                    "en",
-                    namespace,
-                  )
-                  if (Object.hasOwn(keys, params.key)) {
-                    targetNamespaces.push(namespace)
-                  }
-                } catch (error) {
-                  // Namespace file doesn't exist, continue
-                }
-              }
-
-              if (targetNamespaces.length === 0) {
-                throw new Error(
-                  `Key "${params.key}" does not exist in translation files. Use add_translation_key to create it.`,
-                )
-              }
-
-              // Build translation cache with new value
-              const inputLanguage = params.language || "en"
-              const translationCache: Record<string, string> = {
-                [inputLanguage]: params.value,
-              }
-
-              // Translate to all other locales
-              const otherLocales = config.locales.filter(
-                (l) => l !== inputLanguage,
-              )
-              if (otherLocales.length > 0 && config.openai) {
-                const { translateKey } = await import("./lib/utils.js")
-
-                await Promise.all(
-                  otherLocales.map(async (locale) => {
-                    const translation = await translateKey({
-                      context: config.context || "",
-                      inputLanguage: inputLanguage,
-                      outputLanguage: locale,
-                      object: {
-                        [params.key]: params.value,
-                      },
-                      openai: config.openai!,
-                      model: config.model,
-                    })
-                    translationCache[locale] = translation[params.key]
-                  }),
-                )
-              }
-
-              // Update the key in all relevant namespaces and locales
-              // Process sequentially to avoid race conditions
-              const { writeLocalesFile } = await import("./lib/utils.js")
-
-              for (const namespace of targetNamespaces) {
-                for (const locale of config.locales) {
-                  const newValue = translationCache[locale] || params.value
-
-                  // Load existing keys
-                  const existingKeys = await loadLocalesFile(
-                    config.loadPath,
-                    locale,
-                    namespace,
-                  )
-
-                  const originalKeyCount = Object.keys(existingKeys).length
-
-                  // Update the specific key
-                  existingKeys[params.key] = newValue
-
-                  const newKeyCount = Object.keys(existingKeys).length
-
-                  // Safety check: we should only be updating, not removing
-                  // Key count should stay same (update) or increase by 1 (add)
-                  if (newKeyCount < originalKeyCount) {
-                    throw new Error(
-                      `Safety check failed: Updating locale "${locale}" would reduce keys from ${originalKeyCount} to ${newKeyCount}. Aborting.`,
-                    )
-                  }
-
-                  await writeLocalesFile(
-                    config.savePath,
-                    locale,
-                    namespace,
-                    existingKeys,
-                  )
-                }
-              }
-            })
+            const result = await translationMutex.withLock(async () =>
+              updateTranslationKeyOperation({
+                config,
+                key: params.key,
+                value: params.value,
+                language: params.language,
+              }),
+            )
 
             return {
               content: [
@@ -996,11 +909,17 @@ class I18nMagicServer {
                   text: JSON.stringify(
                     {
                       success: true,
-                      message: `Successfully updated translation key "${params.key}" in ${config.locales.length} locale(s)`,
-                      key: params.key,
-                      newValue: params.value,
-                      providedLanguage: params.language || "en",
-                      locales: config.locales,
+                      message: `Successfully updated translation key "${result.key}" in ${result.updatedLocales.length} locale(s)`,
+                      key: result.key,
+                      newValue: result.value,
+                      providedLanguage: result.sourceLocale,
+                      updatedLocales: result.updatedLocales,
+                      pendingLocales: result.pendingLocales,
+                      locales: result.updatedLocales,
+                      nextStep:
+                        result.pendingLocales.length > 0
+                          ? "Run 'i18n-magic sync' with a configured provider to translate pending locales."
+                          : "All configured locales were updated.",
                     },
                     null,
                     2,