Starlight

AI translation for Starlight with Lingo.dev CLI

What is Starlight?

Starlight is a documentation theme built on top of the Astro framework. It provides built-in site navigation, search, internationalization, and SEO features to create beautiful, accessible documentation sites.

What is Lingo.dev CLI?

Lingo.dev is an AI-powered translation platform. The Lingo.dev CLI reads source files, sends translatable content to large language models, and writes translated files back to your project.

About this guide

This guide explains how to set up Lingo.dev CLI in a Starlight documentation site. You'll learn how to scaffold a project with Starlight, configure a translation pipeline, and view the results.

Step 1. Set up a Starlight project

  1. Create a new Starlight application:

    npm create astro@latest -- --template starlight

  2. Navigate into the project directory:

    cd <your-starlight-project>

Step 2. Create source content

  1. Create a directory for storing documentation in the source locale:

    mkdir -p src/content/docs/en

  2. Create a file that contains some documentation content (e.g., src/content/docs/en/index.mdx):

    ---
title: "Welcome"
description: "Getting started with our documentation"
---

## Introduction

This documentation is automatically translated by Lingo.dev.

## Features

Our product includes powerful capabilities for modern development.

Step 3. Configure the CLI

In the root of the project, create an i18n.json file:

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": 1.8,
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {
    "mdx": {
      "include": [
        "src/content/docs/[locale]/*.mdx",
        "src/content/docs/[locale]/*/*.mdx"
      ]
    }
  }
}

This file defines:

  • the files that Lingo.dev CLI should translate
  • the languages to translate between

In this case, the configuration translates MDX files from English to Spanish.

It's important to note that:

  • [locale] is a placeholder that's replaced at runtime. It ensures that content is read from one location (e.g., src/content/docs/en/index.mdx) and written to a different location (e.g., src/content/docs/es/index.mdx).
  • Lingo.dev CLI does not support recursive glob patterns (e.g., **/*.mdx). You'll need to create additional include patterns to translate files that exist within nested directories.

To learn more, see i18n.json configuration.

Step 4. Translate the content

  1. Sign up for a Lingo.dev account.

  2. Log in to Lingo.dev via the CLI:

    npx lingo.dev@latest login

  3. Run the translation pipeline:

    npx lingo.dev@latest run

    The CLI will create a src/content/docs/es/ directory for storing the translated content and a i18n.lock file for keeping track of what has been translated (to prevent unnecessary retranslations).

Step 5. Use the translations

  1. In the astro.config.mjs file, configure the supported locales:

    import { defineConfig } from "astro/config";
import starlight from "@astrojs/starlight";

export default defineConfig({
  integrations: [
    starlight({
      title: "My Docs",
      defaultLocale: "en",
      locales: {
        en: {
          label: "English",
          lang: "en",
        },
        es: {
          label: "Español",
          lang: "es",
        },
      },
    }),
  ],
});

  2. Start the development server:

    npm run dev

  3. Navigate to the following URLs: