HTML

AI translation for HTML files with Lingo.dev CLI

What is HTML?

HTML (HyperText Markup Language) is the standard markup language for creating web pages and web applications. It uses tags to structure content and define elements like headings, paragraphs, links, images, and forms.

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 HTML 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 one or more HTML files that contain the content to be translated. These files must be located at a path that includes the source locale somewhere in the path (e.g., as a directory name like en/ or as part of the filename like messages.en.html).

For HTML files, translatable content includes:

  • Text content within HTML elements
  • Attribute values including:
    • alt attributes (image descriptions)
    • title attributes (tooltips)
    • placeholder attributes (input hints)
    • value attributes (button and input values)
    • Meta tag content attributes
  • The lang attribute is automatically updated to match the target locale

Script tags, style tags, and non-translatable attributes are preserved.

For example:

<!DOCTYPE html>
<html lang="en">
  <head>
    <title>MyApp - Hello World</title>
    <meta name="description" content="A simple demo app" />
  </head>
  <body>
    <h1>Welcome to MyApp</h1>
    <p>Hello, world! This is a simple demo with <strong>bold text</strong>.</p>
    <img src="example.jpg" alt="Example image" />
  </body>
</html>

Step 5. Create a bucket

  1. In the i18n.json file, add an "html" object to the buckets object:

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

  2. In the "html" 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": {
    "html": {
      "include": ["./[locale]/example.html"]
    }
  }
}

    These patterns define which files to translate.

    The patterns themselves:

    • must contain [locale] as a placeholder for the configured locale
    • can point to file paths (e.g., "[locale]/config.html")
    • can use asterisks as wildcard placeholders (e.g., "[locale]/*.html")

    Recursive glob patterns (e.g., **/*.html) 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:

  1. Sign up for a Lingo.dev account.

  2. Run the following command:

    npx lingo.dev@latest login

    This will open your default browser and ask you to authenticte.

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

  1. Reads the i18n.json file.
  2. Finds the files that need to be translated.
  3. Extracts the translatable content from the files.
  4. Uses the configured LLM to translate the extracted content.
  5. 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

en/example.html

<!DOCTYPE html>
<html lang="en">
  <head>
    <title>MyApp - Hello World</title>
    <meta name="description" content="A simple demo app" />
  </head>
  <body>
    <h1>Welcome to MyApp</h1>
    <p>Hello, world! This is a simple demo with <strong>bold text</strong>.</p>
    <img src="example.jpg" alt="Example image" />
    <input type="text" placeholder="Enter text here" />
    <a href="#" title="Click for more">Learn more</a>
  </body>
</html>

es/example.html

<!DOCTYPE html>
<html lang="es">
  <head>
    <title>MyApp - Hola Mundo</title>
    <meta name="description" content="Una aplicación de demostración simple" />
  </head>
  <body>
    <h1>Bienvenido a MyApp</h1>
    <p>¡Hola, mundo! Esta es una demostración simple con <strong>texto en negrita</strong>.</p>
    <img src="example.jpg" alt="Imagen de ejemplo" />
    <input type="text" placeholder="Ingresa texto aquí" />
    <a href="#" title="Haz clic para más">Saber más</a>
  </body>
</html>

i18n.json

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

i18n.lock

version: 1
checksums:
  ab95e8c959a889717f02a05af5c5b1e6:
    head/0/0: 7d39787547365ee4194f29f3f54e5c05
    head/1#content: 49f8864eb0e53903f04532bf33e1e4fa
    head/2#content: c2a1da93efb7e744d100df705e5fcbfd
    head/3#content: d94b318cb327f61f1aea44a6cb1fdcad
    body/0/0: d1c3a9f35e377554a4ccaa467ca26614
    body/1/0: e19afd1952881bdf10063f9478980147
    body/1/1/0: 7cd9256312384858ecba6c29d3c2e550
    body/1/2: ce8b9bb44f031705708a70e068bb73c8
    body/1/3/0: 037d114f19b882f08994712b8d9c1e37
    body/1/4: f05f450fffcb17520c441ab9789f40ce
    body/2/0/0/0: 57d373bcffe2d376cbf9919da30ca30b
    body/3#alt: 68f95fca639f8bf72a4796b6734b02d5
    body/4#alt: cb7d920c3bbcade1c8e0307093f58573
    body/5#placeholder: a05ce3b4578f55e41bd2ad4964f966b4
    body/6#placeholder: a4554ed67c02872e302b0042724f859d
    body/7#title: c903c6985a40ce02d65c90229de35a4e
    body/7/0: e598091d132f890c37a6d4ed94f6d794
    body/8#title: d656021ba5f485fa1a82f8aac6ecc5de
    body/8/0: 1c6856488bd34ad87fcacce2d8e66a0b
    body/9/0: 862964e6cd73cdffdcac622406c6bac9