Starlight

使用 Lingo.dev CLI 为 Starlight 提供 AI 翻译

什么是 Starlight？

Starlight 是一个基于 Astro 框架构建的文档主题。它内置了站点导航、搜索、国际化和 SEO 功能，可用于创建美观且易于访问的文档网站。

什么是 Lingo.dev CLI？

Lingo.dev 是一个由 AI 驱动的翻译平台。Lingo.dev CLI 会读取源文件，将可翻译内容发送给大型语言模型，并将翻译后的文件写回到您的项目中。

关于本指南

本指南介绍如何在 Starlight 文档站点中配置 Lingo.dev CLI。您将学习如何使用 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. 通过 CLI 登录 Lingo.dev：

    npx lingo.dev@latest login

  3. 运行翻译流水线：

    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. 启动开发服务器：

    npm run dev

  3. 访问以下 URL：