@scoutello/i18n-magic 0.65.0 → 0.67.0

package/src/commands/scan.ts

@@ -1,8 +1,7 @@
 import type { Configuration } from "../lib/types.js"
 import {
-  checkAllKeysExist,
-  findExistingTranslations,
-  getMissingKeys,
+  getKeysWithNamespaces,
+  getPureKey,
   getTextInput,
   loadLocalesFile,
   translateKey,
@@ -10,11 +9,15 @@ import {
 } from "../lib/utils.js"
 import { findUnusedKeys, removeUnusedKeys } from "./clean.js"
 
+const fileKey = (locale: string, namespace: string) =>
+  JSON.stringify([locale, namespace])
+
 export const translateMissing = async (config: Configuration) => {
   const {
     loadPath,
     savePath,
     defaultLocale,
+    defaultNamespace,
     namespaces,
     locales,
     context,
@@ -22,138 +25,157 @@ export const translateMissing = async (config: Configuration) => {
     disableTranslationDuringScan,
     autoClear,
   } = config
-
-  if (autoClear) {
-    console.log("🧹 Checking for unused translations before scanning...")
-    const report = await findUnusedKeys(config)
-
-    if (report.unusedCount > 0) {
-      await removeUnusedKeys(config)
-      console.log("")
-    } else {
-      console.log("✅ No unused keys found.\n")
+  const activeLocales = disableTranslationDuringScan
+    ? [defaultLocale]
+    : locales
+  const keysWithNamespaces = await getKeysWithNamespaces({
+    globPatterns: config.globPatterns,
+    defaultNamespace,
+  })
+  const expectedByNamespace = Object.fromEntries(
+    namespaces.map((namespace) => [namespace, new Set<string>()]),
+  ) as Record<string, Set<string>>
+
+  for (const { key, namespaces: keyNamespaces } of keysWithNamespaces) {
+    for (const namespace of keyNamespaces) {
+      if (!expectedByNamespace[namespace]) continue
+      const pureKey = getPureKey(
+        key,
+        namespace,
+        namespace === defaultNamespace,
+      )
+      const expectedKey = pureKey || (!key.includes(":") ? key : null)
+      if (expectedKey !== null) expectedByNamespace[namespace].add(expectedKey)
     }
   }
 
-  const newKeys = await getMissingKeys(config)
-
-  if (newKeys.length === 0) {
-    console.log("No new keys found.")
-
-    await checkAllKeysExist(config)
-
-    return
-  }
-
-  console.log(
-    `${newKeys.length} keys are missing. Please provide the values for the following keys in ${defaultLocale}:`,
-  )
-
-  const newKeysWithDefaultLocale = []
-
-  // Check for existing translations in parallel
-  const keysList = newKeys.map((k) => k.key)
-  const existingTranslationResults = await findExistingTranslations(
-    keysList,
-    namespaces,
-    defaultLocale,
-    loadPath,
+  const stagedFiles = new Map<string, Record<string, string>>()
+  await Promise.all(
+    activeLocales.flatMap((locale) =>
+      namespaces.map(async (namespace) => {
+        const translations = await loadLocalesFile(
+          loadPath,
+          locale,
+          namespace,
+          { silent: true },
+        )
+        stagedFiles.set(fileKey(locale, namespace), { ...translations })
+      }),
+    ),
   )
 
-  const reusedKeys: string[] = []
-  for (const newKey of newKeys) {
-    const existingValue = existingTranslationResults[newKey.key]
-
-    let answer: string
-    // Use explicit null check instead of truthy check to handle empty string values
-    if (existingValue !== null) {
-      reusedKeys.push(newKey.key)
-      answer = existingValue
-    } else {
-      answer = await getTextInput(newKey.key, newKey.namespaces)
+  const changedFiles = new Set<string>()
+  const missingDefaultKeys = new Map<string, Set<string>>()
+  for (const namespace of namespaces) {
+    const translations = stagedFiles.get(fileKey(defaultLocale, namespace))!
+    for (const key of expectedByNamespace[namespace]) {
+      if (!Object.hasOwn(translations, key)) {
+        missingDefaultKeys.get(key)?.add(namespace) ??
+          missingDefaultKeys.set(key, new Set([namespace]))
+      }
     }
-
-    newKeysWithDefaultLocale.push({
-      key: newKey.key,
-      namespace: newKey.namespace,
-      namespaces: newKey.namespaces,
-      value: answer,
-    })
   }
 
-  // Batch log reused keys
-  if (reusedKeys.length > 0) {
+  if (missingDefaultKeys.size > 0) {
     console.log(
-      `🔄 Auto-reused ${reusedKeys.length} existing values from other namespaces`,
+      `${missingDefaultKeys.size} keys are missing. Please provide the values for the following keys in ${defaultLocale}:`,
     )
   }
 
-  const newKeysObject = newKeysWithDefaultLocale.reduce((prev, next) => {
-    prev[next.key] = next.value
+  for (const [key, keyNamespaces] of missingDefaultKeys) {
+    let value: string | undefined
+    for (const namespace of namespaces) {
+      const translations = stagedFiles.get(fileKey(defaultLocale, namespace))!
+      if (Object.hasOwn(translations, key)) {
+        value = translations[key]
+        break
+      }
+    }
 
-    return prev
-  }, {})
+    value ??= await getTextInput(key, Array.from(keyNamespaces))
+    for (const namespace of keyNamespaces) {
+      stagedFiles.get(fileKey(defaultLocale, namespace))![key] = value
+      changedFiles.add(fileKey(defaultLocale, namespace))
+    }
+  }
 
-  const allLocales = disableTranslationDuringScan ? [defaultLocale] : locales
+  await Promise.all(
+    activeLocales
+      .filter((locale) => locale !== defaultLocale)
+      .map(async (locale) => {
+        const missingByKey = new Map<string, Set<string>>()
+        for (const namespace of namespaces) {
+          const translations = stagedFiles.get(fileKey(locale, namespace))!
+          for (const key of expectedByNamespace[namespace]) {
+            if (!Object.hasOwn(translations, key)) {
+              missingByKey.get(key)?.add(namespace) ??
+                missingByKey.set(key, new Set([namespace]))
+            }
+          }
+        }
 
-  // Batch translate for all non-default locales in parallel
-  const translationCache: Record<string, Record<string, string>> = {
-    [defaultLocale]: newKeysObject,
-  }
+        const reused: Record<string, string> = {}
+        const keysToTranslate: Record<string, string> = {}
+        for (const key of missingByKey.keys()) {
+          let existingValue: string | undefined
+          for (const namespace of namespaces) {
+            const translations = stagedFiles.get(fileKey(locale, namespace))!
+            if (Object.hasOwn(translations, key)) {
+              existingValue = translations[key]
+              break
+            }
+          }
+
+          if (existingValue !== undefined) {
+            reused[key] = existingValue
+            continue
+          }
+
+          const sourceNamespace = Array.from(missingByKey.get(key)!)[0]
+          const sourceTranslations = stagedFiles.get(
+            fileKey(defaultLocale, sourceNamespace),
+          )!
+          keysToTranslate[key] = sourceTranslations[key]
+        }
 
-  const nonDefaultLocales = allLocales.filter((l) => l !== defaultLocale)
-  if (nonDefaultLocales.length > 0) {
-    await Promise.all(
-      nonDefaultLocales.map(async (locale) => {
-        const translatedValues = await translateKey({
+        const translated = await translateKey({
           inputLanguage: defaultLocale,
           outputLanguage: locale,
           context,
-          object: newKeysObject,
+          object: keysToTranslate,
           openai,
           model: config.model,
         })
-        translationCache[locale] = translatedValues
-      }),
-    )
-  }
-
-  // Process all locale/namespace combinations in parallel
-  const writeResults: Array<{
-    locale: string
-    namespace: string
-    keyCount: number
-  }> = []
-  await Promise.all(
-    allLocales.flatMap((locale) =>
-      namespaces.map(async (namespace) => {
-        const existingKeys = await loadLocalesFile(loadPath, locale, namespace)
-
-        const relevantKeys = newKeysWithDefaultLocale.filter((key) =>
-          key.namespaces?.includes(namespace),
-        )
-
-        if (relevantKeys.length === 0) {
-          return
-        }
-
-        const translatedValues = translationCache[locale]
-        for (const key of relevantKeys) {
-          existingKeys[key.key] = translatedValues[key.key]
+        const resolvedValues = { ...reused, ...translated }
+
+        for (const [key, keyNamespaces] of missingByKey) {
+          for (const namespace of keyNamespaces) {
+            stagedFiles.get(fileKey(locale, namespace))![key] =
+              resolvedValues[key]
+            changedFiles.add(fileKey(locale, namespace))
+          }
         }
-
-        await writeLocalesFile(savePath, locale, namespace, existingKeys)
-        writeResults.push({ locale, namespace, keyCount: relevantKeys.length })
       }),
-    ),
   )
 
-  // Log where keys were written
-  for (const { locale, namespace, keyCount } of writeResults) {
-    console.log(`   📝 Wrote ${keyCount} key(s) to ${locale}/${namespace}.json`)
+  for (const locale of activeLocales) {
+    for (const namespace of namespaces) {
+      const key = fileKey(locale, namespace)
+      if (!changedFiles.has(key)) continue
+      await writeLocalesFile(savePath, locale, namespace, stagedFiles.get(key)!)
+      console.log(`   📝 Updated ${locale}/${namespace}.json`)
+    }
   }
 
-  await checkAllKeysExist(config)
+  if (autoClear) {
+    console.log("🧹 Checking for unused translations after scanning...")
+    const report = await findUnusedKeys(config)
+    if (report.unusedCount > 0) await removeUnusedKeys(config)
+  }
 
-  console.log(`Successfully translated ${newKeys.length} keys.`)
+  if (changedFiles.size === 0) {
+    console.log("No missing translations found.")
+  } else {
+    console.log(`Successfully updated ${changedFiles.size} locale file(s).`)
+  }
 }

package/src/commands/sync-locales.ts

@@ -1,10 +1,8 @@
-import fs from "node:fs"
 import chalk from "chalk"
 import cliProgress from "cli-progress"
 import { languages } from "../lib/languges.js"
 import type { Configuration } from "../lib/types.js"
 import {
-  findExistingTranslations,
   loadLocalesFile,
   TranslationError,
   translateKey,
@@ -70,6 +68,11 @@ export const syncLocales = async (config: Configuration) => {
     }
   }
 
+  const stagedFiles = new Map<
+    string,
+    { locale: string; namespace: string; translations: Record<string, string> }
+  >()
+
   const progressBars = new cliProgress.MultiBar(
     {
       format: `   {label} {bar} {percentage}% | {value}/{total} | {duration_formatted} | {status}`,
@@ -99,28 +102,6 @@ export const syncLocales = async (config: Configuration) => {
   const suppressedLog = () => {}
 
   try {
-    // Helper to ensure a locale/namespace file exists before we add keys
-    const ensureLocaleNamespaceFile = async (
-      locale: string,
-      namespace: string,
-    ) => {
-      if (typeof savePath === "string") {
-        const filePath = savePath
-          .replace("{{lng}}", locale)
-          .replace("{{ns}}", namespace)
-        if (!fs.existsSync(filePath)) {
-          await writeLocalesFile(savePath, locale, namespace, {})
-        }
-      }
-    }
-
-    // Ensure all default-locale namespace files exist first
-    await Promise.all(
-      namespaces.map((namespace) =>
-        ensureLocaleNamespaceFile(defaultLocale, namespace),
-      ),
-    )
-
     // Process locales in parallel batches
     let completedCount = 0
     const currentlyProcessing: Set<string> = new Set()
@@ -187,13 +168,6 @@ export const syncLocales = async (config: Configuration) => {
       updateProgressDisplay()
 
       try {
-        // Ensure all namespace files for this locale exist
-        await Promise.all(
-          namespaces.map((namespace) =>
-            ensureLocaleNamespaceFile(locale, namespace),
-          ),
-        )
-
         // Collect all missing keys for this locale across all namespaces
         const allMissingKeys: Record<
           string,
@@ -232,7 +206,7 @@ export const syncLocales = async (config: Configuration) => {
           namespaceKeys[namespace] = localeKeys
 
           for (const [key, value] of Object.entries(defaultLocaleKeys)) {
-            if (!localeKeys[key]) {
+            if (!Object.hasOwn(localeKeys, key)) {
               if (allMissingKeys[key]) {
                 allMissingKeys[key].namespaces.push(namespace)
               } else {
@@ -259,18 +233,12 @@ export const syncLocales = async (config: Configuration) => {
         const keysToTranslate: Record<string, string> = {}
         const existingTranslations: Record<string, string> = {}
 
-        const existingTranslationResults = await findExistingTranslations(
-          missingKeysList,
-          namespaces,
-          locale,
-          loadPath,
-          { silent: true },
-        )
-
         for (const key of missingKeysList) {
-          const existingValue = existingTranslationResults[key]
-          if (existingValue !== null) {
-            existingTranslations[key] = existingValue
+          const existingNamespace = namespaces.find((namespace) =>
+            Object.hasOwn(namespaceKeys[namespace], key),
+          )
+          if (existingNamespace !== undefined) {
+            existingTranslations[key] = namespaceKeys[existingNamespace][key]
             localeResults[locale].reused++
           } else {
             keysToTranslate[key] = allMissingKeys[key].value
@@ -319,24 +287,25 @@ export const syncLocales = async (config: Configuration) => {
         // Combine and save
         const allTranslations = { ...existingTranslations, ...translatedValues }
 
-        await Promise.all(
-          namespaces.map(async (namespace) => {
-            let hasChanges = false
-            const updatedKeys = { ...namespaceKeys[namespace] }
-
-            for (const key of missingKeysList) {
-              if (allMissingKeys[key].namespaces.includes(namespace)) {
-                const translation = allTranslations[key] || ""
-                updatedKeys[key] = translation
-                hasChanges = true
-              }
-            }
+        for (const namespace of namespaces) {
+          let hasChanges = false
+          const updatedKeys = { ...namespaceKeys[namespace] }
 
-            if (hasChanges) {
-              await writeLocalesFile(savePath, locale, namespace, updatedKeys)
+          for (const key of missingKeysList) {
+            if (allMissingKeys[key].namespaces.includes(namespace)) {
+              updatedKeys[key] = allTranslations[key]
+              hasChanges = true
             }
-          }),
-        )
+          }
+
+          if (hasChanges) {
+            stagedFiles.set(JSON.stringify([locale, namespace]), {
+              locale,
+              namespace,
+              translations: updatedKeys,
+            })
+          }
+        }
 
         localeResults[locale].status = "done"
         currentlyProcessing.delete(locale)
@@ -366,6 +335,19 @@ export const syncLocales = async (config: Configuration) => {
 
     progressBars.stop()
 
+    const errorLocales = localesToProcess.filter(
+      (locale) => localeResults[locale].status === "error",
+    )
+    if (errorLocales.length > 0) {
+      throw new TranslationError(
+        `Sync failed for ${errorLocales.length} locale(s); no translations were written.`,
+      )
+    }
+
+    for (const { locale, namespace, translations } of stagedFiles.values()) {
+      await writeLocalesFile(savePath, locale, namespace, translations)
+    }
+
     // Print summary
     console.log("")
     console.log(chalk.green("✨ Sync complete!\n"))
@@ -389,10 +371,6 @@ export const syncLocales = async (config: Configuration) => {
     const doneLocales = localesToProcess.filter(
       (l) => localeResults[l].status === "done",
     )
-    const errorLocales = localesToProcess.filter(
-      (l) => localeResults[l].status === "error",
-    )
-
     // Show successful languages in a compact grid
     if (doneLocales.length > 0) {
       const columns = 3

package/src/index.ts

@@ -1,5 +1,10 @@
 // Export command functions for programmatic usage
-export { checkMissing } from "./commands/check-missing.js"
+export {
+  checkMissing,
+  collectMissingTranslations,
+  MissingTranslationsError,
+} from "./commands/check-missing.js"
+export type { MissingTranslationsReport } from "./commands/check-missing.js"
 export { removeUnusedKeys } from "./commands/clean.js"
 
 export { replaceTranslation } from "./commands/replace.js"

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/mcp-write-schemas.ts

@@ -0,0 +1,46 @@
+import { z } from "zod"
+
+const ExplicitSourceLanguageSchema = z
+  .string()
+  .min(1)
+  .describe(
+    "Required configured language code of the provided value (for example, en or de).",
+  )
+
+export const MCP_WRITE_REQUIRED_FIELDS = [
+  "key",
+  "value",
+  "language",
+] as const
+
+export 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: ExplicitSourceLanguageSchema,
+})
+
+export 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: ExplicitSourceLanguageSchema,
+      }),
+    )
+    .describe(
+      "Array of translation keys to add in batch. Use this for adding multiple keys at once for better performance.",
+    ),
+})
+
+export 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: ExplicitSourceLanguageSchema,
+})

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>
 }