@scoutello/i18n-magic 0.14.0

package/src/index.ts

@@ -0,0 +1,92 @@
+import { Command } from "commander"
+import dotenv from "dotenv"
+import OpenAI from "openai"
+import { checkMissing } from "./commands/check-missing"
+import { replaceTranslation } from "./commands/replace"
+import { translateMissing } from "./commands/scan"
+import { syncLocales } from "./commands/sync-locales"
+import type { CommandType, Configuration } from "./lib/types"
+import { loadConfig } from "./lib/utils"
+
+// Only run CLI initialization when this file is executed directly
+
+const program = new Command()
+
+program
+  .name("i18n-magic")
+  .description(
+    "CLI to help you manage your locales JSON with translations, replacements, etc. with OpenAI.",
+  )
+  .version("0.2.0")
+  .option("-c, --config <path>", "path to config file")
+  .option("-e, --env <path>", "path to .env file")
+
+const commands: CommandType[] = [
+  {
+    name: "scan",
+    description:
+      "Scan for missing translations, get prompted for each, translate it to the other locales and save it to the JSON file.",
+    action: translateMissing,
+  },
+  {
+    name: "replace",
+    description:
+      "Replace a translation based on the key, and translate it to the other locales and save it to the JSON file.",
+    action: replaceTranslation,
+  },
+  {
+    name: "check-missing",
+    description:
+      "Check if there are any missing translations. Useful for a CI/CD pipeline or husky hook.",
+    action: checkMissing,
+  },
+  {
+    name: "sync",
+    description:
+      "Sync the translations from the default locale to the other locales. Useful for a CI/CD pipeline or husky hook.",
+    action: syncLocales,
+  },
+]
+
+for (const command of commands) {
+  program
+    .command(command.name)
+    .description(command.description)
+    .action(async () => {
+      const res = dotenv.config({
+        path: program.opts().env || ".env",
+      })
+
+      const config: Configuration = await loadConfig({
+        configPath: program.opts().config,
+      })
+
+      const isGemini = (config.model as string)?.includes("gemini")
+
+      // Get API key from environment or config
+      const openaiKey = res.parsed.OPENAI_API_KEY || config.OPENAI_API_KEY
+      const geminiKey = res.parsed.GEMINI_API_KEY || config.GEMINI_API_KEY
+
+      // Select appropriate key based on model type
+      const key = isGemini ? geminiKey : openaiKey
+
+      if (!key) {
+        const keyType = isGemini ? "GEMINI_API_KEY" : "OPENAI_API_KEY"
+        console.error(
+          `Please provide a${isGemini ? " Gemini" : "n OpenAI"} API key in your .env file or config, called ${keyType}.`,
+        )
+        process.exit(1)
+      }
+
+      const openai = new OpenAI({
+        apiKey: key,
+        ...(isGemini && {
+          baseURL: "https://generativelanguage.googleapis.com/v1beta/openai/",
+        }),
+      })
+
+      command.action({ ...config, openai })
+    })
+}
+
+program.parse(process.argv)

package/src/lib/languges.ts

@@ -0,0 +1,142 @@
+export const languages = [
+  {
+    label: "Deutsch",
+    name: "German",
+    value: "de",
+  },
+  {
+    label: "English",
+    name: "English",
+    value: "en",
+  },
+  {
+    label: "Español",
+    name: "Spanish",
+    value: "es",
+  },
+  {
+    label: "Français",
+    name: "French",
+    value: "fr",
+  },
+  {
+    label: "Dansk",
+    name: "Danish",
+    value: "dk",
+  },
+  {
+    label: "中文",
+    name: "Chinese",
+    value: "cn",
+  },
+  {
+    label: "Русский",
+    name: "Russian",
+    value: "ru",
+  },
+  {
+    label: "Italiano",
+    name: "Italian",
+    value: "it",
+  },
+  {
+    label: "Nederlands",
+    name: "Dutch",
+    value: "nl",
+  },
+  {
+    label: "Português",
+    name: "Portuguese",
+    value: "pt",
+  },
+  {
+    label: "Türkçe",
+    name: "Turkish",
+    value: "tr",
+  },
+  {
+    label: "Polski",
+    name: "Polish",
+    value: "pl",
+  },
+  {
+    label: "Українська",
+    name: "Ukrainian",
+    value: "ua",
+  },
+  {
+    label: "Suomi",
+    name: "Finnish",
+    value: "fi",
+  },
+  {
+    label: "Norsk",
+    name: "Norwegian",
+    value: "no",
+  },
+  {
+    label: "Svenska",
+    name: "Swedish",
+    value: "sv",
+  },
+  {
+    label: "Čeština",
+    name: "Czech",
+    value: "cz",
+  },
+  {
+    label: "Ελληνικά",
+    name: "Greek",
+    value: "gr",
+  },
+  {
+    label: "日本語",
+    name: "Japanese",
+    value: "jp",
+  },
+  {
+    label: "한국어",
+    name: "Korean",
+    value: "kr",
+  },
+  {
+    label: "Română",
+    name: "Romanian",
+    value: "ro",
+  },
+  {
+    label: "Hrvatski",
+    name: "Croatian",
+    value: "hr",
+  },
+  {
+    label: "Magyar",
+    name: "Hungarian",
+    value: "hu",
+  },
+  {
+    label: "Slovensky",
+    name: "Slovak",
+    value: "sk",
+  },
+  {
+    label: "हिन्दी",
+    name: "Hindi",
+    value: "hi",
+  },
+  {
+    label: "தமிழ்",
+    name: "Tamil",
+    value: "ta",
+  },
+  {
+    label: "Bahasa Indonesia",
+    name: "Indonesian",
+    value: "id",
+  },
+  {
+    label: "Tiếng Việt",
+    name: "Vietnamese",
+    value: "vn",
+  },
+]

