{"id":17025,"library":"lingo.dev","title":"Lingo.dev CLI","description":"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.","status":"active","version":"0.133.9","language":"javascript","source_language":"en","source_url":"https://github.com/lingodotdev/lingo.dev","tags":["javascript"],"install":[{"cmd":"npm install lingo.dev","lang":"bash","label":"npm"},{"cmd":"yarn add lingo.dev","lang":"bash","label":"yarn"},{"cmd":"pnpm add lingo.dev","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Internal dependency for core SDK functionalities, which may be re-exported or used by the CLI.","package":"@lingo.dev/_sdk","optional":false},{"reason":"Internal dependency for build-time compilation features, used by the CLI.","package":"@lingo.dev/_compiler","optional":false}],"imports":[{"note":"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.","wrong":"const { Client } = require('lingo.dev');","symbol":"Client","correct":"import { Client } from 'lingo.dev';"},{"note":"Type definition for Lingo.dev configuration. Use `import type` for type-only imports to ensure tree-shaking and avoid runtime issues.","wrong":"import { LingoConfig } from 'lingo.dev';","symbol":"LingoConfig","correct":"import type { LingoConfig } from 'lingo.dev';"},{"note":"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'.","wrong":"import { run } from 'lingo.dev';","symbol":"run","correct":"import { run } from 'lingo.dev/cli';"}],"quickstart":{"code":"import { Client } from 'lingo.dev';\nimport { readFileSync } from 'node:fs';\n\nconst lingoClient = new Client({\n  apiKey: process.env.LINGO_API_KEY ?? '',\n  projectId: process.env.LINGO_PROJECT_ID ?? '',\n  baseUrl: 'https://api.lingo.dev'\n});\n\nasync function translateContent() {\n  if (!process.env.LINGO_API_KEY || !process.env.LINGO_PROJECT_ID) {\n    console.error('LINGO_API_KEY and LINGO_PROJECT_ID environment variables must be set.');\n    return;\n  }\n\n  try {\n    // Example: Pushing content from a file (e.g., a simple JSON for translation)\n    // In a real scenario, this would involve more complex file parsing.\n    const sourceContent = readFileSync('src/locales/en.json', 'utf8');\n    console.log('Pushing content for translation...');\n    const pushResult = await lingoClient.pushJson({ \n        locale: 'en', \n        content: JSON.parse(sourceContent) \n    });\n    console.log('Push result:', pushResult);\n\n    // Example: Fetching translated content\n    console.log('Fetching translations for es...');\n    const translations = await lingoClient.fetchJson({\n      locale: 'es',\n      projectId: process.env.LINGO_PROJECT_ID ?? ''\n    });\n    console.log('Spanish Translations:', translations);\n\n  } catch (error) {\n    console.error('Error during Lingo.dev operation:', error);\n  }\n}\n\ntranslateContent();\n\n// To run the CLI (separate usage, typically from terminal):\n// npx lingo.dev@latest run --help","lang":"typescript","description":"This quickstart demonstrates basic programmatic interaction with the Lingo.dev SDK for pushing and fetching JSON content, illustrating runtime translation capabilities."},"warnings":[{"fix":"Upgrade your Node.js environment to version 18 or newer.","message":"The package requires Node.js version 18 or higher. Older Node.js environments will fail to run the CLI or utilize the SDK.","severity":"breaking","affected_versions":"<=0.133.0"},{"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.","message":"SDK 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.","severity":"breaking","affected_versions":">=0.133.4"},{"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`.","message":"The 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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"The CI pull request flow previously ignored existing translation branches and started from scratch, potentially creating duplicate PRs when original ones were merged concurrently.","severity":"gotcha","affected_versions":"<=0.133.5"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Install the CLI globally (`npm install -g lingo.dev`) or use `npx lingo.dev@latest <command>` to execute it without global installation.","cause":"The Lingo.dev CLI is not installed globally or `npx` is not resolving it correctly in your PATH.","error":"Error: Command not found: lingo.dev"},{"fix":"Update Lingo.dev to version `0.133.6` or newer, which contains a fix for this VTT parsing issue.","cause":"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.","error":"Error: VTT parser crash on files with STYLE/REGION blocks"},{"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.","cause":"The provided Lingo.dev API Key or Project ID is either missing, incorrect, or does not have sufficient permissions for the requested operation.","error":"Error: Authentication failed: Invalid API Key or Project ID."},{"fix":"Ensure the `Lingo.dev Client` is correctly instantiated with valid `apiKey`, `projectId`, and `baseUrl` in its configuration object.","cause":"This error likely occurs when attempting to call SDK methods on an uninitialized or incorrectly initialized `Client` instance, possibly due to missing configuration.","error":"TypeError: Cannot read properties of undefined (reading 'pushJson')"}],"ecosystem":"npm","meta_description":null}