Lingo.dev CLI

Common errors

• Error: Command not found: lingo.dev

  cause 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

  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.
  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.

  cause 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')

  cause 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.

Warnings

• breaking The 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.
• breaking 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.
  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.
• gotcha 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.
  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`.
• gotcha The 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.

Install

• npm install lingo.dev npm
• yarn add lingo.dev yarn
• pnpm add lingo.dev pnpm

Imports

• Client
  wrong:

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

  correct:

  import { Client } from '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
  wrong:

  import { LingoConfig } from 'lingo.dev';

  correct:

  import type { 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
  wrong:

  import { run } from 'lingo.dev';

  correct:

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

  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'.

Quickstart

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