CSV - Lingo.dev CLI

What is CSV?

CSV (Comma-Separated Values) is a plain text file format that stores tabular data, where each line represents a row and values within each row are separated by commas.

For example:

KEY,en
welcome_message,Welcome to our application
button_save,Save
error_invalid_email,Please enter a valid email address

What is Lingo.dev CLI?

Lingo.dev CLI is a free, open-source CLI for translating apps and content with AI. It's designed to replace traditional translation management software while integrating with existing pipelines.

To learn more, see Overview.

About this guide

This guide explains how to translate CSV files with Lingo.dev CLI.

You'll learn how to:

Create a project from scratch
Configure a translation pipeline
Generate translations with AI

Prerequisites

To use Lingo.dev CLI, ensure that Node.js v18+ is installed:

❯ node -v
v22.17.0

Step 1. Set up a project

In your project's directory, create an i18n.json file:

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {}
}

This file defines the behavior of the translation pipeline, including what languages to translate between and where the localizable content exists on the file system.

To learn more about the available properties, see i18n.json.

Step 2. Configure the source locale

The source locale is the original language and region that your content was written in. To configure the source locale, set the locale.source property in the i18n.json file:

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {}
}

The source locale must be provided as a BCP 47 language tag.

For the complete list of the locale codes that Lingo.dev CLI supports, see Supported locale codes.

Step 3. Configure the target locales

The target locales are the languages and regions you want to translate your content into. To configure the target locales, set the locale.targets property in the i18n.json file:

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {}
}

Step 4. Create the source content

If you haven't already, create a CSV file that contains the content to be translated.

In the case of CSV files, the following requirements apply:

The first column must be named "KEY".
Each row in the "KEY" column must specify unique IDs for translation messages.
The second column must equal the source locale that's defined in the i18n.json file.
Each row in the second column must contain the content that will be translated.

Note: During the translation process, the source content files will be overwritten to include the translated content (in addition to the source content).

Step 5. Create a bucket

In the i18n.json file, add a "csv" object to the buckets object:

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {
    "csv": {}
  }
}

In the "csv" object, define an array of one or more include patterns:
```
{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {
    "csv": {
      "include": ["./example.csv"]
    }
  }
}
```
These patterns define which files to translate and can either:
- point to specific file paths (e.g., "some/dir/file.csv")
- use asterisks as wildcard placeholders (e.g., "some/dir/*.csv")
Recursive glob patterns (e.g., **/*.csv) are not supported.

Step 6. Configure an LLM

Lingo.dev CLI uses large language models (LLMs) to translate content with AI. To use one of these models, you need an API key from a supported provider.

To get up and running as quickly as possible, we recommend using Lingo.dev Engine — our own, hosted platform that offers 10,000 tokens of free, monthly usage:

Sign up for a Lingo.dev account.
Run the following command:
```
npx lingo.dev@latest login
```
This will open your default browser and ask you to authenticte.
Follow the prompts.

Step 7. Generate the translations

In the directory that contains the i18n.json file, run the following command:

npx lingo.dev@latest run

This command:

Reads the i18n.json file.
Finds the files that need to be translated.
Extracts the translatable content from the files.
Uses the configured LLM to translate the extracted content.
Writes the translated content back to the file system.

The first time translations are generated, an i18n.lock file is created. This file keeps track of what content has been translated, preventing unnecessary retranslations on subsequent runs.

Example

example.csv (before translation)

KEY,en
welcome_message,Welcome to our application
button_save,Save
error_invalid_email,Please enter a valid email address
product_name,Premium Widget
empty_row_key,
whitespace_only,
new_feature,This is a new feature

example.csv (after translation)

KEY,en,es
welcome_message,Welcome to our application,Bienvenido a nuestra aplicación
button_save,Save,Guardar
error_invalid_email,Please enter a valid email address,"Por favor, introduce una dirección de correo electrónico válida"
product_name,Premium Widget,Widget Premium
empty_row_key,,
whitespace_only,   ,
new_feature,This is a new feature,Esta es una nueva función

i18n.json

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {
    "csv": {
      "include": ["./example.csv"]
    }
  }
}

i18n.lock

version: 1
checksums:
  e8b273672f895de0944f0a2317670d7c:
    welcome_message: 1308168cca4fa5d8d7a0cf24e55e93fc
    button_save: f7a2929f33bc420195e59ac5a8bcd454
    error_invalid_email: 8de4bc8832b11b380bc4cbcedc16e48b
    product_name: d3d99b147cc363dc6db8a48e8a13d4c1
    new_feature: 7cd986af1fe5e89abe7ecffba5413110
  d0f33bd41270762260010c4723a564f5:
    welcome_message: 1308168cca4fa5d8d7a0cf24e55e93fc
    button_save: f7a2929f33bc420195e59ac5a8bcd454
    error_invalid_email: 8de4bc8832b11b380bc4cbcedc16e48b
    product_name: d3d99b147cc363dc6db8a48e8a13d4c1
    new_feature: 7cd986af1fe5e89abe7ecffba5413110