VuePress - Lingo.dev CLI

什么是 VuePress？

VuePress 是一个基于 Vue 的静态网站生成器，适用于创建文档站点。它提供了针对技术文档优化的主题，并支持 Vue 组件集成。

什么是 Lingo.dev CLI？

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

关于本指南

本指南介绍如何在 VuePress 文档站点中配置 Lingo.dev CLI。您将学习如何使用 VuePress 搭建项目、配置翻译流程，并查看翻译结果。

步骤 1. 搭建 VuePress 项目

创建一个新的 VuePress 项目：
```
npm create vuepress@latest my-docs
```
进入项目目录：
```
cd my-docs
```
安装依赖：
```
npm install
```

步骤 2. 创建源内容

创建一个用于存放源语言文档的目录：
```
mkdir docs/en
```

创建一个包含文档内容的文件（例如，docs/en/README.md）：

---
home: true
title: Home
heroText: VuePress Documentation
tagline: Documentation powered by VuePress
---

## Getting started

This documentation is automatically translated by Lingo.dev.

## Features

Our product includes powerful capabilities for modern development.

步骤 3. 设置符号链接

VuePress 期望源语言内容位于根目录 docs，目标语言内容位于子目录，但 Lingo.dev CLI 不支持这种结构。

为此，我们建议：

将源内容文件存放在语言目录中（例如，docs/en/）
通过生成符号链接，使这些文件也出现在根目录 docs 下

为简化此流程：

创建一个用于生成符号链接的脚本（例如，scripts/symlinks.sh）：

for file in docs/en/*; do ln -sf "en/$(basename "$file")" "docs/$(basename "$file")"; done

使脚本具有可执行权限：
```
chmod +x scripts/symlinks.sh
```
运行该脚本：
```
./scripts/symlinks.sh
```

每当你向 docs/en/ 目录添加文件时，都需要重新运行该脚本。

步骤 4. 配置 CLI

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

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

该文件定义了：

Lingo.dev CLI 需要翻译的文件
需要互译的语言

在本例中，配置将 Markdown 文件从英文翻译为西班牙文。

需要注意的是：

[locale] 是一个在运行时替换的占位符。它确保内容从一个位置（如 docs/en/README.md）读取，并写入另一个位置（如 docs/es/README.md）。
Lingo.dev CLI 不支持递归 glob 模式（如 **/*.md）。如需翻译嵌套目录下的文件，你需要额外创建 include 模式。

了解更多信息，请参见 i18n.json 配置。

步骤 5. 翻译内容

注册 Lingo.dev 账号。
通过 CLI 登录 Lingo.dev：
```
npx lingo.dev@latest login
```
运行翻译流水线：
```
npx lingo.dev@latest run
```
CLI 会创建一个 docs/es/ 目录用于存储已翻译内容，并生成一个 i18n.lock 文件以记录已翻译内容（防止重复翻译）。

步骤 6. 使用翻译结果

在 docs/.vuepress/config.js 文件中：

在主题配置中添加一个 locales 属性：

theme: defaultTheme({
  locales: {
    "/": {
      selectLanguageName: "English",
    },
    "/es/": {
      selectLanguageName: "Español",
    },
  },
}),

在根级别添加一个 locales 属性，用于为每个语言环境定义语言配置：

{
  locales: {
    "/": {
      lang: "en",
      title: "VuePress",
    },
    "/es/": {
      lang: "es",
      title: "VuePress",
    },
  },
}

启动开发服务器：
```
npm run docs:dev
```
访问 http://localhost:8080。你应该会看到一个用于切换语言的下拉菜单。