astro-llm-translator

An Astro integration that automatically translates your Markdown and MDX content using LLMs (OpenAI, Anthropic, DeepSeek, etc.) during the build process.

It features incremental builds, smart caching, and automatic synchronization of deletions, ensuring you only pay for what needs to be translated.

Installation

npm install astro-llm-translator openai
# or
pnpm add astro-llm-translator openai
# or
bun add astro-llm-translator openai

Note: You also need to install the openai package as a peer dependency.

Usage

Add the integration to your astro.config.mjs:

import { defineConfig } from 'astro/config';
import llmTranslator from 'astro-llm-translator';

export default defineConfig({
  integrations: [
    llmTranslator({
      sourceLang: 'en', // or 'root'
      targetLangs: ['es', 'fr', 'de'],
      contentDir: 'src/content/docs',
      openai: {
        model: 'gpt-4o-mini', // Optional: defaults to gpt-4o-mini
      }
    })
  ]
});

Configuration

Options

Option	Type	Default	Description
sourceLang	string	Required	The language code of your source content (e.g., 'en'). Set to 'root' if your source files are directly inside contentDir.
targetLangs	string[]	Required	Array of language codes to translate into (e.g., ['es', 'fr']).
contentDir	string	'src/content/docs'	Directory relative to project root containing your content.
customInstructions	string	undefined	Additional instructions to guide the translator (e.g. "Use a friendly tone").
dictionary	Record<string, string>	{}	Key-value pairs of terms to force translation for (e.g. {'Astro': 'AstroFramework'}).
banner	Record<string, string>	{}	Optional configuration to inject banner content into the frontmatter of translated files.
openai	object	{}	Optional configuration for the LLM client.

Banner Configuration

You can inject a banner message into the frontmatter of translated files (e.g., to warn users that the content is AI-translated).

llmTranslator({
  // ...
  banner: {
    en: "This content is AI-translated.",
    es: "Este contenido ha sido traducido por IA."
  }
})

OpenAI Options (openai)

Option	Type	Default	Description
apiKey	string	process.env.OPENAI_API_KEY	Your API key.
baseURL	string	process.env.OPENAI_BASE_URL	Base URL for the API (useful for OpenRouter or local models).
model	string	'gpt-4o-mini'	The model identifier to use.

Environment Variables

You can configure the LLM client using environment variables in your .env file:

# Standard OpenAI
OPENAI_API_KEY=sk-...

# Or OpenRouter / Custom Provider
OPENROUTER_API_KEY=sk-or-...
OPENROUTER_BASE_URL=https://openrouter.ai/api/v1
OPENAI_MODEL=anthropic/claude-3-haiku

# Skip translation processing (e.g. in CI/Pages build)
ASTRO_LLM_SKIP_TRANSLATE=true

The integration checks for keys in this order:

1. options.openai.apiKey
2. OPENAI_API_KEY
3. OPENROUTER_API_KEY

Starlight Support

If you are using Starlight, you can use the companion plugin to automatically translate sidebar directory labels.

First, the main integration collects and translates directory names during the build process. Then, the Starlight plugin uses this data to reconstruct the sidebar with translated labels.

// astro.config.mjs
import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';
import llmTranslator from 'astro-llm-translator';
import starlightTranslator from 'astro-llm-translator/starlight'; // Import the plugin

export default defineConfig({
  integrations: [
    llmTranslator({
      sourceLang: 'en',
      targetLangs: ['es', 'fr'],
      // ... other options
    }),
    starlight({
      title: 'My Docs',
      defaultLocale: 'en',
      locales: {
        en: { label: 'English', lang: 'en' },
        es: { label: 'Español', lang: 'es' },
        fr: { label: 'Français', lang: 'fr' },
      },
      plugins: [
        starlightTranslator(), // Add the plugin here
      ],
      sidebar: [
        // Works with autogenerate!
        {
          label: 'Guides',
          autogenerate: { directory: 'guides' },
        },
      ],
    }),
  ],
});

Note: The main llmTranslator integration must be present to generate the translation data (src/.translator-segments.json) that the Starlight plugin relies on.

Directory Structure Examples

1. Subdirectory Mode (Default)

Config: sourceLang: 'en'

src/content/docs/
├── en/           <-- Source
│   └── index.md
├── es/           <-- Auto-generated
│   └── index.md
└── fr/           <-- Auto-generated
    └── index.md

2. Root Mode

Config: sourceLang: 'root'

src/content/docs/
├── index.md      <-- Source
├── about.md      <-- Source
├── es/           <-- Auto-generated (ignored by scanner)
│   ├── index.md
│   └── about.md
└── fr/           <-- Auto-generated (ignored by scanner)
    ├── index.md
    └── about.md