Quickstart

Lingo.dev CLI's core strength is to efficiently localize apps and markdown content into target languages using a single CLI command.

This quickstart guide assumes you're either about to make your app multilingual, or have already configured it to handle 2+ languages. Therefore, the guide is designed to be short enough to be completed in under 10 minutes, but detailed enough to understand the internals.

Upon completion of this guide, you will:

  1. Localize app content into Spanish and Japanese using an AI translation engine;
  2. Understand how source files, target files, and the configuration work together;
  3. Set up a localization workflow that can scale your app and markdown content to dozens of languages and tens of thousands of words.

Let's begin!

Prerequisites

Markdown

Markdown files are structured documents, that means no prior setup is needed. Lingo.dev CLI processes .md files directly, maintaining formatting while localizing content, so you can continue to the Step 1.

Applications

To make an app multilingual, modern web and mobile applications require developers to set up internationalization (i18n) configuration first.

For this quickstart, we'll create a standalone JSON file to demonstrate how Lingo.dev CLI localizes application content.

When integrating with your actual application, follow our recommended framework guides:

Windows only: Running via npx

If you are running npx for the first time, it requires Bash or another compatible shell. On Windows, you can install Git for Windows.

After installing, before running npx for the first time, set the shell for npx by running one of the following commands in your terminal (depending on where Git Bash is installed):

npm config set script-shell "C:\\Program Files\\git\\bin\\bash.exe"

or

npm config set script-shell "C:\\Program Files (x86)\\git\\bin\\bash.exe"

This is required to properly execute the lingo.dev package on Windows.

Step 1. Initialize the project

Lingo.dev CLI uses the standard i18n.json configuration file to declare your localization settings. To create it interactively, run:

npx lingo.dev@latest init

It will ask you questions about your project, then create a i18n.json file in your project root.

The file should look like this:

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

Let's unpack each configuration element:

  • locale.source — The language your team writes in. This setting identifies which files contain the authoritative content. All localization flows from source to targets.

  • locale.targets — An array of ISO 639-1 language codes representing your target markets. Each code corresponds to a separate file (or section within a file, depending on format). You can start with one or two languages and add more as you expand.

  • buckets.json.include — Glob-like patterns that tell the CLI where to find and create locale files. The special [locale] token expands to each language code. With the pattern locales/[locale].json, the CLI looks for locales/en.json as the source and generates locales/es.json and locales/ja.json as targets. You can specify multiple patterns and even mix formats within a single configuration.

Advanced features you'll discover as your project grows:

  • Multiple buckets for different file types or sections of your app
  • exclude patterns to skip certain files
  • lockedKeys to prevent specific values from translation

Create the English source file

For this quickstart, we'll create a locale file:

mkdir -p locales
echo '{"greeting":"Hello, world!","button.submit":"Submit"}' > locales/en.json

This creates a locales directory and an English source file with two translation keys. Keys like greeting work for flat structures, while namespaced keys like button.submit help organize larger applications.

Nested objects are supported too. You'll find more details about different file formats in the rest of the documentation.

Step 2. Authentication

The Lingo.dev CLI sends your content to AI translation engine for localization, so we need to authenticate first.

Option 1. Raw LLM API Access

The Lingo.dev CLI helps you use LLM models like OpenAI or Anthropic for localization and translation.

This means you're billed per token processed, you control the model selection, system prompts, and all model parameters.

To authenticate, create a .env file in your project root with your API key:

# if you're using OpenAI
OPENAI_API_KEY=sk-...
# if you're using Anthropic
ANTHROPIC_API_KEY=sk-...

Alternatively, instead of using .env, you can export the variable in your current shell session:

export ANTHROPIC_API_KEY=sk-ant-...

Want to add support for another provider? Lingo.dev CLI is open source and welcomes contributions! Fork the repository and submit a pull request: github.com/lingodotdev/lingo.dev.

Option 2. Lingo.dev Engine

Alternatively, you can create a free Lingo.dev Engine account and use it as your AI translation engine.

It provides dynamic model selection, auto-routing to different models for each language pair, automated model fallbacks, translation memory that considers past translations, and glossary support for your project's domain-specific terminology. There are both free and paid options, and the free Hobby tier should be sufficient for this tutorial.

To authenticate, run:

npx lingo.dev@latest login

Important detail. If you're using Brave browser, or your browser extensions are blocking the authentication flow, you can manually authenticate by adding a LINGODOTDEV_API_KEY environment variable to your .env file:

LINGODOTDEV_API_KEY=...

You will find the token in the Lingo.dev Engine Project Settings.

Step 3. Set up AI translation engine

Now that you're authenticated, you need to configure which AI translation engine to use.

Option 1. Raw LLM API Access

To use OpenAI, update your i18n.json config to use the openai provider:

{
  "locale": {
    "source": "en",
    "targets": ["es", "ja"]
  },
  "buckets": {
    "json": {
      "include": ["locales/[locale].json"]
    }
  },
  "provider": {
    "id": "openai",
    "model": "gpt-4o-mini",
    "prompt": "Act as a professional software localization expert. Translate each key from {source} to {target}. Preserve ICU message format placeholders like {name} and {{count}}. Maintain Markdown formatting including links and code blocks. Match the tone and formality of the source text. Technical terms that are typically untranslated in the industry should remain in English."
  }
}

You can experiment with different prompts to customize the localization behavior, but we've found this one to be a good starting point!

The provider configuration controls direct LLM access:

  • id — Either openai or anthropic
  • model — The specific model version to use. Examples: gpt-4o-mini, gpt-4o (OpenAI), or claude-3-haiku, claude-3-sonnet (Anthropic).
  • prompt — A system prompt that guides translation behavior. The {source} and {target} placeholders are replaced with actual language codes at runtime. This prompt is your opportunity to enforce terminology, style, and domain-specific rules.

Option 2. Lingo.dev Engine

If you're using Lingo.dev Engine as your AI translation engine, you can skip the provider node entirely.

The engine automatically selects models and prompts based on the Lingo.dev team's research and the settings of your engine.

Your i18n.json configuration:

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

Note: When using Lingo.dev Engine, omit the provider node entirely. The engine automatically selects models and prompts.

Step 4. Translate

To localize your app, run:

npx lingo.dev@latest i18n

The CLI will create the target files, and update the i18n.lock file that tracks content fingerprints. This ensures incremental updates on subsequent runs.

You've now localized your app content!

Next steps

You've completed the core localization workflow. Your repository now contains localized files that can be committed, reviewed, and deployed like any other code artifact.

From here, you can:

  • Automate the workflow: CI/CD Integration — Set up CI/CD integration to localize on every push, and commit the changes back to your repository automatically, via pull requests or direct commits;
  • Understand the internals: How it Works — Learn about the algorithms, performance optimizations, and architectural decisions.