VuePress - Lingo.dev CLI

What is VuePress?

VuePress is a Vue-powered static site generator for creating documentation sites. It provides a theme optimized for technical documentation and Vue component integration.

What is Lingo.dev CLI?

Lingo.dev is an AI-powered translation platform. The Lingo.dev CLI reads source files, sends translatable content to large language models, and writes translated files back to your project.

About this guide

This guide explains how to set up Lingo.dev CLI in a VuePress documentation site. You'll learn how to scaffold a project with VuePress, configure a translation pipeline, and view the results.

Step 1. Set up a VuePress project

Create a new VuePress project:
```
npm create vuepress@latest my-docs
```
Navigate into the project directory:
```
cd my-docs
```
Install dependencies:
```
npm install
```

Step 2. Create source content

Create a directory for storing documentation in the source locale:
```
mkdir docs/en
```

Create a file that contains some documentation content (e.g., 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.

Step 3. Set up symbolic links

VuePress expects source locale content in the root docs directory, with target locale content in subdirectories, but Lingo.dev CLI doesn't support this combination.

As a workaround, we recommend:

Storing the source content files in a locale directory (e.g., docs/en/)
Generating symbolic links so that the files also appear in the root docs directory

To streamline this process:

Create a script for generating the symbolic links (e.g., scripts/symlinks.sh):

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

Make the script executable:
```
chmod +x scripts/symlinks.sh
```
Run the script:
```
./scripts/symlinks.sh
```

You'll need to re-run the script any time you add files to the docs/en/ directory.

Step 4. Configure the CLI

In the root of the project, create an i18n.json file:

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

This file defines:

the files that Lingo.dev CLI should translate
the languages to translate between

In this case, the configuration translates Markdown files from English to Spanish.

It's important to note that:

[locale] is a placeholder that's replaced at runtime. It ensures that content is read from one location (e.g., docs/en/README.md) and written to a different location (e.g., docs/es/README.md).
Lingo.dev CLI does not support recursive glob patterns (e.g., **/*.md). You'll need to create additional include patterns to translate files that exist within nested directories.

To learn more, see i18n.json configuration.

Step 5. Translate the content

Sign up for a Lingo.dev account.
Log in to Lingo.dev via the CLI:
```
npx lingo.dev@latest login
```
Run the translation pipeline:
```
npx lingo.dev@latest run
```
The CLI will create a docs/es/ directory for storing the translated content and an i18n.lock file for keeping track of what has been translated (to prevent unnecessary retranslations).

Step 6. Use the translations

In the docs/.vuepress/config.js file:

Add a locales property to the theme configuration:

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

Add a root-level locales property to define the language configuration for each locale:

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

Start the development server:
```
npm run docs:dev
```
Navigate to http://localhost:8080. You should see a dropdown for switching between languages.