feat: manual llm options (#614)

Author: maxprilutskiy

.changeset/fair-books-admire.md

@@ -0,0 +1,6 @@
+---
+"@lingo.dev/_spec": minor
+"lingo.dev": minor
+---
+
+add basic translators

packages/cli/i18n.json

@@ -1,5 +1,10 @@
 {
-  "version": 1.2,
+  "version": 1.5,
+  "provider": {
+    "id": "anthropic",
+    "model": "claude-3-7-sonnet-latest",
+    "prompt": "You're translating text from {source} to {target}."
+  },
   "locale": {
     "source": "en",
     "targets": ["es", "fr", "it", "de", "ar"]

packages/cli/package.json

@@ -57,13 +57,16 @@
   "author": "",
   "license": "Apache-2.0",
   "dependencies": {
+    "@ai-sdk/anthropic": "^1.2.6",
+    "@ai-sdk/openai": "^1.3.7",
     "@datocms/cma-client-node": "^3.4.0",
     "@gitbeaker/rest": "^39.34.3",
     "@inquirer/prompts": "^7.2.3",
     "@lingo.dev/_sdk": "workspace:*",
     "@lingo.dev/_spec": "workspace:*",
     "@modelcontextprotocol/sdk": "^1.5.0",
     "@paralleldrive/cuid2": "^2.2.2",
+    "ai": "^4.3.2",
     "bitbucket": "^2.12.0",
     "chalk": "^5.4.1",
     "cors": "^2.8.5",

packages/cli/src/cli/cmd/i18n.ts

@@ -1,5 +1,4 @@
 import { bucketTypeSchema, I18nConfig, localeCodeSchema, resolveOverriddenLocale } from "@lingo.dev/_spec";
-import { LingoDotDevEngine } from "@lingo.dev/_sdk";
 import { Command } from "interactive-commander";
 import Z from "zod";
 import _ from "lodash";
@@ -17,6 +16,8 @@ import inquirer from "inquirer";
 import externalEditor from "external-editor";
 import { cacheChunk, deleteCache, getNormalizedCache } from "../utils/cache";
 import updateGitignore from "../utils/update-gitignore";
+import createProcessor from "../processor";
+import { withExponentialBackoff } from "../utils/exp-backoff";
 
 export default new Command()
   .command("i18n")
@@ -299,11 +300,13 @@ export default new Command()
                 bucketOra.start(
                   `[${sourceLocale} -> ${targetLocale}] [${Object.keys(processableData).length} entries] (0%) AI localization in progress...`,
                 );
-                const localizationEngine = createLocalizationEngineConnection({
+                let processPayload = createProcessor(i18nConfig!.provider, {
                   apiKey: settings.auth.apiKey,
                   apiUrl: settings.auth.apiUrl,
                 });
-                const processedTargetData = await localizationEngine.process(
+                processPayload = withExponentialBackoff(processPayload, 3, 1000);
+
+                const processedTargetData = await processPayload(
                   {
                     sourceLocale,
                     sourceData,
@@ -435,47 +438,6 @@ async function retryWithExponentialBackoff<T>(
   throw new Error("Unreachable code");
 }
 
-function createLocalizationEngineConnection(params: { apiKey: string; apiUrl: string; maxRetries?: number }) {
-  const engine = new LingoDotDevEngine({
-    apiKey: params.apiKey,
-    apiUrl: params.apiUrl,
-  });
-
-  return {
-    process: async (
-      args: {
-        sourceLocale: string;
-        sourceData: Record<string, any>;
-        processableData: Record<string, any>;
-        targetLocale: string;
-        targetData: Record<string, any>;
-      },
-      onProgress: (
-        progress: number,
-        sourceChunk: Record<string, string>,
-        processedChunk: Record<string, string>,
-      ) => void,
-    ) => {
-      return retryWithExponentialBackoff(
-        () =>
-          engine.localizeObject(
-            args.processableData,
-            {
-              sourceLocale: args.sourceLocale,
-              targetLocale: args.targetLocale,
-              reference: {
-                [args.sourceLocale]: args.sourceData,
-                [args.targetLocale]: args.targetData,
-              },
-            },
-            onProgress,
-          ),
-        params.maxRetries ?? 3,
-      );
-    },
-  };
-}
-
 function parseFlags(options: any) {
   return Z.object({
     apiKey: Z.string().optional(),

packages/cli/src/cli/processor/_base.ts

@@ -0,0 +1,15 @@
+export type LocalizerInput = {
+  sourceLocale: string;
+  sourceData: Record<string, any>;
+  processableData: Record<string, any>;
+  targetLocale: string;
+  targetData: Record<string, any>;
+};
+
+export type LocalizerProgressFn = (
+  progress: number,
+  sourceChunk: Record<string, string>,
+  processedChunk: Record<string, string>,
+) => void;
+
+export type LocalizerFn = (input: LocalizerInput, onProgress: LocalizerProgressFn) => Promise<Record<string, any>>;

packages/cli/src/cli/processor/index.ts

@@ -0,0 +1,42 @@
+import { I18nConfig } from "@lingo.dev/_spec";
+import { LocalizerFn } from "./_base";
+import { createLingoLocalizer } from "./lingo";
+import { createBasicTranslator } from "./openai";
+import { createOpenAI } from "@ai-sdk/openai";
+import { createAnthropic } from "@ai-sdk/anthropic";
+
+export default function createProcessor(
+  provider: I18nConfig["provider"],
+  params: { apiKey: string; apiUrl: string },
+): LocalizerFn {
+  if (!provider || provider.id === "lingo") {
+    const result = createLingoLocalizer(params);
+    return result;
+  } else {
+    const model = getPureModelProvider(provider);
+    const result = createBasicTranslator(model, provider.prompt);
+    return result;
+  }
+}
+
+function getPureModelProvider(provider: I18nConfig["provider"]) {
+  switch (provider?.id) {
+    case "openai":
+      if (!process.env.OPENAI_API_KEY) {
+        throw new Error("OPENAI_API_KEY is not set.");
+      }
+      return createOpenAI({
+        apiKey: process.env.OPENAI_API_KEY,
+        baseURL: provider.baseUrl,
+      })(provider.model);
+    case "anthropic":
+      if (!process.env.ANTHROPIC_API_KEY) {
+        throw new Error("ANTHROPIC_API_KEY is not set.");
+      }
+      return createAnthropic({
+        apiKey: process.env.ANTHROPIC_API_KEY,
+      })(provider.model);
+    default:
+      throw new Error(`Unsupported provider: ${provider?.id}`);
+  }
+}

packages/cli/src/cli/processor/lingo.ts

@@ -0,0 +1,26 @@
+import { LingoDotDevEngine } from "@lingo.dev/_sdk";
+import { LocalizerInput, LocalizerProgressFn } from "./_base";
+
+export function createLingoLocalizer(params: { apiKey: string; apiUrl: string }) {
+  return async (input: LocalizerInput, onProgress: LocalizerProgressFn) => {
+    const lingo = new LingoDotDevEngine({
+      apiKey: params.apiKey,
+      apiUrl: params.apiUrl,
+    });
+
+    const result = await lingo.localizeObject(
+      input.processableData,
+      {
+        sourceLocale: input.sourceLocale,
+        targetLocale: input.targetLocale,
+        reference: {
+          [input.sourceLocale]: input.sourceData,
+          [input.targetLocale]: input.targetData,
+        },
+      },
+      onProgress,
+    );
+
+    return result;
+  };
+}

packages/cli/src/cli/processor/openai.ts

@@ -0,0 +1,55 @@
+import { generateText, LanguageModelV1 } from "ai";
+import { LocalizerInput, LocalizerProgressFn } from "./_base";
+
+export function createBasicTranslator(model: LanguageModelV1, systemPrompt: string) {
+  return async (input: LocalizerInput, onProgress: LocalizerProgressFn) => {
+    if (!process.env.OPENAI_API_KEY) {
+      throw new Error("OPENAI_API_KEY is not set");
+    }
+
+    const response = await generateText({
+      model,
+      messages: [
+        {
+          role: "system",
+          content: JSON.stringify({
+            role: "system",
+            content: systemPrompt.replaceAll("{source}", input.sourceLocale).replaceAll("{target}", input.targetLocale),
+          }),
+        },
+        {
+          role: "user",
+          content: JSON.stringify({
+            sourceLocale: "en",
+            targetLocale: "es",
+            data: {
+              message: "Hello, world!",
+            },
+          }),
+        },
+        {
+          role: "assistant",
+          content: JSON.stringify({
+            sourceLocale: "en",
+            targetLocale: "es",
+            data: {
+              message: "Hola, mundo!",
+            },
+          }),
+        },
+        {
+          role: "user",
+          content: JSON.stringify({
+            sourceLocale: "en",
+            targetLocale: "es",
+            data: input.processableData,
+          }),
+        },
+      ],
+    });
+
+    const result = JSON.parse(response.text);
+
+    return result;
+  };
+}

packages/cli/src/cli/utils/exp-backoff.ts

@@ -0,0 +1,19 @@
+export function withExponentialBackoff<T, Args extends any[]>(
+  fn: (...args: Args) => Promise<T>,
+  maxAttempts: number = 3,
+  baseDelay: number = 1000,
+): (...args: Args) => Promise<T> {
+  return async (...args: Args): Promise<T> => {
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+      try {
+        return await fn(...args);
+      } catch (error) {
+        if (attempt === maxAttempts - 1) throw error;
+
+        const delay = baseDelay * Math.pow(2, attempt);
+        await new Promise((resolve) => setTimeout(resolve, delay));
+      }
+    }
+    throw new Error("Unreachable code");
+  };
+}

packages/spec/src/config.ts

@@ -23,12 +23,12 @@ type ConfigDefinitionExtensionParams<T extends Z.ZodRawShape, P extends Z.ZodRaw
   createUpgrader: (
     config: Z.infer<Z.ZodObject<P>>,
     schema: Z.ZodObject<T>,
-    defaultValue: Z.infer<Z.ZodObject<T>>
+    defaultValue: Z.infer<Z.ZodObject<T>>,
   ) => Z.infer<Z.ZodObject<T>>;
 };
 const extendConfigDefinition = <T extends Z.ZodRawShape, P extends Z.ZodRawShape>(
   definition: ConfigDefinition<P, any>,
-  params: ConfigDefinitionExtensionParams<T, P>
+  params: ConfigDefinitionExtensionParams<T, P>,
 ) => {
   const schema = params.createSchema(definition.schema);
   const defaultValue = params.createDefaultValue(definition.defaultValue);
@@ -120,7 +120,7 @@ export const configV1_1Definition = extendConfigDefinition(configV1Definition, {
         Z.object({
           include: Z.array(Z.string()).default([]),
           exclude: Z.array(Z.string()).default([]).optional(),
-        })
+        }),
       ).default({}),
     }),
   createDefaultValue: (baseDefaultValue) => ({
@@ -188,7 +188,7 @@ export const configV1_3Definition = extendConfigDefinition(configV1_2Definition,
             .default([])
             .optional(),
           injectLocale: Z.array(Z.string()).optional(),
-        })
+        }),
       ).default({}),
     }),
   createDefaultValue: (baseDefaultValue) => ({
@@ -222,8 +222,47 @@ export const configV1_4Definition = extendConfigDefinition(configV1_3Definition,
   }),
 });
 
+// v1.4 -> v1.5
+// Changes: add "provider" field to the config
+const commonProviderSchema = Z.object({
+  id: Z.string(),
+  model: Z.string(),
+  prompt: Z.string(),
+  baseUrl: Z.string().optional(),
+});
+const providerSchema = Z.union([
+  commonProviderSchema.extend({
+    id: Z.literal("lingo"),
+    model: Z.literal("best"),
+  }),
+  commonProviderSchema.extend({
+    id: Z.enum(["openai", "anthropic"]),
+  }),
+]);
+export const configV1_5Definition = extendConfigDefinition(configV1_4Definition, {
+  createSchema: (baseSchema) =>
+    baseSchema.extend({
+      provider: providerSchema
+        .default({
+          id: "lingo",
+          model: "best",
+          baseUrl: "https://engine.lingo.dev",
+          prompt: "",
+        })
+        .optional(),
+    }),
+  createDefaultValue: (baseDefaultValue) => ({
+    ...baseDefaultValue,
+    version: 1.5,
+  }),
+  createUpgrader: (oldConfig) => ({
+    ...oldConfig,
+    version: 1.5,
+  }),
+});
+
 // exports
-export const LATEST_CONFIG_DEFINITION = configV1_4Definition;
+export const LATEST_CONFIG_DEFINITION = configV1_5Definition;
 
 export type I18nConfig = Z.infer<(typeof LATEST_CONFIG_DEFINITION)["schema"]>;