astro-content-ai-translator

Astro integration for AI-powered content translation using OpenAI.

Installation

npm install @affiliate.fm/astro-content-ai-translator
npx astro-ai-translator init

The setup wizard will:

• Add integration to your astro.config.mjs
• Set up your OpenAI API key in .env

Alternatively, use npx astro add @affiliate.fm/astro-content-ai-translator.

Quick Start

1. Mark files for translation

In your content files, add _translateTo to frontmatter:

---
title: About Us
description: Learn about our company
_translateTo: [ru, de]
---

Options:

• _translateTo: [ru, de] — translate to specific locales
• _translateTo: all — translate to all configured locales
• _translateTo: false — explicitly don't translate
• No field — file is not translated (must opt-in)

Usage

Translate missing content

npx astro-ai-translator

Before translation starts, you'll see:

• Cost estimate — approximate tokens and USD cost
• File list — what will be translated
• Confirmation prompt — approve before spending API credits

Example output:

┌─────────────────────────────────────────────────────────────┐
│                   📊 TRANSLATION ESTIMATE                   │
└─────────────────────────────────────────────────────────────┘

  📁 Files to translate:
     • index.mdx → ru (~807 tokens)
     • index.mdx → ja (~807 tokens)
     • about.mdx → ru (~658 tokens)

  ─────────────────────────────────────────────────────────────
  📈 Model:          gpt-4.1
  📝 Translations:   3
  🔤 Input tokens:   ~1.1K
  📤 Output tokens:  ~1.1K
  📦 Total tokens:   ~2.3K
  ─────────────────────────────────────────────────────────────
  💰 Estimated cost: $0.02
  ─────────────────────────────────────────────────────────────

  Proceed with translation? (3 file(s), ~$0.02) [Y/n]

During translation, a live progress bar shows current status.

Translate specific file

npx astro-ai-translator about.mdx

Check status

npx astro-ai-translator --status

Preview (dry run)

npx astro-ai-translator --dry-run

Shows estimate without confirmation prompt. No API calls made.

Force overwrite

npx astro-ai-translator --force

Generated files

AI-translated files include metadata in frontmatter:

---
title: О нас
description: Узнайте о нашей компании
_ai:
  source: about.mdx
  hash: a1b2c3d4e5f6
  model: gpt-4.1
  date: "2025-12-15"
---

This lets you:

• Identify AI translations vs manual
• Track source file changes
• Know which model was used

Environment variables

Variable	Default	Description
OPENAI_API_KEY	required	OpenAI API key
AI_TRANSLATE_MODEL	gpt-4.1	Model override
AI_TRANSLATE_CONTENT_DIR	src/content/pages	Content directory

Supported models & pricing

Cost estimates use current OpenAI pricing (USD per 1M tokens):

Model	Input	Output	Best for
gpt-4.1	$2.00	$8.00	Default, best quality
gpt-4.1-mini	$0.40	$1.60	Good balance
gpt-4.1-nano	$0.10	$0.40	Budget option
gpt-4o	$2.50	$10.00	High quality
gpt-4o-mini	$0.15	$0.60	Very cheap
gpt-3.5-turbo	$0.50	$1.50	Legacy, fast

For high-volume translation, gpt-4.1-mini or gpt-4o-mini offer good quality at lower cost.

File structure

The translator follows Astro i18n conventions:

src/content/pages/
├── index.mdx           # Default locale (en)
├── about.mdx           # Default locale (en)
├── ru/
│   ├── index.mdx       # Russian (ai or manual)
│   └── about.mdx       # Russian (ai or manual)
└── de/
    ├── index.mdx       # German
    └── about.mdx       # German

Alternates support

If source file has alternates, translated files get correct permalink:

# Source: about.mdx
alternates:
  ru: o-nas
  de: ueber-uns

Generated ru/about.mdx will have permalink: o-nas.

Related

• website-core-template — i18n-ready Astro starter template
• astro-content-ai-enhancer — AI assistant that enhances raw Markdown into structured, well-formatted pages

Author

Built by Affiliate.FM — independent media and open-source tools for affiliate, performance, and digital marketing.

License

MIT