@scoutello/i18n-magic 0.65.0 → 0.67.0

package/src/mcp-server.ts

@@ -9,7 +9,14 @@ import OpenAI from "openai"
 import path from "path"
 import { fileURLToPath } from "url"
 import { z } from "zod"
+import {
+  AddTranslationKeySchema,
+  AddTranslationKeysSchema,
+  MCP_WRITE_REQUIRED_FIELDS,
+  UpdateTranslationKeySchema,
+} from "./lib/mcp-write-schemas.js"
 import type { Configuration } from "./lib/types.js"
+import { updateTranslationKeyOperation } from "./lib/update-translation-key.js"
 import {
   addTranslationKey,
   addTranslationKeys,
@@ -150,46 +157,6 @@ function resolveProjectRoot(): string {
   return cwd
 }
 
-// Zod schema for the add_translation_key tool parameters
-const AddTranslationKeySchema = 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.',
-    ),
-})
-
-// 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({})
 
@@ -200,20 +167,6 @@ const GetTranslationKeySchema = z.object({
     .describe('The translation key to retrieve (e.g., "welcomeMessage")'),
 })
 
-// Zod schema for the update_translation_key tool parameters
-const UpdateTranslationKeySchema = z.object({
-  key: z
-    .string()
-    .describe('The translation key to update (e.g., "welcomeMessage")'),
-  value: z.string().describe("The new 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.',
-    ),
-})
-
 // Zod schema for the search_translations tool parameters
 const SearchTranslationsSchema = z.object({
   query: z
@@ -299,7 +252,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 and its explicit source language. The destination translation file is resolved automatically from project configuration and code usage. 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,10 +268,10 @@ 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.',
+                    "Required configured language code of the provided value (for example, en or de).",
                 },
               },
-              required: ["key", "value"],
+              required: [...MCP_WRITE_REQUIRED_FIELDS],
             },
           },
           {
@@ -346,10 +299,10 @@ 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.',
+                          "Required configured language code of the provided value (for example, en or de).",
                       },
                     },
-                    required: ["key", "value"],
+                    required: [...MCP_WRITE_REQUIRED_FIELDS],
                   },
                 },
               },
@@ -385,7 +338,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 and its explicit source language. With a provider, every locale is translated before writes begin. Without a provider, only the supplied 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,10 +354,10 @@ 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.',
+                    "Required configured language code of the provided value (for example, en or de).",
                 },
               },
-              required: ["key", "value"],
+              required: [...MCP_WRITE_REQUIRED_FIELDS],
             },
           },
           {
@@ -448,7 +401,7 @@ class I18nMagicServer {
               return await addTranslationKey({
                 key: params.key,
                 value: params.value,
-                language: params.language || "en",
+                language: params.language,
                 config,
               })
             })
@@ -467,7 +420,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 +517,7 @@ class I18nMagicServer {
                 keys: params.keys.map((k) => ({
                   key: k.key,
                   value: k.value,
-                  language: k.language || "en",
+                  language: k.language,
                 })),
                 config,
               })
@@ -691,7 +644,7 @@ class I18nMagicServer {
                     nextSteps:
                       missingKeys.length > 0
                         ? [
-                            "Use add_translation_key to add these keys with English values",
+                            "Use add_translation_key with each value and its explicit source language (for example, language: \"en\")",
                             "Or run 'i18n-magic scan' to add them interactively",
                           ]
                         : [],
@@ -892,102 +845,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 +861,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,