@lingo.dev/sdk

TypeScript SDK for the Lingo.dev localization API: synchronous localization, language detection, and asynchronous translation jobs with webhook callbacks.

Install

npm install @lingo.dev/sdk

The SDK ships a Promise-based client (no runtime dependencies) and an optional Effect-native entry point. effect is an optional peer dependency — install it only if you use the @lingo.dev/sdk/effect import.

Usage

import { createClient } from "@lingo.dev/sdk";

const lingo = createClient({ apiKey: process.env.LINGO_API_KEY! });

// Synchronous, single locale
const result = await lingo.localize({
  sourceLocale: "en",
  targetLocale: "es",
  data: { greeting: "Hello, world!" },
});
// → { sourceLocale: "en", targetLocale: "es", data: { greeting: "..." }, usage: { ... } }

Asynchronous jobs with a webhook callback

For multiple target locales or the full localization pipeline, create a job group. Lingo runs it in the background and POSTs a signed callback to callbackUrl per completed locale.

const group = await lingo.localizationJobs.create({
  sourceLocale: "en",
  targetLocales: ["es", "fr", "de"],
  data: { greeting: "Hello, world!" },
  callbackUrl: "https://your-app.example.com/lingo/callback",
  idempotencyKey: "your-stable-key", // safe to retry; returns the same group
});

// Reconcile by polling if a callback is missed (callbacks are best-effort)
const status = await lingo.localizationJobs.getGroup(group.groupId);

Callbacks are signed per the Standard Webhooks spec. Verify them with the standardwebhooks package using your organization's webhook secret.

Configuration

createClient({
  apiKey: "lk_...",               // required
  baseUrl: "https://api.lingo.dev", // optional override
  fetch: customFetch,              // optional; defaults to global fetch
});

Requests that fail throw LingoApiError with status and body.

Effect

import { LingoClient } from "@lingo.dev/sdk/effect";

const layer = LingoClient.layerConfig({
  apiKey: Config.redacted("LINGO_API_KEY"),
});

LingoClient is a Context.Service exposing the same methods, each returning an Effect.

License

Apache-2.0