VuePress - Lingo.dev CLI

Что такое VuePress?

VuePress — это статический генератор сайтов на базе Vue для создания сайтов с документацией. Он предлагает тему, оптимизированную для технической документации, и интеграцию с компонентами Vue.

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

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

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

В этом руководстве объясняется, как настроить Lingo.dev CLI в проекте документации на VuePress. Вы узнаете, как создать проект на 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.
Войдите в Lingo.dev через CLI:
```
npx lingo.dev@latest login
```
Запустите pipeline перевода:
```
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",
    },
  },
}
```

Запустите dev-сервер:
```
npm run docs:dev
```
Перейдите на http://localhost:8080. Должен появиться выпадающий список для переключения языков.