Lingo.dev Docs

Appearance

Quickstart ​

This guide will help you:

  1. Save time on localization with Lingo.dev
  2. Set up the CLI in your project
  3. Add multiple languages with a single command

Authentication ​

Authenticate with Lingo.dev's cloud service:

bash
npx lingo.dev@latest auth --login

This opens a browser window for login or signup. Return to your terminal after authenticating.

INFO

Having trouble with browser redirects? Authenticate using an environment variable as described here.

Prefer using your own AI provider? Use the Bring Your Own LLM feature with your OpenAI or Anthropic API keys instead.

Project Setup ​

Lingo.dev uses an i18n.json configuration file to manage your translations. This file defines:

  • Source and target languages
  • Location of source files
  • Where to save translated files
  • Files to exclude from translation

Create this file with the initialization command:

bash
npx lingo.dev@latest init

TIP

The interactive setup will ask for:

  • Source locale (e.g., en for English)
  • Target locales (e.g., es fr for Spanish and French)
  • File formats to translate (e.g., json)
  • File patterns - the CLI detects existing locale files or creates new ones in default locations

This creates an i18n.json file in your current directory:

json
{
  "version": 1.1,
  "locale": {
    "source": "en",
    "targets": [
      "es",
      "fr"
    ]
  },
  "buckets": {
    "json": {
      "include": [
        "locales/[locale].json"
      ]
    }
  }
}

TIP

Already have translation files? Specify their paths in the buckets section.

This configuration:

  1. Sets English as your source language with Spanish and French as targets
  2. Tells Lingo.dev to look for JSON files in the locales folder

Each bucket (organized by file type) requires an include array for file patterns to translate. You can also add an exclude array to skip specific files.

Creating Source Files ​

If you don't have locale files yet, create them:

bash
mkdir locales
echo '{"hello": "Hello, world!"}' > locales/en.json

This creates a simple English source file with one key-value pair. In real projects, you'll have many more translation keys.

Translating Content ​

Run the translation command:

bash
npx lingo.dev@latest i18n

This creates es.json and fr.json files in the locales folder with translated content. The command also generates an i18n.lock file that tracks source file hashes, enabling Lingo.dev to update translations only when source content changes. Commit this lock file to your repository.

Automating Translations ​

Integrate Lingo.dev into your CI/CD pipeline by following our CI/CD or GitHub Actions guides.

TIP

You can configure multiple file types and complex patterns:

json
"buckets": {
  "markdown": {
    "include": [
      "docs/[locale]/*.md",
      "blog/[locale]/*.md"
    ],
    "exclude": [
      "docs/[locale]/internal-*.md"
    ]
  },
  "json": {
    "include": [
      "locales/[locale].json"
    ]
  }
}

This setup translates Markdown files in docs and blog directories (excluding those starting with internal-), plus JSON files in the locales directory.