package/src/lib/types.ts

@@ -0,0 +1,38 @@
+import type OpenAI from "openai"
+import type { ChatModel } from "openai/resources/chat/chat"
+
+type Model =
+  | ChatModel
+  | "gemini-2.5-pro-exp-03-25"
+  | "gemini-2.0-flash"
+  | "gemini-2.0-flash-lite"
+
+export interface Configuration {
+  loadPath:
+    | string
+    | ((locale: string, namespace: string) => Promise<Record<string, string>>)
+  savePath:
+    | string
+    | ((
+        locale: string,
+        namespace: string,
+        data: Record<string, string>,
+      ) => Promise<void>)
+  defaultLocale: string
+  defaultNamespace: string
+  namespaces: string[]
+  locales: string[]
+  globPatterns: string[]
+  context?: string
+  disableTranslation?: boolean
+  OPENAI_API_KEY?: string
+  GEMINI_API_KEY?: string
+  model?: Model
+  openai?: OpenAI
+}
+
+export interface CommandType {
+  name: string
+  description: string
+  action: (config: Configuration) => Promise<void>
+}

package/src/lib/utils.ts

@@ -0,0 +1,320 @@
+import glob from "fast-glob"
+import { Parser } from "i18next-scanner"
+import fs from "node:fs"
+import path from "node:path"
+import type OpenAI from "openai"
+import prompts from "prompts"
+import { languages } from "./languges"
+import type { Configuration } from "./types"
+
+export const loadConfig = ({
+  configPath = "i18n-magic.js",
+}: { configPath: string }) => {
+  const filePath = path.join(process.cwd(), configPath)
+
+  if (!fs.existsSync(filePath)) {
+    console.error("Config file does not exist:", filePath)
+    process.exit(1)
+  }
+
+  try {
+    const config = require(filePath)
+    // Validate config if needed
+    return config
+  } catch (error) {
+    console.error("Error while loading config:", error)
+    process.exit(1)
+  }
+}
+
+export function removeDuplicatesFromArray<T>(arr: T[]): T[] {
+  return arr.filter((item, index) => arr.indexOf(item) === index)
+}
+
+export const translateKey = async ({
+  inputLanguage,
+  context,
+  object,
+  openai,
+  outputLanguage,
+  model,
+}: {
+  object: Record<string, string>
+  context: string
+  inputLanguage: string
+  outputLanguage: string
+  model: string
+  openai: OpenAI
+}) => {
+  // Split object into chunks of 100 keys
+  const entries = Object.entries(object)
+  const chunks: Array<[string, string][]> = []
+
+  for (let i = 0; i < entries.length; i += 100) {
+    chunks.push(entries.slice(i, i + 100))
+  }
+
+  let result: Record<string, string> = {}
+
+  const existingInput = languages.find((l) => l.value === inputLanguage)
+  const existingOutput = languages.find((l) => l.value === outputLanguage)
+
+  const input = existingInput?.label || inputLanguage
+  const output = existingOutput?.label || outputLanguage
+
+  // Translate each chunk
+  for (const chunk of chunks) {
+    const chunkObject = Object.fromEntries(chunk)
+    const completion = await openai.beta.chat.completions.parse({
+      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",
+        },
+      ],
+      response_format: {
+        type: "json_object",
+      },
+    })
+
+    const translatedChunk = JSON.parse(
+      completion.choices[0].message.content,
+    ) as Record<string, string>
+
+    // Merge translated chunk with result
+    result = { ...result, ...translatedChunk }
+
+    // Optional: Add a small delay between chunks to avoid rate limiting
+    await new Promise((resolve) => setTimeout(resolve, 100))
+  }
+
+  return result
+}
+
+export const loadLocalesFile = async (
+  loadPath:
+    | string
+    | ((locale: string, namespace: string) => Promise<Record<string, string>>),
+  locale: string,
+  namespace: string,
+) => {
+  if (typeof loadPath === "string") {
+    const resolvedPath = loadPath
+      .replace("{{lng}}", locale)
+      .replace("{{ns}}", namespace)
+
+    const content = fs.readFileSync(resolvedPath, "utf-8")
+    const json = JSON.parse(content)
+
+    return json as Record<string, string>
+  }
+
+  return loadPath(locale, namespace)
+}
+
+export const writeLocalesFile = async (
+  savePath:
+    | string
+    | ((
+        locale: string,
+        namespace: string,
+        data: Record<string, string>,
+      ) => Promise<void>),
+  locale: string,
+  namespace: string,
+  data: Record<string, string>,
+) => {
+  if (typeof savePath === "string") {
+    const resolvedSavePath = savePath
+      .replace("{{lng}}", locale)
+      .replace("{{ns}}", namespace)
+
+    fs.writeFileSync(resolvedSavePath, JSON.stringify(data, null, 2))
+
+    return
+  }
+
+  await savePath(locale, namespace, data)
+}
+
+export const getPureKey = (
+  key: string,
+  namespace?: string,
+  isDefault?: boolean,
+) => {
+  const splitted = key.split(":")
+
+  if (splitted.length === 1) {
+    if (isDefault) {
+      return key
+    }
+
+    return null
+  }
+
+  if (splitted[0] === namespace) {
+    return splitted[1]
+  }
+
+  return null
+}
+
+export const getMissingKeys = async ({
+  globPatterns,
+  namespaces,
+  defaultNamespace,
+  defaultLocale,
+  loadPath,
+}: Configuration) => {
+  const parser = new Parser({
+    nsSeparator: false,
+    keySeparator: false,
+  })
+
+  const files = await glob([...globPatterns, "!**/node_modules/**"])
+
+  const keys = []
+
+  for (const file of files) {
+    const content = fs.readFileSync(file, "utf-8")
+    parser.parseFuncFromString(content, { list: ["t"] }, (key: string) => {
+      keys.push(key)
+    })
+  }
+
+  const uniqueKeys = removeDuplicatesFromArray(keys)
+
+  const newKeys = []
+
+  for (const namespace of namespaces) {
+    const existingKeys = await loadLocalesFile(
+      loadPath,
+      defaultLocale,
+      namespace,
+    )
+
+    console.log(Object.keys(existingKeys).length, "existing keys")
+
+    for (const key of uniqueKeys) {
+      const pureKey = getPureKey(key, namespace, namespace === defaultNamespace)
+
+      if (!pureKey) {
+        continue
+      }
+
+      if (!existingKeys[pureKey]) {
+        newKeys.push({ key: pureKey, namespace })
+      }
+    }
+  }
+
+  return newKeys
+}
+
+export const getTextInput = async (prompt: string) => {
+  const input = await prompts({
+    name: "value",
+    type: "text",
+    message: prompt,
+    onState: (state) => {
+      if (state.aborted) {
+        process.nextTick(() => {
+          process.exit(0)
+        })
+      }
+    },
+  })
+
+  return input.value as string
+}
+
+export const checkAllKeysExist = async ({
+  namespaces,
+  defaultLocale,
+  loadPath,
+  locales,
+  context,
+  openai,
+  savePath,
+  disableTranslation,
+  model,
+}: Configuration) => {
+  if (disableTranslation) {
+    return
+  }
+
+  for (const namespace of namespaces) {
+    const defaultLocaleKeys = await loadLocalesFile(
+      loadPath,
+      defaultLocale,
+      namespace,
+    )
+
+    for (const locale of locales) {
+      if (locale === defaultLocale) continue
+
+      const localeKeys = await loadLocalesFile(loadPath, locale, namespace)
+      const missingKeys: Record<string, string> = {}
+
+      // Check which keys from default locale are missing in current locale
+      for (const [key, value] of Object.entries(defaultLocaleKeys)) {
+        if (!localeKeys[key]) {
+          missingKeys[key] = value
+        }
+      }
+
+      // If there are missing keys, translate them
+      if (Object.keys(missingKeys).length > 0) {
+        console.log(
+          `Found ${Object.keys(missingKeys).length} missing keys in ${locale} (namespace: ${namespace})`,
+        )
+
+        const translatedValues = await translateKey({
+          inputLanguage: defaultLocale,
+          outputLanguage: locale,
+          context,
+          object: missingKeys,
+          openai,
+          model,
+        })
+
+        // Merge translated values with existing ones
+        const updatedLocaleKeys = {
+          ...localeKeys,
+          ...translatedValues,
+        }
+
+        // Save the updated translations
+        writeLocalesFile(savePath, locale, namespace, updatedLocaleKeys)
+        console.log(
+          `✓ Translated and saved missing keys for ${locale} (namespace: ${namespace})`,
+        )
+      }
+    }
+  }
+}
+
+export class TranslationError extends Error {
+  constructor(
+    message: string,
+    public locale?: string,
+    public namespace?: string,
+    public cause?: Error,
+  ) {
+    super(message)
+    this.name = "TranslationError"
+  }
+}