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: "欢迎"
description: "开始使用我们的文档"
---

## 介绍

本文档由 Lingo.dev 自动翻译。

## 功能

我们的产品包含现代开发的强大功能。

第 3 步：配置 CLI

在项目根目录中创建一个 i18n.json 文件：

{
  "$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"
      ]
    }
  }
}

此文件定义了：

  • Lingo.dev CLI 应翻译的文件
  • 翻译的语言对

在此配置中，MDX 文件将从英语翻译为西班牙语。

需要注意的是：

  • [locale] 是一个在运行时替换的占位符。它确保内容从一个位置读取（例如，src/content/docs/en/index.mdx），并写入到另一个位置（例如，src/content/docs/es/index.mdx）。
  • Lingo.dev CLI 不支持递归的全局模式（例如，**/*.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：