@scoutello/i18n-magic 0.64.0 → 0.66.0

package/src/lib/locale-storage.ts

@@ -0,0 +1,76 @@
+import path from "node:path"
+import type { Configuration } from "./types.js"
+
+export class LocaleConfigurationError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = "LocaleConfigurationError"
+  }
+}
+
+export const resolveConfiguredLocale = (
+  config: Pick<Configuration, "defaultLocale" | "locales">,
+  requested?: string,
+) => {
+  const locale = requested ?? config.defaultLocale
+
+  if (!config.locales.includes(locale)) {
+    throw new LocaleConfigurationError(
+      `Unsupported locale "${locale}". Expected one of: ${config.locales.join(", ")}.`,
+    )
+  }
+
+  return locale
+}
+
+const getConfiguredBasePath = (template: string) => {
+  const placeholderIndexes = [
+    template.indexOf("{{lng}}"),
+    template.indexOf("{{ns}}"),
+  ].filter((index) => index >= 0)
+
+  if (placeholderIndexes.length === 0) {
+    return path.dirname(path.resolve(template))
+  }
+
+  const firstPlaceholder = Math.min(...placeholderIndexes)
+  const staticPrefix = template.slice(0, firstPlaceholder)
+
+  if (
+    staticPrefix.length === 0 ||
+    staticPrefix.endsWith(path.sep) ||
+    staticPrefix.endsWith("/") ||
+    staticPrefix.endsWith("\\")
+  ) {
+    return path.resolve(staticPrefix || ".")
+  }
+
+  return path.dirname(path.resolve(staticPrefix))
+}
+
+export const resolveLocaleTemplatePath = (
+  template: string,
+  locale: string,
+  namespace: string,
+) => {
+  const configuredBase = getConfiguredBasePath(template)
+  const expandedPath = template
+    .split("{{lng}}")
+    .join(locale)
+    .split("{{ns}}")
+    .join(namespace)
+  const resolvedPath = path.resolve(expandedPath)
+  const relativePath = path.relative(configuredBase, resolvedPath)
+
+  if (
+    relativePath === ".." ||
+    relativePath.startsWith(`..${path.sep}`) ||
+    path.isAbsolute(relativePath)
+  ) {
+    throw new LocaleConfigurationError(
+      "Expanded locale path escapes the configured storage base.",
+    )
+  }
+
+  return resolvedPath
+}

package/src/lib/translation-response.ts

@@ -0,0 +1,59 @@
+export class TranslationResponseError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = "TranslationResponseError"
+  }
+}
+
+export class TranslationProviderUnavailableError extends Error {
+  constructor() {
+    super(
+      "A translation provider is required for this operation, but no provider credentials are configured.",
+    )
+    this.name = "TranslationProviderUnavailableError"
+  }
+}
+
+export const parseTranslationResponse = (
+  content: string | null,
+  requestedKeys: string[],
+): Record<string, string> => {
+  let parsed: unknown
+
+  try {
+    parsed = content === null ? null : JSON.parse(content)
+  } catch {
+    throw new TranslationResponseError(
+      "Translation provider returned malformed JSON.",
+    )
+  }
+
+  if (parsed === null || Array.isArray(parsed) || typeof parsed !== "object") {
+    throw new TranslationResponseError(
+      "Translation provider returned a value that is not a JSON object.",
+    )
+  }
+
+  const response = parsed as Record<string, unknown>
+  const requested = new Set(requestedKeys)
+  const responseKeys = Object.keys(response)
+  const missingKeys = requestedKeys.filter((key) => !Object.hasOwn(response, key))
+  const extraKeys = responseKeys.filter((key) => !requested.has(key))
+  const invalidValueKeys = responseKeys.filter(
+    (key) => typeof response[key] !== "string",
+  )
+
+  if (missingKeys.length > 0 || extraKeys.length > 0 || invalidValueKeys.length > 0) {
+    const problems: string[] = []
+    if (missingKeys.length > 0) problems.push(`missing keys: ${missingKeys.join(", ")}`)
+    if (extraKeys.length > 0) problems.push(`extra keys: ${extraKeys.join(", ")}`)
+    if (invalidValueKeys.length > 0) {
+      problems.push(`non-string values: ${invalidValueKeys.join(", ")}`)
+    }
+    throw new TranslationResponseError(
+      `Translation provider returned an invalid key/value shape (${problems.join("; ")}).`,
+    )
+  }
+
+  return response as Record<string, string>
+}

package/src/lib/types.ts

@@ -40,5 +40,5 @@ export interface Configuration {
 export interface CommandType {
   name: string
   description: string
-  action: (config: Configuration, ...args: any[]) => Promise<void>
+  action: (config: Configuration, ...args: any[]) => Promise<unknown>
 }

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