@lingo.dev/_sdk 0.7.12

package/README.md

@@ -0,0 +1,19 @@
+# Lingo.dev SDK
+
+Official SDK for Lingo.dev.
+
+### Installation
+
+```bash
+npm i lingo.dev
+```
+
+### Usage
+
+```
+import {} from 'lingo.dev/sdk';
+```
+
+### Documentation
+
+[Documentation](https://lingo.dev/go/docs)

package/build/index.cjs

@@ -0,0 +1,326 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _interopRequireWildcard(obj) { if (obj && obj.__esModule) { return obj; } else { var newObj = {}; if (obj != null) { for (var key in obj) { if (Object.prototype.hasOwnProperty.call(obj, key)) { newObj[key] = obj[key]; } } } newObj.default = obj; return newObj; } } function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; } function _optionalChain(ops) { let lastAccessLHS = undefined; let value = ops[0]; let i = 1; while (i < ops.length) { const op = ops[i]; const fn = ops[i + 1]; i += 2; if ((op === 'optionalAccess' || op === 'optionalCall') && value == null) { return undefined; } if (op === 'access' || op === 'optionalAccess') { lastAccessLHS = value; value = fn(value); } else if (op === 'call' || op === 'optionalCall') { value = fn((...args) => value.call(lastAccessLHS, ...args)); lastAccessLHS = undefined; } } return value; }// src/index.ts
+var _zod = require('zod'); var _zod2 = _interopRequireDefault(_zod);
+var __spec = require('@lingo.dev/_spec');
+var _cuid2 = require('@paralleldrive/cuid2');
+var engineParamsSchema = _zod2.default.object({
+  apiKey: _zod2.default.string(),
+  apiUrl: _zod2.default.string().url().default("https://engine.lingo.dev"),
+  batchSize: _zod2.default.number().int().gt(0).lte(250).default(25),
+  idealBatchItemSize: _zod2.default.number().int().gt(0).lte(2500).default(250)
+}).passthrough();
+var payloadSchema = _zod2.default.record(_zod2.default.string(), _zod2.default.any());
+var localizationParamsSchema = _zod2.default.object({
+  sourceLocale: __spec.localeCodeSchema,
+  targetLocale: __spec.localeCodeSchema,
+  fast: _zod2.default.boolean().optional()
+});
+var referenceSchema = _zod2.default.record(__spec.localeCodeSchema, payloadSchema);
+var ReplexicaEngine = class {
+  
+  /**
+   * Create a new ReplexicaEngine instance
+   * @param config - Configuration options for the Engine
+   */
+  constructor(config) {
+    this.config = engineParamsSchema.parse(config);
+  }
+  /**
+   * Localize content using the Lingo.dev API
+   * @param payload - The content to be localized
+   * @param params - Localization parameters including source/target locales and fast mode option
+   * @param reference - Optional reference translations to maintain consistency
+   * @param progressCallback - Optional callback function to report progress (0-100)
+   * @returns Localized content
+   * @internal
+   */
+  async _localizeRaw(payload, params, reference, progressCallback) {
+    const finalPayload = payloadSchema.parse(payload);
+    const finalParams = localizationParamsSchema.parse(params);
+    const chunkedPayload = this.extractPayloadChunks(finalPayload);
+    const processedPayloadChunks = [];
+    const workflowId = _cuid2.createId.call(void 0, );
+    for (let i = 0; i < chunkedPayload.length; i++) {
+      const chunk = chunkedPayload[i];
+      const percentageCompleted = Math.round((i + 1) / chunkedPayload.length * 100);
+      const processedPayloadChunk = await this.localizeChunk(
+        finalParams.sourceLocale,
+        finalParams.targetLocale,
+        { data: chunk, reference },
+        workflowId,
+        params.fast || false
+      );
+      if (progressCallback) {
+        progressCallback(percentageCompleted, chunk, processedPayloadChunk);
+      }
+      processedPayloadChunks.push(processedPayloadChunk);
+    }
+    return Object.assign({}, ...processedPayloadChunks);
+  }
+  /**
+   * Localize a single chunk of content
+   * @param sourceLocale - Source locale
+   * @param targetLocale - Target locale
+   * @param payload - Payload containing the chunk to be localized
+   * @returns Localized chunk
+   */
+  async localizeChunk(sourceLocale, targetLocale, payload, workflowId, fast) {
+    const res = await fetch(`${this.config.apiUrl}/i18n`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${this.config.apiKey}`
+      },
+      body: JSON.stringify(
+        {
+          params: { workflowId, fast },
+          locale: {
+            source: sourceLocale,
+            target: targetLocale
+          },
+          data: payload.data,
+          reference: payload.reference
+        },
+        null,
+        2
+      )
+    });
+    if (!res.ok) {
+      if (res.status === 400) {
+        throw new Error(`Invalid request: ${res.statusText}`);
+      } else {
+        const errorText = await res.text();
+        throw new Error(errorText);
+      }
+    }
+    const jsonResponse = await res.json();
+    return jsonResponse.data || {};
+  }
+  /**
+   * Extract payload chunks based on the ideal chunk size
+   * @param payload - The payload to be chunked
+   * @returns An array of payload chunks
+   */
+  extractPayloadChunks(payload) {
+    const result = [];
+    let currentChunk = {};
+    let currentChunkItemCount = 0;
+    const payloadEntries = Object.entries(payload);
+    for (let i = 0; i < payloadEntries.length; i++) {
+      const [key, value] = payloadEntries[i];
+      currentChunk[key] = value;
+      currentChunkItemCount++;
+      const currentChunkSize = this.countWordsInRecord(currentChunk);
+      if (currentChunkSize > this.config.idealBatchItemSize || currentChunkItemCount >= this.config.batchSize || i === payloadEntries.length - 1) {
+        result.push(currentChunk);
+        currentChunk = {};
+        currentChunkItemCount = 0;
+      }
+    }
+    return result;
+  }
+  /**
+   * Count words in a record or array
+   * @param payload - The payload to count words in
+   * @returns The total number of words
+   */
+  countWordsInRecord(payload) {
+    if (Array.isArray(payload)) {
+      return payload.reduce((acc, item) => acc + this.countWordsInRecord(item), 0);
+    } else if (typeof payload === "object" && payload !== null) {
+      return Object.values(payload).reduce((acc, item) => acc + this.countWordsInRecord(item), 0);
+    } else if (typeof payload === "string") {
+      return payload.trim().split(/\s+/).filter(Boolean).length;
+    } else {
+      return 0;
+    }
+  }
+  /**
+   * Localize a typical JavaScript object
+   * @param obj - The object to be localized (strings will be extracted and translated)
+   * @param params - Localization parameters:
+   *   - sourceLocale: The source language code (e.g., 'en')
+   *   - targetLocale: The target language code (e.g., 'es')
+   *   - fast: Optional boolean to enable fast mode (faster but potentially lower quality)
+   * @param progressCallback - Optional callback function to report progress (0-100)
+   * @returns A new object with the same structure but localized string values
+   */
+  async localizeObject(obj, params, progressCallback) {
+    return this._localizeRaw(obj, params, void 0, progressCallback);
+  }
+  /**
+   * Localize a single text string
+   * @param text - The text string to be localized
+   * @param params - Localization parameters:
+   *   - sourceLocale: The source language code (e.g., 'en')
+   *   - targetLocale: The target language code (e.g., 'es')
+   *   - fast: Optional boolean to enable fast mode (faster for bigger batches)
+   * @param progressCallback - Optional callback function to report progress (0-100)
+   * @returns The localized text string
+   */
+  async localizeText(text, params, progressCallback) {
+    const response = await this._localizeRaw({ text }, params, void 0, progressCallback);
+    return response.text || "";
+  }
+  /**
+   * Localize a text string to multiple target locales
+   * @param text - The text string to be localized
+   * @param params - Localization parameters:
+   *   - sourceLocale: The source language code (e.g., 'en')
+   *   - targetLocales: An array of target language codes (e.g., ['es', 'fr'])
+   *   - fast: Optional boolean to enable fast mode (for bigger batches)
+   * @returns An array of localized text strings
+   */
+  async batchLocalizeText(text, params) {
+    const responses = await Promise.all(
+      params.targetLocales.map(
+        (targetLocale) => this.localizeText(text, {
+          sourceLocale: params.sourceLocale,
+          targetLocale,
+          fast: params.fast
+        })
+      )
+    );
+    return responses;
+  }
+  /**
+   * Localize a chat sequence while preserving speaker names
+   * @param chat - Array of chat messages, each with 'name' and 'text' properties
+   * @param params - Localization parameters:
+   *   - sourceLocale: The source language code (e.g., 'en')
+   *   - targetLocale: The target language code (e.g., 'es')
+   *   - fast: Optional boolean to enable fast mode (faster but potentially lower quality)
+   * @param progressCallback - Optional callback function to report progress (0-100)
+   * @returns Array of localized chat messages with preserved structure
+   */
+  async localizeChat(chat, params, progressCallback) {
+    const localized = await this._localizeRaw({ chat }, params, void 0, progressCallback);
+    return Object.entries(localized).map(([key, value]) => ({
+      name: chat[parseInt(key.split("_")[1])].name,
+      text: value
+    }));
+  }
+  /**
+   * Localize an HTML document while preserving structure and formatting
+   * Handles both text content and localizable attributes (alt, title, placeholder, meta content)
+   * @param html - The HTML document string to be localized
+   * @param params - Localization parameters:
+   *   - sourceLocale: The source language code (e.g., 'en')
+   *   - targetLocale: The target language code (e.g., 'es')
+   *   - fast: Optional boolean to enable fast mode (faster but potentially lower quality)
+   * @param progressCallback - Optional callback function to report progress (0-100)
+   * @returns The localized HTML document as a string, with updated lang attribute
+   */
+  async localizeHtml(html, params, progressCallback) {
+    const jsdomPackage = await Promise.resolve().then(() => _interopRequireWildcard(require("jsdom")));
+    const { JSDOM } = jsdomPackage;
+    const dom = new JSDOM(html);
+    const document = dom.window.document;
+    const LOCALIZABLE_ATTRIBUTES = {
+      meta: ["content"],
+      img: ["alt"],
+      input: ["placeholder"],
+      a: ["title"]
+    };
+    const UNLOCALIZABLE_TAGS = ["script", "style"];
+    const extractedContent = {};
+    const getPath = (node, attribute) => {
+      const indices = [];
+      let current = node;
+      let rootParent = "";
+      while (current) {
+        const parent = current.parentElement;
+        if (!parent) break;
+        if (parent === document.documentElement) {
+          rootParent = current.nodeName.toLowerCase();
+          break;
+        }
+        const siblings = Array.from(parent.childNodes).filter(
+          (n) => n.nodeType === 1 || n.nodeType === 3 && _optionalChain([n, 'access', _ => _.textContent, 'optionalAccess', _2 => _2.trim, 'call', _3 => _3()])
+        );
+        const index = siblings.indexOf(current);
+        if (index !== -1) {
+          indices.unshift(index);
+        }
+        current = parent;
+      }
+      const basePath = rootParent ? `${rootParent}/${indices.join("/")}` : indices.join("/");
+      return attribute ? `${basePath}#${attribute}` : basePath;
+    };
+    const processNode = (node) => {
+      let parent = node.parentElement;
+      while (parent) {
+        if (UNLOCALIZABLE_TAGS.includes(parent.tagName.toLowerCase())) {
+          return;
+        }
+        parent = parent.parentElement;
+      }
+      if (node.nodeType === 3) {
+        const text = _optionalChain([node, 'access', _4 => _4.textContent, 'optionalAccess', _5 => _5.trim, 'call', _6 => _6()]) || "";
+        if (text) {
+          extractedContent[getPath(node)] = text;
+        }
+      } else if (node.nodeType === 1) {
+        const element = node;
+        const tagName = element.tagName.toLowerCase();
+        const attributes = LOCALIZABLE_ATTRIBUTES[tagName] || [];
+        attributes.forEach((attr) => {
+          const value = element.getAttribute(attr);
+          if (value) {
+            extractedContent[getPath(element, attr)] = value;
+          }
+        });
+        Array.from(element.childNodes).filter((n) => n.nodeType === 1 || n.nodeType === 3 && _optionalChain([n, 'access', _7 => _7.textContent, 'optionalAccess', _8 => _8.trim, 'call', _9 => _9()])).forEach(processNode);
+      }
+    };
+    Array.from(document.head.childNodes).filter((n) => n.nodeType === 1 || n.nodeType === 3 && _optionalChain([n, 'access', _10 => _10.textContent, 'optionalAccess', _11 => _11.trim, 'call', _12 => _12()])).forEach(processNode);
+    Array.from(document.body.childNodes).filter((n) => n.nodeType === 1 || n.nodeType === 3 && _optionalChain([n, 'access', _13 => _13.textContent, 'optionalAccess', _14 => _14.trim, 'call', _15 => _15()])).forEach(processNode);
+    const localizedContent = await this._localizeRaw(extractedContent, params, void 0, progressCallback);
+    document.documentElement.setAttribute("lang", params.targetLocale);
+    Object.entries(localizedContent).forEach(([path, value]) => {
+      const [nodePath, attribute] = path.split("#");
+      const [rootTag, ...indices] = nodePath.split("/");
+      let parent = rootTag === "head" ? document.head : document.body;
+      let current = parent;
+      for (const index of indices) {
+        const siblings = Array.from(parent.childNodes).filter(
+          (n) => n.nodeType === 1 || n.nodeType === 3 && _optionalChain([n, 'access', _16 => _16.textContent, 'optionalAccess', _17 => _17.trim, 'call', _18 => _18()])
+        );
+        current = siblings[parseInt(index)] || null;
+        if (_optionalChain([current, 'optionalAccess', _19 => _19.nodeType]) === 1) {
+          parent = current;
+        }
+      }
+      if (current) {
+        if (attribute) {
+          current.setAttribute(attribute, value);
+        } else {
+          current.textContent = value;
+        }
+      }
+    });
+    return dom.serialize();
+  }
+  /**
+   * Detect the language of a given text
+   * @param text - The text to analyze
+   * @returns Promise resolving to a locale code (e.g., 'en', 'es', 'fr')
+   */
+  async recognizeLocale(text) {
+    const response = await fetch(`${this.config.apiUrl}/recognize`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${this.config.apiKey}`
+      },
+      body: JSON.stringify({ text })
+    });
+    if (!response.ok) {
+      throw new Error(`Error recognizing locale: ${response.statusText}`);
+    }
+    const jsonResponse = await response.json();
+    return jsonResponse.locale;
+  }
+};
+
+
+exports.ReplexicaEngine = ReplexicaEngine;

package/build/index.d.cts

@@ -0,0 +1,150 @@
+import Z from 'zod';
+import { LocaleCode } from '@lingo.dev/_spec';
+
+declare const engineParamsSchema: Z.ZodObject<{
+    apiKey: Z.ZodString;
+    apiUrl: Z.ZodDefault<Z.ZodString>;
+    batchSize: Z.ZodDefault<Z.ZodNumber>;
+    idealBatchItemSize: Z.ZodDefault<Z.ZodNumber>;
+}, "passthrough", Z.ZodTypeAny, Z.objectOutputType<{
+    apiKey: Z.ZodString;
+    apiUrl: Z.ZodDefault<Z.ZodString>;
+    batchSize: Z.ZodDefault<Z.ZodNumber>;
+    idealBatchItemSize: Z.ZodDefault<Z.ZodNumber>;
+}, Z.ZodTypeAny, "passthrough">, Z.objectInputType<{
+    apiKey: Z.ZodString;
+    apiUrl: Z.ZodDefault<Z.ZodString>;
+    batchSize: Z.ZodDefault<Z.ZodNumber>;
+    idealBatchItemSize: Z.ZodDefault<Z.ZodNumber>;
+}, Z.ZodTypeAny, "passthrough">>;
+declare const payloadSchema: Z.ZodRecord<Z.ZodString, Z.ZodAny>;
+declare const localizationParamsSchema: Z.ZodObject<{
+    sourceLocale: Z.ZodEffects<Z.ZodString, string, string>;
+    targetLocale: Z.ZodEffects<Z.ZodString, string, string>;
+    fast: Z.ZodOptional<Z.ZodBoolean>;
+}, "strip", Z.ZodTypeAny, {
+    sourceLocale: string;
+    targetLocale: string;
+    fast?: boolean | undefined;
+}, {
+    sourceLocale: string;
+    targetLocale: string;
+    fast?: boolean | undefined;
+}>;
+declare const referenceSchema: Z.ZodRecord<Z.ZodEffects<Z.ZodString, string, string>, Z.ZodRecord<Z.ZodString, Z.ZodAny>>;
+/**
+ * ReplexicaEngine class for interacting with the Lingo.dev API
+ * A powerful localization engine that supports various content types including
+ * plain text, objects, chat sequences, and HTML documents.
+ */
+declare class ReplexicaEngine {
+    private config;
+    /**
+     * Create a new ReplexicaEngine instance
+     * @param config - Configuration options for the Engine
+     */
+    constructor(config: Partial<Z.infer<typeof engineParamsSchema>>);
+    /**
+     * Localize content using the Lingo.dev API
+     * @param payload - The content to be localized
+     * @param params - Localization parameters including source/target locales and fast mode option
+     * @param reference - Optional reference translations to maintain consistency
+     * @param progressCallback - Optional callback function to report progress (0-100)
+     * @returns Localized content
+     * @internal
+     */
+    _localizeRaw(payload: Z.infer<typeof payloadSchema>, params: Z.infer<typeof localizationParamsSchema>, reference?: Z.infer<typeof referenceSchema>, progressCallback?: (progress: number, sourceChunk: Record<string, string>, processedChunk: Record<string, string>) => void): Promise<Record<string, string>>;
+    /**
+     * Localize a single chunk of content
+     * @param sourceLocale - Source locale
+     * @param targetLocale - Target locale
+     * @param payload - Payload containing the chunk to be localized
+     * @returns Localized chunk
+     */
+    private localizeChunk;
+    /**
+     * Extract payload chunks based on the ideal chunk size
+     * @param payload - The payload to be chunked
+     * @returns An array of payload chunks
+     */
+    private extractPayloadChunks;
+    /**
+     * Count words in a record or array
+     * @param payload - The payload to count words in
+     * @returns The total number of words
+     */
+    private countWordsInRecord;
+    /**
+     * Localize a typical JavaScript object
+     * @param obj - The object to be localized (strings will be extracted and translated)
+     * @param params - Localization parameters:
+     *   - sourceLocale: The source language code (e.g., 'en')
+     *   - targetLocale: The target language code (e.g., 'es')
+     *   - fast: Optional boolean to enable fast mode (faster but potentially lower quality)
+     * @param progressCallback - Optional callback function to report progress (0-100)
+     * @returns A new object with the same structure but localized string values
+     */
+    localizeObject(obj: Record<string, any>, params: Z.infer<typeof localizationParamsSchema>, progressCallback?: (progress: number, sourceChunk: Record<string, string>, processedChunk: Record<string, string>) => void): Promise<Record<string, any>>;
+    /**
+     * Localize a single text string
+     * @param text - The text string to be localized
+     * @param params - Localization parameters:
+     *   - sourceLocale: The source language code (e.g., 'en')
+     *   - targetLocale: The target language code (e.g., 'es')
+     *   - fast: Optional boolean to enable fast mode (faster for bigger batches)
+     * @param progressCallback - Optional callback function to report progress (0-100)
+     * @returns The localized text string
+     */
+    localizeText(text: string, params: Z.infer<typeof localizationParamsSchema>, progressCallback?: (progress: number) => void): Promise<string>;
+    /**
+     * Localize a text string to multiple target locales
+     * @param text - The text string to be localized
+     * @param params - Localization parameters:
+     *   - sourceLocale: The source language code (e.g., 'en')
+     *   - targetLocales: An array of target language codes (e.g., ['es', 'fr'])
+     *   - fast: Optional boolean to enable fast mode (for bigger batches)
+     * @returns An array of localized text strings
+     */
+    batchLocalizeText(text: string, params: {
+        sourceLocale: LocaleCode;
+        targetLocales: LocaleCode[];
+        fast?: boolean;
+    }): Promise<string[]>;
+    /**
+     * Localize a chat sequence while preserving speaker names
+     * @param chat - Array of chat messages, each with 'name' and 'text' properties
+     * @param params - Localization parameters:
+     *   - sourceLocale: The source language code (e.g., 'en')
+     *   - targetLocale: The target language code (e.g., 'es')
+     *   - fast: Optional boolean to enable fast mode (faster but potentially lower quality)
+     * @param progressCallback - Optional callback function to report progress (0-100)
+     * @returns Array of localized chat messages with preserved structure
+     */
+    localizeChat(chat: Array<{
+        name: string;
+        text: string;
+    }>, params: Z.infer<typeof localizationParamsSchema>, progressCallback?: (progress: number) => void): Promise<Array<{
+        name: string;
+        text: string;
+    }>>;
+    /**
+     * Localize an HTML document while preserving structure and formatting
+     * Handles both text content and localizable attributes (alt, title, placeholder, meta content)
+     * @param html - The HTML document string to be localized
+     * @param params - Localization parameters:
+     *   - sourceLocale: The source language code (e.g., 'en')
+     *   - targetLocale: The target language code (e.g., 'es')
+     *   - fast: Optional boolean to enable fast mode (faster but potentially lower quality)
+     * @param progressCallback - Optional callback function to report progress (0-100)
+     * @returns The localized HTML document as a string, with updated lang attribute
+     */
+    localizeHtml(html: string, params: Z.infer<typeof localizationParamsSchema>, progressCallback?: (progress: number) => void): Promise<string>;
+    /**
+     * Detect the language of a given text
+     * @param text - The text to analyze
+     * @returns Promise resolving to a locale code (e.g., 'en', 'es', 'fr')
+     */
+    recognizeLocale(text: string): Promise<LocaleCode>;
+}
+
+export { ReplexicaEngine };

package/build/index.d.ts

@@ -0,0 +1,150 @@
+import Z from 'zod';
+import { LocaleCode } from '@lingo.dev/_spec';
+
+declare const engineParamsSchema: Z.ZodObject<{
+    apiKey: Z.ZodString;
+    apiUrl: Z.ZodDefault<Z.ZodString>;
+    batchSize: Z.ZodDefault<Z.ZodNumber>;
+    idealBatchItemSize: Z.ZodDefault<Z.ZodNumber>;
+}, "passthrough", Z.ZodTypeAny, Z.objectOutputType<{
+    apiKey: Z.ZodString;
+    apiUrl: Z.ZodDefault<Z.ZodString>;
+    batchSize: Z.ZodDefault<Z.ZodNumber>;
+    idealBatchItemSize: Z.ZodDefault<Z.ZodNumber>;
+}, Z.ZodTypeAny, "passthrough">, Z.objectInputType<{
+    apiKey: Z.ZodString;
+    apiUrl: Z.ZodDefault<Z.ZodString>;
+    batchSize: Z.ZodDefault<Z.ZodNumber>;
+    idealBatchItemSize: Z.ZodDefault<Z.ZodNumber>;
+}, Z.ZodTypeAny, "passthrough">>;
+declare const payloadSchema: Z.ZodRecord<Z.ZodString, Z.ZodAny>;
+declare const localizationParamsSchema: Z.ZodObject<{
+    sourceLocale: Z.ZodEffects<Z.ZodString, string, string>;
+    targetLocale: Z.ZodEffects<Z.ZodString, string, string>;
+    fast: Z.ZodOptional<Z.ZodBoolean>;
+}, "strip", Z.ZodTypeAny, {
+    sourceLocale: string;
+    targetLocale: string;
+    fast?: boolean | undefined;
+}, {
+    sourceLocale: string;
+    targetLocale: string;
+    fast?: boolean | undefined;
+}>;
+declare const referenceSchema: Z.ZodRecord<Z.ZodEffects<Z.ZodString, string, string>, Z.ZodRecord<Z.ZodString, Z.ZodAny>>;
+/**
+ * ReplexicaEngine class for interacting with the Lingo.dev API
+ * A powerful localization engine that supports various content types including
+ * plain text, objects, chat sequences, and HTML documents.
+ */
+declare class ReplexicaEngine {
+    private config;
+    /**
+     * Create a new ReplexicaEngine instance
+     * @param config - Configuration options for the Engine
+     */
+    constructor(config: Partial<Z.infer<typeof engineParamsSchema>>);
+    /**
+     * Localize content using the Lingo.dev API
+     * @param payload - The content to be localized
+     * @param params - Localization parameters including source/target locales and fast mode option
+     * @param reference - Optional reference translations to maintain consistency
+     * @param progressCallback - Optional callback function to report progress (0-100)
+     * @returns Localized content
+     * @internal
+     */
+    _localizeRaw(payload: Z.infer<typeof payloadSchema>, params: Z.infer<typeof localizationParamsSchema>, reference?: Z.infer<typeof referenceSchema>, progressCallback?: (progress: number, sourceChunk: Record<string, string>, processedChunk: Record<string, string>) => void): Promise<Record<string, string>>;
+    /**
+     * Localize a single chunk of content
+     * @param sourceLocale - Source locale
+     * @param targetLocale - Target locale
+     * @param payload - Payload containing the chunk to be localized
+     * @returns Localized chunk
+     */
+    private localizeChunk;
+    /**
+     * Extract payload chunks based on the ideal chunk size
+     * @param payload - The payload to be chunked
+     * @returns An array of payload chunks
+     */
+    private extractPayloadChunks;
+    /**
+     * Count words in a record or array
+     * @param payload - The payload to count words in
+     * @returns The total number of words
+     */
+    private countWordsInRecord;
+    /**
+     * Localize a typical JavaScript object
+     * @param obj - The object to be localized (strings will be extracted and translated)
+     * @param params - Localization parameters:
+     *   - sourceLocale: The source language code (e.g., 'en')
+     *   - targetLocale: The target language code (e.g., 'es')
+     *   - fast: Optional boolean to enable fast mode (faster but potentially lower quality)
+     * @param progressCallback - Optional callback function to report progress (0-100)
+     * @returns A new object with the same structure but localized string values
+     */
+    localizeObject(obj: Record<string, any>, params: Z.infer<typeof localizationParamsSchema>, progressCallback?: (progress: number, sourceChunk: Record<string, string>, processedChunk: Record<string, string>) => void): Promise<Record<string, any>>;
+    /**
+     * Localize a single text string
+     * @param text - The text string to be localized
+     * @param params - Localization parameters:
+     *   - sourceLocale: The source language code (e.g., 'en')
+     *   - targetLocale: The target language code (e.g., 'es')
+     *   - fast: Optional boolean to enable fast mode (faster for bigger batches)
+     * @param progressCallback - Optional callback function to report progress (0-100)
+     * @returns The localized text string
+     */
+    localizeText(text: string, params: Z.infer<typeof localizationParamsSchema>, progressCallback?: (progress: number) => void): Promise<string>;
+    /**
+     * Localize a text string to multiple target locales
+     * @param text - The text string to be localized
+     * @param params - Localization parameters:
+     *   - sourceLocale: The source language code (e.g., 'en')
+     *   - targetLocales: An array of target language codes (e.g., ['es', 'fr'])
+     *   - fast: Optional boolean to enable fast mode (for bigger batches)
+     * @returns An array of localized text strings
+     */
+    batchLocalizeText(text: string, params: {
+        sourceLocale: LocaleCode;
+        targetLocales: LocaleCode[];
+        fast?: boolean;
+    }): Promise<string[]>;
+    /**
+     * Localize a chat sequence while preserving speaker names
+     * @param chat - Array of chat messages, each with 'name' and 'text' properties
+     * @param params - Localization parameters:
+     *   - sourceLocale: The source language code (e.g., 'en')
+     *   - targetLocale: The target language code (e.g., 'es')
+     *   - fast: Optional boolean to enable fast mode (faster but potentially lower quality)
+     * @param progressCallback - Optional callback function to report progress (0-100)
+     * @returns Array of localized chat messages with preserved structure
+     */
+    localizeChat(chat: Array<{
+        name: string;
+        text: string;
+    }>, params: Z.infer<typeof localizationParamsSchema>, progressCallback?: (progress: number) => void): Promise<Array<{
+        name: string;
+        text: string;
+    }>>;
+    /**
+     * Localize an HTML document while preserving structure and formatting
+     * Handles both text content and localizable attributes (alt, title, placeholder, meta content)
+     * @param html - The HTML document string to be localized
+     * @param params - Localization parameters:
+     *   - sourceLocale: The source language code (e.g., 'en')
+     *   - targetLocale: The target language code (e.g., 'es')
+     *   - fast: Optional boolean to enable fast mode (faster but potentially lower quality)
+     * @param progressCallback - Optional callback function to report progress (0-100)
+     * @returns The localized HTML document as a string, with updated lang attribute
+     */
+    localizeHtml(html: string, params: Z.infer<typeof localizationParamsSchema>, progressCallback?: (progress: number) => void): Promise<string>;
+    /**
+     * Detect the language of a given text
+     * @param text - The text to analyze
+     * @returns Promise resolving to a locale code (e.g., 'en', 'es', 'fr')
+     */
+    recognizeLocale(text: string): Promise<LocaleCode>;
+}
+
+export { ReplexicaEngine };

package/build/index.mjs

@@ -0,0 +1,326 @@
+// src/index.ts
+import Z from "zod";
+import { localeCodeSchema } from "@lingo.dev/_spec";
+import { createId } from "@paralleldrive/cuid2";
+var engineParamsSchema = Z.object({
+  apiKey: Z.string(),
+  apiUrl: Z.string().url().default("https://engine.lingo.dev"),
+  batchSize: Z.number().int().gt(0).lte(250).default(25),
+  idealBatchItemSize: Z.number().int().gt(0).lte(2500).default(250)
+}).passthrough();
+var payloadSchema = Z.record(Z.string(), Z.any());
+var localizationParamsSchema = Z.object({
+  sourceLocale: localeCodeSchema,
+  targetLocale: localeCodeSchema,
+  fast: Z.boolean().optional()
+});
+var referenceSchema = Z.record(localeCodeSchema, payloadSchema);
+var ReplexicaEngine = class {
+  config;
+  /**
+   * Create a new ReplexicaEngine instance
+   * @param config - Configuration options for the Engine
+   */
+  constructor(config) {
+    this.config = engineParamsSchema.parse(config);
+  }
+  /**
+   * Localize content using the Lingo.dev API
+   * @param payload - The content to be localized
+   * @param params - Localization parameters including source/target locales and fast mode option
+   * @param reference - Optional reference translations to maintain consistency
+   * @param progressCallback - Optional callback function to report progress (0-100)
+   * @returns Localized content
+   * @internal
+   */
+  async _localizeRaw(payload, params, reference, progressCallback) {
+    const finalPayload = payloadSchema.parse(payload);
+    const finalParams = localizationParamsSchema.parse(params);
+    const chunkedPayload = this.extractPayloadChunks(finalPayload);
+    const processedPayloadChunks = [];
+    const workflowId = createId();
+    for (let i = 0; i < chunkedPayload.length; i++) {
+      const chunk = chunkedPayload[i];
+      const percentageCompleted = Math.round((i + 1) / chunkedPayload.length * 100);
+      const processedPayloadChunk = await this.localizeChunk(
+        finalParams.sourceLocale,
+        finalParams.targetLocale,
+        { data: chunk, reference },
+        workflowId,
+        params.fast || false
+      );
+      if (progressCallback) {
+        progressCallback(percentageCompleted, chunk, processedPayloadChunk);
+      }
+      processedPayloadChunks.push(processedPayloadChunk);
+    }
+    return Object.assign({}, ...processedPayloadChunks);
+  }
+  /**
+   * Localize a single chunk of content
+   * @param sourceLocale - Source locale
+   * @param targetLocale - Target locale
+   * @param payload - Payload containing the chunk to be localized
+   * @returns Localized chunk
+   */
+  async localizeChunk(sourceLocale, targetLocale, payload, workflowId, fast) {
+    const res = await fetch(`${this.config.apiUrl}/i18n`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${this.config.apiKey}`
+      },
+      body: JSON.stringify(
+        {
+          params: { workflowId, fast },
+          locale: {
+            source: sourceLocale,
+            target: targetLocale
+          },
+          data: payload.data,
+          reference: payload.reference
+        },
+        null,
+        2
+      )
+    });
+    if (!res.ok) {
+      if (res.status === 400) {
+        throw new Error(`Invalid request: ${res.statusText}`);
+      } else {
+        const errorText = await res.text();
+        throw new Error(errorText);
+      }
+    }
+    const jsonResponse = await res.json();
+    return jsonResponse.data || {};
+  }
+  /**
+   * Extract payload chunks based on the ideal chunk size
+   * @param payload - The payload to be chunked
+   * @returns An array of payload chunks
+   */
+  extractPayloadChunks(payload) {
+    const result = [];
+    let currentChunk = {};
+    let currentChunkItemCount = 0;
+    const payloadEntries = Object.entries(payload);
+    for (let i = 0; i < payloadEntries.length; i++) {
+      const [key, value] = payloadEntries[i];
+      currentChunk[key] = value;
+      currentChunkItemCount++;
+      const currentChunkSize = this.countWordsInRecord(currentChunk);
+      if (currentChunkSize > this.config.idealBatchItemSize || currentChunkItemCount >= this.config.batchSize || i === payloadEntries.length - 1) {
+        result.push(currentChunk);
+        currentChunk = {};
+        currentChunkItemCount = 0;
+      }
+    }
+    return result;
+  }
+  /**
+   * Count words in a record or array
+   * @param payload - The payload to count words in
+   * @returns The total number of words
+   */
+  countWordsInRecord(payload) {
+    if (Array.isArray(payload)) {
+      return payload.reduce((acc, item) => acc + this.countWordsInRecord(item), 0);
+    } else if (typeof payload === "object" && payload !== null) {
+      return Object.values(payload).reduce((acc, item) => acc + this.countWordsInRecord(item), 0);
+    } else if (typeof payload === "string") {
+      return payload.trim().split(/\s+/).filter(Boolean).length;
+    } else {
+      return 0;
+    }
+  }
+  /**
+   * Localize a typical JavaScript object
+   * @param obj - The object to be localized (strings will be extracted and translated)
+   * @param params - Localization parameters:
+   *   - sourceLocale: The source language code (e.g., 'en')
+   *   - targetLocale: The target language code (e.g., 'es')
+   *   - fast: Optional boolean to enable fast mode (faster but potentially lower quality)
+   * @param progressCallback - Optional callback function to report progress (0-100)
+   * @returns A new object with the same structure but localized string values
+   */
+  async localizeObject(obj, params, progressCallback) {
+    return this._localizeRaw(obj, params, void 0, progressCallback);
+  }
+  /**
+   * Localize a single text string
+   * @param text - The text string to be localized
+   * @param params - Localization parameters:
+   *   - sourceLocale: The source language code (e.g., 'en')
+   *   - targetLocale: The target language code (e.g., 'es')
+   *   - fast: Optional boolean to enable fast mode (faster for bigger batches)
+   * @param progressCallback - Optional callback function to report progress (0-100)
+   * @returns The localized text string
+   */
+  async localizeText(text, params, progressCallback) {
+    const response = await this._localizeRaw({ text }, params, void 0, progressCallback);
+    return response.text || "";
+  }
+  /**
+   * Localize a text string to multiple target locales
+   * @param text - The text string to be localized
+   * @param params - Localization parameters:
+   *   - sourceLocale: The source language code (e.g., 'en')
+   *   - targetLocales: An array of target language codes (e.g., ['es', 'fr'])
+   *   - fast: Optional boolean to enable fast mode (for bigger batches)
+   * @returns An array of localized text strings
+   */
+  async batchLocalizeText(text, params) {
+    const responses = await Promise.all(
+      params.targetLocales.map(
+        (targetLocale) => this.localizeText(text, {
+          sourceLocale: params.sourceLocale,
+          targetLocale,
+          fast: params.fast
+        })
+      )
+    );
+    return responses;
+  }
+  /**
+   * Localize a chat sequence while preserving speaker names
+   * @param chat - Array of chat messages, each with 'name' and 'text' properties
+   * @param params - Localization parameters:
+   *   - sourceLocale: The source language code (e.g., 'en')
+   *   - targetLocale: The target language code (e.g., 'es')
+   *   - fast: Optional boolean to enable fast mode (faster but potentially lower quality)
+   * @param progressCallback - Optional callback function to report progress (0-100)
+   * @returns Array of localized chat messages with preserved structure
+   */
+  async localizeChat(chat, params, progressCallback) {
+    const localized = await this._localizeRaw({ chat }, params, void 0, progressCallback);
+    return Object.entries(localized).map(([key, value]) => ({
+      name: chat[parseInt(key.split("_")[1])].name,
+      text: value
+    }));
+  }
+  /**
+   * Localize an HTML document while preserving structure and formatting
+   * Handles both text content and localizable attributes (alt, title, placeholder, meta content)
+   * @param html - The HTML document string to be localized
+   * @param params - Localization parameters:
+   *   - sourceLocale: The source language code (e.g., 'en')
+   *   - targetLocale: The target language code (e.g., 'es')
+   *   - fast: Optional boolean to enable fast mode (faster but potentially lower quality)
+   * @param progressCallback - Optional callback function to report progress (0-100)
+   * @returns The localized HTML document as a string, with updated lang attribute
+   */
+  async localizeHtml(html, params, progressCallback) {
+    const jsdomPackage = await import("jsdom");
+    const { JSDOM } = jsdomPackage;
+    const dom = new JSDOM(html);
+    const document = dom.window.document;
+    const LOCALIZABLE_ATTRIBUTES = {
+      meta: ["content"],
+      img: ["alt"],
+      input: ["placeholder"],
+      a: ["title"]
+    };
+    const UNLOCALIZABLE_TAGS = ["script", "style"];
+    const extractedContent = {};
+    const getPath = (node, attribute) => {
+      const indices = [];
+      let current = node;
+      let rootParent = "";
+      while (current) {
+        const parent = current.parentElement;
+        if (!parent) break;
+        if (parent === document.documentElement) {
+          rootParent = current.nodeName.toLowerCase();
+          break;
+        }
+        const siblings = Array.from(parent.childNodes).filter(
+          (n) => n.nodeType === 1 || n.nodeType === 3 && n.textContent?.trim()
+        );
+        const index = siblings.indexOf(current);
+        if (index !== -1) {
+          indices.unshift(index);
+        }
+        current = parent;
+      }
+      const basePath = rootParent ? `${rootParent}/${indices.join("/")}` : indices.join("/");
+      return attribute ? `${basePath}#${attribute}` : basePath;
+    };
+    const processNode = (node) => {
+      let parent = node.parentElement;
+      while (parent) {
+        if (UNLOCALIZABLE_TAGS.includes(parent.tagName.toLowerCase())) {
+          return;
+        }
+        parent = parent.parentElement;
+      }
+      if (node.nodeType === 3) {
+        const text = node.textContent?.trim() || "";
+        if (text) {
+          extractedContent[getPath(node)] = text;
+        }
+      } else if (node.nodeType === 1) {
+        const element = node;
+        const tagName = element.tagName.toLowerCase();
+        const attributes = LOCALIZABLE_ATTRIBUTES[tagName] || [];
+        attributes.forEach((attr) => {
+          const value = element.getAttribute(attr);
+          if (value) {
+            extractedContent[getPath(element, attr)] = value;
+          }
+        });
+        Array.from(element.childNodes).filter((n) => n.nodeType === 1 || n.nodeType === 3 && n.textContent?.trim()).forEach(processNode);
+      }
+    };
+    Array.from(document.head.childNodes).filter((n) => n.nodeType === 1 || n.nodeType === 3 && n.textContent?.trim()).forEach(processNode);
+    Array.from(document.body.childNodes).filter((n) => n.nodeType === 1 || n.nodeType === 3 && n.textContent?.trim()).forEach(processNode);
+    const localizedContent = await this._localizeRaw(extractedContent, params, void 0, progressCallback);
+    document.documentElement.setAttribute("lang", params.targetLocale);
+    Object.entries(localizedContent).forEach(([path, value]) => {
+      const [nodePath, attribute] = path.split("#");
+      const [rootTag, ...indices] = nodePath.split("/");
+      let parent = rootTag === "head" ? document.head : document.body;
+      let current = parent;
+      for (const index of indices) {
+        const siblings = Array.from(parent.childNodes).filter(
+          (n) => n.nodeType === 1 || n.nodeType === 3 && n.textContent?.trim()
+        );
+        current = siblings[parseInt(index)] || null;
+        if (current?.nodeType === 1) {
+          parent = current;
+        }
+      }
+      if (current) {
+        if (attribute) {
+          current.setAttribute(attribute, value);
+        } else {
+          current.textContent = value;
+        }
+      }
+    });
+    return dom.serialize();
+  }
+  /**
+   * Detect the language of a given text
+   * @param text - The text to analyze
+   * @returns Promise resolving to a locale code (e.g., 'en', 'es', 'fr')
+   */
+  async recognizeLocale(text) {
+    const response = await fetch(`${this.config.apiUrl}/recognize`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${this.config.apiKey}`
+      },
+      body: JSON.stringify({ text })
+    });
+    if (!response.ok) {
+      throw new Error(`Error recognizing locale: ${response.statusText}`);
+    }
+    const jsonResponse = await response.json();
+    return jsonResponse.locale;
+  }
+};
+export {
+  ReplexicaEngine
+};

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@lingo.dev/_sdk",
+  "version": "0.7.12",
+  "description": "Lingo.dev JS SDK",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "types": "build/index.d.ts",
+  "module": "build/index.mjs",
+  "main": "build/index.cjs",
+  "files": [
+    "build"
+  ],
+  "scripts": {
+    "dev": "tsup --watch",
+    "build": "tsc --noEmit && tsup",
+    "test": "vitest run"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "Apache-2.0",
+  "dependencies": {
+    "@paralleldrive/cuid2": "^2.2.2",
+    "@lingo.dev/_spec": "workspace:*",
+    "jsdom": "^25.0.1",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8",
+    "zod": "^3.24.1"
+  },
+  "devDependencies": {
+    "@types/jsdom": "^21.1.7",
+    "tsup": "^8.3.5"
+  }
+}