lingo.dev

library0.133.9jsnpmunverified

Lingo.dev is an open-source i18n toolkit for Node.js environments, currently at version `0.133.9`, which is actively maintained with frequent patch releases addressing fixes and minor enhancements across its components. It functions as a comprehensive solution for localization, notably leveraging AI to streamline i18n setup in popular React frameworks like Next.js, React Router, and TanStack Start. A key differentiator is its 'MCP' (Multi-Context Planning) feature, which provides AI assistants with structured, framework-specific i18n knowledge to prevent common hallucination errors during setup. The package offers a robust CLI for translating various file formats (JSON, YAML, markdown, CSV, PO, VTT), an SDK for runtime translation, a compiler for build-time localization, and integrates into CI/CD pipelines. This ecosystem covers the full localization lifecycle from initial configuration to automated workflows.

llm-agents devops web-framework

npm install lingo.dev

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · LINGO.DEV

lingo.dev

llm-agentsjavascriptv0.133.9

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Client

✓ import { Client } from 'lingo.dev';

✗ const { Client } = require('lingo.dev');

The primary class for interacting with the Lingo.dev SDK for runtime translation. The `lingo.dev` package re-exports SDK functionalities as implied by the README.

LingoConfig

✓ import type { LingoConfig } from 'lingo.dev';

✗ import { LingoConfig } from 'lingo.dev';

Type definition for Lingo.dev configuration. Use `import type` for type-only imports to ensure tree-shaking and avoid runtime issues.

run

✓ import { run } from 'lingo.dev/cli';

✗ import { run } from 'lingo.dev';

While primarily a CLI, advanced use cases might programmatically invoke CLI commands. The `run` function for the CLI is likely exposed from a subpath, e.g., 'lingo.dev/cli'.

This quickstart demonstrates basic programmatic interaction with the Lingo.dev SDK for pushing and fetching JSON content, illustrating runtime translation capabilities.

import { Client } from 'lingo.dev'; import { readFileSync } from 'node:fs'; const lingoClient = new Client({ apiKey: process.env.LINGO_API_KEY ?? '', projectId: process.env.LINGO_PROJECT_ID ?? '', baseUrl: 'https://api.lingo.dev' }); async function translateContent() { if (!process.env.LINGO_API_KEY || !process.env.LINGO_PROJECT_ID) { console.error('LINGO_API_KEY and LINGO_PROJECT_ID environment variables must be set.'); return; } try { // Example: Pushing content from a file (e.g., a simple JSON for translation) // In a real scenario, this would involve more complex file parsing. const sourceContent = readFileSync('src/locales/en.json', 'utf8'); console.log('Pushing content for translation...'); const pushResult = await lingoClient.pushJson({ locale: 'en', content: JSON.parse(sourceContent) }); console.log('Push result:', pushResult); // Example: Fetching translated content console.log('Fetching translations for es...'); const translations = await lingoClient.fetchJson({ locale: 'es', projectId: process.env.LINGO_PROJECT_ID ?? '' }); console.log('Spanish Translations:', translations); } catch (error) { console.error('Error during Lingo.dev operation:', error); } } translateContent(); // To run the CLI (separate usage, typically from terminal): // npx lingo.dev@latest run --help

lingo --version

Debug

Known issues

breakingThe package requires Node.js version 18 or higher. Older Node.js environments will fail to run the CLI or utilize the SDK.

fix

Upgrade your Node.js environment to version 18 or newer.

affects: <=0.133.0

breakingSDK API error handling was changed to propagate network errors instead of silently treating them as 'not authenticated'. This means applications relying on previous silent failure behavior for network issues will now receive direct error throws.

fix

Update error handling logic to explicitly catch and manage network-related errors that may now propagate from Lingo.dev SDK calls, particularly for the `whoami` function and similar API interactions.

affects: >=0.133.4

gotchaThe documentation mentions `npm install lingo.dev` for SDK usage, but the internal SDK implementation is in `@lingo.dev/_sdk`. While the main `lingo.dev` package appears to re-export core SDK functionalities, direct imports from the internal `@lingo.dev/_sdk` package are not officially supported and may lead to issues or break in future versions.

fix

Always import SDK functionalities directly from 'lingo.dev' (e.g., `import { Client } from 'lingo.dev';`) rather than attempting to import from `@lingo.dev/_sdk`.

affects: >=0.1.0

gotchaThe CI pull request flow previously ignored existing translation branches and started from scratch, potentially creating duplicate PRs when original ones were merged concurrently.

fix

Ensure you are on version `0.133.6` or later to leverage the fix for the CI pull request flow. If using custom CI/CD scripts, verify their idempotency.

affects: <=0.133.5

Errors

Common errors & fixes

Error: Command not found: lingo.dev

The Lingo.dev CLI is not installed globally or `npx` is not resolving it correctly in your PATH.

fix

Install the CLI globally (`npm install -g lingo.dev`) or use `npx lingo.dev@latest <command>` to execute it without global installation.

Error: VTT parser crash on files with STYLE/REGION blocks

An older version of the Lingo.dev CLI had a bug in its VTT (WebVTT) parser when encountering `STYLE` or `REGION` blocks within the file.

fix

Update Lingo.dev to version `0.133.6` or newer, which contains a fix for this VTT parsing issue.

Error: Authentication failed: Invalid API Key or Project ID.

The provided Lingo.dev API Key or Project ID is either missing, incorrect, or does not have sufficient permissions for the requested operation.

fix

Verify that your `LINGO_API_KEY` and `LINGO_PROJECT_ID` environment variables are correctly set and correspond to valid credentials for your Lingo.dev project.

TypeError: Cannot read properties of undefined (reading 'pushJson')

This error likely occurs when attempting to call SDK methods on an uninitialized or incorrectly initialized `Client` instance, possibly due to missing configuration.

fix

Ensure the `Lingo.dev Client` is correctly instantiated with valid `apiKey`, `projectId`, and `baseUrl` in its configuration object.

Upgrade

Version history

0.133.9latest on npm

Audit

Dependencies

@lingo.dev/_sdkrequiredInternal dependency for core SDK functionalities, which may be re-exported or used by the CLI.

@lingo.dev/_compilerrequiredInternal dependency for build-time compilation features, used by the CLI.

Agent activity

21 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/lingodotdev/lingo.dev ↗

packagehttps://www.npmjs.com/package/lingo.dev ↗

homepagehttps://lingo.dev ↗