Starlight

AI-перевод для Starlight с помощью Lingo.dev CLI

Что такое Starlight?

Starlight — это тема для документации, созданная на базе фреймворка Astro. Она предоставляет встроенную навигацию по сайту, поиск, интернационализацию и SEO-функции для создания красивых и доступных сайтов с документацией.

Что такое Lingo.dev CLI?

Lingo.dev — это платформа для перевода на базе искусственного интеллекта. Lingo.dev CLI читает исходные файлы, отправляет переводимый контент в большие языковые модели и записывает переведённые файлы обратно в ваш проект.

О данном руководстве

В этом руководстве объясняется, как настроить Lingo.dev CLI на сайте документации Starlight. Вы узнаете, как создать проект на Starlight, настроить процесс перевода и посмотреть результат.

Шаг 1. Создайте проект Starlight

  1. Создайте новое приложение Starlight:

    npm create astro@latest -- --template starlight

  2. Перейдите в директорию проекта:

    cd <your-starlight-project>

Шаг 2. Создайте исходный контент

  1. Создайте директорию для хранения документации на исходном языке:

    mkdir -p src/content/docs/en

  2. Создайте файл с каким-либо содержимым документации (например, 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.

Шаг 3. Настройте CLI

В корне проекта создайте файл i18n.json:

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

Этот файл определяет:

  • какие файлы должен переводить Lingo.dev CLI
  • между какими языками выполнять перевод

В данном случае конфигурация переводит MDX-файлы с английского на испанский.

Важно отметить, что:

  • [locale] — это плейсхолдер, который заменяется во время выполнения. Он гарантирует, что контент читается из одного места (например, src/content/docs/en/index.mdx) и записывается в другое место (например, src/content/docs/es/index.mdx).
  • Lingo.dev CLI не поддерживает рекурсивные glob-шаблоны (например, **/*.mdx). Нужно создать дополнительные шаблоны include, чтобы переводить файлы, которые находятся во вложенных папках.

Подробнее смотри в конфиге i18n.json.

Шаг 4. Переведи контент

  1. Зарегистрируйся в Lingo.dev.

  2. Войди в Lingo.dev через CLI:

    npx lingo.dev@latest login

  3. Запусти pipeline перевода:

    npx lingo.dev@latest run

    CLI создаст директорию src/content/docs/es/ для хранения переведённого контента и файл i18n.lock для отслеживания переведённого (чтобы не переводить повторно).

Шаг 5. Используй переводы

  1. В файле astro.config.mjs укажи поддерживаемые локали:

    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. Запусти dev-сервер:

    npm run dev

  3. Перейди по этим ссылкам: