@scoutello/i18n-magic 0.52.0 → 0.54.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 } from "./lib/utils.js"
+import { addTranslationKey, getMissingKeys, loadConfig, loadLocalesFile } from "./lib/utils.js"
 import type { Configuration } from "./lib/types.js"
 import path from "path"
 import fs from "fs"
@@ -67,7 +67,8 @@ function resolveProjectRoot(): string {
 // 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 English text value for this translation key"),
+  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 list_untranslated_keys tool parameters
@@ -80,6 +81,35 @@ const ListUntranslatedKeysSchema = z.object({
     ),
 })
 
+// Zod schema for the get_translation_key tool parameters
+const GetTranslationKeySchema = z.object({
+  key: z.string().describe("The translation key to retrieve (e.g., \"welcomeMessage\")"),
+  namespace: z
+    .string()
+    .optional()
+    .describe(
+      "Optional namespace to search in. If not provided, searches in default namespace first, then all namespaces.",
+    ),
+})
+
+// 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."),
+  namespace: z
+    .string()
+    .optional()
+    .describe(
+      "Optional namespace to update. If not provided, updates the key in all namespaces where it exists.",
+    ),
+})
+
+// Zod schema for the search_translations tool parameters
+const SearchTranslationsSchema = z.object({
+  query: z.string().describe("Search term to find in translation keys or values (fuzzy search)"),
+})
+
 class I18nMagicServer {
   private server: Server
   private config: Configuration | null = null
@@ -154,7 +184,7 @@ class I18nMagicServer {
         tools: [
           {
             name: "add_translation_key",
-            description:  "Add a new translation key with an English value.",
+            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).",
             inputSchema: {
               type: "object",
               properties: {
@@ -166,7 +196,12 @@ class I18nMagicServer {
                 value: {
                   type: "string",
                   description:
-                    "The English text value for this translation key",
+                    "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"],
@@ -188,6 +223,74 @@ class I18nMagicServer {
               required: [],
             },
           },
+          {
+            name: "get_translation_key",
+            description:
+              "Retrieve the English value for a specific translation key. This tool searches for the key in the locale files and always returns the English translation if it exists.",
+            inputSchema: {
+              type: "object",
+              properties: {
+                key: {
+                  type: "string",
+                  description:
+                    "The translation key to retrieve (e.g., \"welcomeMessage\")",
+                },
+                namespace: {
+                  type: "string",
+                  description:
+                    "Optional namespace to search in. If not provided, searches in default namespace first, then all namespaces.",
+                },
+              },
+              required: ["key"],
+            },
+          },
+          {
+            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) and all namespaces where the key 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.",
+            inputSchema: {
+              type: "object",
+              properties: {
+                key: {
+                  type: "string",
+                  description:
+                    "The translation key to update (e.g., \"welcomeMessage\")",
+                },
+                value: {
+                  type: "string",
+                  description:
+                    "The new 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.",
+                },
+                namespace: {
+                  type: "string",
+                  description:
+                    "Optional namespace to update. If not provided, updates the key in all namespaces where it exists.",
+                },
+              },
+              required: ["key", "value"],
+            },
+          },
+          {
+            name: "search_translations",
+            description:
+              "Search for translations by keyword or phrase across ALL namespaces. This tool performs fuzzy search across both translation keys AND their English values, making it perfect for finding existing translations before adding new ones. Use this to: 1) Check if similar text already exists to avoid duplicates, 2) Find the key name when you only remember part of the text, 3) Discover related translations. Always returns the key name AND English value for each result.",
+            inputSchema: {
+              type: "object",
+              properties: {
+                query: {
+                  type: "string",
+                  description:
+                    "Search term to find in translation keys or values (e.g., 'password', 'welcome', 'click'). Fuzzy search - doesn't need to be exact. Searches across all namespaces.",
+                },
+              },
+              required: ["query"],
+            },
+          },
         ],
       }
     })
@@ -220,6 +323,7 @@ class I18nMagicServer {
             result = await addTranslationKey({
               key: params.key,
               value: params.value,
+              language: params.language || "en",
               config,
             })
           } finally {
@@ -234,14 +338,15 @@ class I18nMagicServer {
                 text: JSON.stringify(
                   {
                     success: true,
-                    message: `Successfully added translation key "${result.key}" to affected namespaces: ${result.namespace} (${result.locale})`,
+                    message: `Successfully added translation key "${result.key}" to affected namespaces: ${result.namespace} (locales: ${result.locale})`,
                     key: result.key,
                     value: result.value,
+                    providedLanguage: params.language || "en",
                     namespace: result.namespace,
-                    locale: result.locale,
+                    locales: result.locale,
                     nextStep: result.locale.includes(',')
-                      ? "Run 'i18n-magic sync' to translate this key to other locales"
-                      : "Key was translated to default locale. Run 'i18n-magic sync' to translate to other locales",
+                      ? "Key was automatically translated to multiple locales"
+                      : "Run 'i18n-magic sync' to translate this key to other locales",
                     diagnostics: logMessages.join('\n'),
                   },
                   null,
@@ -396,6 +501,433 @@ class I18nMagicServer {
         }
       }
 
+      if (request.params.name === "get_translation_key") {
+        try {
+          // Validate parameters
+          const params = GetTranslationKeySchema.parse(
+            request.params.arguments,
+          )
+
+          // Ensure config is loaded
+          const config = await this.ensureConfig()
+
+          // Suppress console.log to prevent interference with MCP JSON protocol
+          const originalConsoleLog = console.log
+          console.log = () => {}
+
+          let foundValue: string | null = null
+          let foundNamespace: string | null = null
+
+          try {
+            // If namespace is specified, only check that namespace
+            if (params.namespace) {
+              const keys = await loadLocalesFile(config.loadPath, "en", params.namespace)
+              if (keys[params.key]) {
+                foundValue = keys[params.key]
+                foundNamespace = params.namespace
+              }
+            } else {
+              // Try default namespace first
+              try {
+                const keys = await loadLocalesFile(config.loadPath, "en", config.defaultNamespace)
+                if (keys[params.key]) {
+                  foundValue = keys[params.key]
+                  foundNamespace = config.defaultNamespace
+                }
+              } catch (error) {
+                // Default namespace file doesn't exist or has issues, continue to search other namespaces
+              }
+
+              // If not found in default namespace, search all other namespaces
+              if (!foundValue) {
+                for (const namespace of config.namespaces) {
+                  if (namespace === config.defaultNamespace) continue // Already checked
+                  
+                  try {
+                    const keys = await loadLocalesFile(config.loadPath, "en", namespace)
+                    if (keys[params.key]) {
+                      foundValue = keys[params.key]
+                      foundNamespace = namespace
+                      break
+                    }
+                  } catch (error) {
+                    // Namespace file doesn't exist or has issues, continue
+                  }
+                }
+              }
+            }
+          } finally {
+            // Restore console.log
+            console.log = originalConsoleLog
+          }
+
+          if (foundValue) {
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: JSON.stringify(
+                    {
+                      success: true,
+                      key: params.key,
+                      value: foundValue,
+                      namespace: foundNamespace,
+                      locale: "en",
+                    },
+                    null,
+                    2,
+                  ),
+                },
+              ],
+            }
+          } else {
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: JSON.stringify(
+                    {
+                      success: false,
+                      error: `Translation key "${params.key}" not found in English locale${params.namespace ? ` (namespace: ${params.namespace})` : ""}`,
+                      key: params.key,
+                      searchedNamespace: params.namespace || "all namespaces",
+                      suggestion: "Use list_untranslated_keys to see all missing keys or add_translation_key to add this key",
+                    },
+                    null,
+                    2,
+                  ),
+                },
+              ],
+              isError: false,
+            }
+          }
+        } catch (error) {
+          const errorMessage =
+            error instanceof Error ? error.message : "Unknown error occurred"
+
+          // Get more detailed error information
+          let errorDetails = errorMessage
+          if (error instanceof Error) {
+            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)}`
+            }
+            if (error.stack) {
+              errorDetails = `${errorDetails}\nStack: ${error.stack}`
+            }
+          }
+
+          // Log detailed error to stderr for debugging
+          console.error(`[i18n-magic MCP] Error getting translation key:`)
+          console.error(errorDetails)
+
+          return {
+            content: [
+              {
+                type: "text",
+                text: JSON.stringify(
+                  {
+                    success: false,
+                    error: errorMessage,
+                    details: errorDetails,
+                  },
+                  null,
+                  2,
+                ),
+              },
+            ],
+            isError: true,
+          }
+        }
+      }
+
+      if (request.params.name === "update_translation_key") {
+        try {
+          // Validate parameters
+          const params = UpdateTranslationKeySchema.parse(
+            request.params.arguments,
+          )
+
+          // Ensure config is loaded
+          const config = await this.ensureConfig()
+
+          // Suppress console.log to prevent interference with MCP JSON protocol
+          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)
+            console.error(`[i18n-magic] ${message}`)
+          }
+
+          try {
+            // Find which namespaces contain this key
+            const targetNamespaces: string[] = []
+            
+            if (params.namespace) {
+              // Check if key exists in specified namespace
+              const keys = await loadLocalesFile(config.loadPath, "en", params.namespace)
+              if (keys[params.key]) {
+                targetNamespaces.push(params.namespace)
+              } else {
+                throw new Error(`Key "${params.key}" does not exist in namespace "${params.namespace}"`)
+              }
+            } else {
+              // Find all namespaces where this key exists
+              for (const namespace of config.namespaces) {
+                try {
+                  const keys = await loadLocalesFile(config.loadPath, "en", namespace)
+                  if (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 any namespace. 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
+            await Promise.all(
+              targetNamespaces.flatMap((namespace) =>
+                config.locales.map(async (locale) => {
+                  const newValue = translationCache[locale] || params.value
+                  const existingKeys = await loadLocalesFile(config.loadPath, locale, namespace)
+                  existingKeys[params.key] = newValue
+                  const { writeLocalesFile } = await import("./lib/utils.js")
+                  await writeLocalesFile(config.savePath, locale, namespace, existingKeys)
+                })
+              )
+            )
+
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: JSON.stringify(
+                    {
+                      success: true,
+                      message: `Successfully updated translation key "${params.key}" in ${targetNamespaces.length} namespace(s) and ${config.locales.length} locale(s)`,
+                      key: params.key,
+                      newValue: params.value,
+                      providedLanguage: params.language || "en",
+                      namespaces: targetNamespaces,
+                      locales: config.locales,
+                      diagnostics: logMessages.join('\n'),
+                    },
+                    null,
+                    2,
+                  ),
+                },
+              ],
+            }
+          } finally {
+            // Restore console.log
+            console.log = originalConsoleLog
+          }
+        } catch (error) {
+          const errorMessage =
+            error instanceof Error ? error.message : "Unknown error occurred"
+
+          let errorDetails = errorMessage
+          if (error instanceof Error && error.stack) {
+            errorDetails = `${errorDetails}\nStack: ${error.stack}`
+          }
+
+          console.error(`[i18n-magic MCP] Error updating translation key:`)
+          console.error(errorDetails)
+
+          return {
+            content: [
+              {
+                type: "text",
+                text: JSON.stringify(
+                  {
+                    success: false,
+                    error: errorMessage,
+                    details: errorDetails,
+                  },
+                  null,
+                  2,
+                ),
+              },
+            ],
+            isError: true,
+          }
+        }
+      }
+
+      if (request.params.name === "search_translations") {
+        try {
+          // Validate parameters
+          const params = SearchTranslationsSchema.parse(
+            request.params.arguments,
+          )
+
+          // Ensure config is loaded
+          const config = await this.ensureConfig()
+
+          // Suppress console.log
+          const originalConsoleLog = console.log
+          console.log = () => {}
+
+          try {
+            const searchQuery = params.query.toLowerCase()
+            const results: Array<{
+              key: string
+              value: string
+              namespace: string
+              matchType: "key" | "value" | "both"
+            }> = []
+
+            // Search through all namespaces
+            for (const namespace of config.namespaces) {
+              try {
+                const keys = await loadLocalesFile(config.loadPath, "en", namespace)
+                
+                for (const [key, value] of Object.entries(keys)) {
+                  const keyLower = key.toLowerCase()
+                  const valueLower = value.toLowerCase()
+                  
+                  // Fuzzy matching: check if search query is contained in key or value
+                  const keyMatch = keyLower.includes(searchQuery)
+                  const valueMatch = valueLower.includes(searchQuery)
+                  
+                  if (keyMatch || valueMatch) {
+                    results.push({
+                      key,
+                      value,
+                      namespace,
+                      matchType: keyMatch && valueMatch ? "both" : keyMatch ? "key" : "value",
+                    })
+                  }
+                }
+              } catch (error) {
+                // Namespace file doesn't exist or has issues, continue
+              }
+            }
+
+            // Sort results: exact matches first, then by match type, then alphabetically
+            results.sort((a, b) => {
+              // Prioritize exact key matches
+              const aExactKey = a.key.toLowerCase() === searchQuery
+              const bExactKey = b.key.toLowerCase() === searchQuery
+              if (aExactKey && !bExactKey) return -1
+              if (!aExactKey && bExactKey) return 1
+              
+              // Prioritize exact value matches
+              const aExactValue = a.value.toLowerCase() === searchQuery
+              const bExactValue = b.value.toLowerCase() === searchQuery
+              if (aExactValue && !bExactValue) return -1
+              if (!aExactValue && bExactValue) return 1
+              
+              // Then by match type (both > key > value)
+              const matchOrder = { both: 0, key: 1, value: 2 }
+              const matchCompare = matchOrder[a.matchType] - matchOrder[b.matchType]
+              if (matchCompare !== 0) return matchCompare
+              
+              // Finally alphabetically by key
+              return a.key.localeCompare(b.key)
+            })
+
+            // Limit results to prevent overwhelming output
+            const maxResults = 50
+            const limitedResults = results.slice(0, maxResults)
+            const hasMore = results.length > maxResults
+
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: JSON.stringify(
+                    {
+                      success: true,
+                      message: results.length === 0
+                        ? `No translations found matching "${params.query}"`
+                        : `Found ${results.length} translation${results.length === 1 ? "" : "s"} matching "${params.query}"${hasMore ? ` (showing first ${maxResults})` : ""}`,
+                      query: params.query,
+                      totalResults: results.length,
+                      results: limitedResults,
+                      hasMore,
+                      tip: "Each result shows the translation key, English value, namespace, and what matched (key, value, or both). Use these keys directly in your code or use get_translation_key for more details.",
+                    },
+                    null,
+                    2,
+                  ),
+                },
+              ],
+            }
+          } finally {
+            // Restore console.log
+            console.log = originalConsoleLog
+          }
+        } catch (error) {
+          const errorMessage =
+            error instanceof Error ? error.message : "Unknown error occurred"
+
+          let errorDetails = errorMessage
+          if (error instanceof Error && error.stack) {
+            errorDetails = `${errorDetails}\nStack: ${error.stack}`
+          }
+
+          console.error(`[i18n-magic MCP] Error searching translations:`)
+          console.error(errorDetails)
+
+          return {
+            content: [
+              {
+                type: "text",
+                text: JSON.stringify(
+                  {
+                    success: false,
+                    error: errorMessage,
+                    details: errorDetails,
+                  },
+                  null,
+                  2,
+                ),
+              },
+            ],
+            isError: true,
+          }
+        }
+      }
+
       throw new Error(`Unknown tool: ${request.params.name}`)
     })
   }