nuxt-auto-translate

nuxt-auto-translate

Automatic i18n translations for Nuxt using LLMs (OpenAI, Anthropic/Claude, Gemini, Groq, Ollama).

Scans your source code for $t() calls, extracts translation keys, and automatically translates them using your preferred AI provider.

• Release Notes

Features

• Multiple LLM Providers: OpenAI, Anthropic (Claude), Google Gemini, Groq, and Ollama (local)
• Automatic Scanning: Detects $t() calls in .vue, .ts, and .js files
• Smart Caching: Only translates new keys, preserves existing translations
• Batch Translation: Efficient batch processing for large translation sets
• Validation: Validates that variables {name} and HTML tags are preserved
• Orphan Cleanup: Optionally removes translations no longer in use
• Backup System: Automatic backups before making changes

Quick Setup

Install the module:

npm install nuxt-auto-translate
# or
pnpm add nuxt-auto-translate

Install your preferred provider SDK (only install what you need):

# OpenAI (default)
npm install openai

# Anthropic (Claude)
npm install @anthropic-ai/sdk

# Google Gemini
npm install @google/generative-ai

# Groq or Ollama - uses openai package
npm install openai

Add the module to your nuxt.config.ts:

With @nuxtjs/i18n (recommended)

When used alongside @nuxtjs/i18n, the module automatically detects defaultLocale, locales, and outputPath from your i18n config — no duplication needed:

export default defineNuxtConfig({
  modules: [
    '@nuxtjs/i18n',
    'nuxt-auto-translate',
  ],

  i18n: {
    defaultLocale: 'es',
    locales: [
      { code: 'es', name: 'Español', file: 'es.json' },
      { code: 'en', name: 'English', file: 'en.json' },
    ],
  },

  // Only configure what's specific to auto-translate
  autoTranslate: {
    enabled: true,
    provider: 'openai',
  },
})

You can still override any auto-detected value explicitly if needed (e.g., a different outputPath).

Standalone (without @nuxtjs/i18n)

export default defineNuxtConfig({
  modules: ['nuxt-auto-translate'],

  autoTranslate: {
    enabled: true,
    provider: 'openai',
    defaultLocale: 'es',
    locales: [
      { code: 'en', name: 'English' },
    ],
    outputPath: 'i18n/locales',
  },
})

Set your API key in .env:

NUXT_AUTO_TRANSLATE_OPENAI_KEY=sk-your-key-here

Configuration

Module Options

Environment Variables

# Select provider (optional, can be set in config)
NUXT_AUTO_TRANSLATE_PROVIDER=openai

# OpenAI
NUXT_AUTO_TRANSLATE_OPENAI_KEY=sk-xxx
NUXT_AUTO_TRANSLATE_OPENAI_MODEL=gpt-4o-mini

# Anthropic
NUXT_AUTO_TRANSLATE_ANTHROPIC_KEY=sk-ant-xxx
NUXT_AUTO_TRANSLATE_ANTHROPIC_MODEL=claude-3-5-haiku-20241022

# Gemini
NUXT_AUTO_TRANSLATE_GEMINI_KEY=AIzaSyxxx
NUXT_AUTO_TRANSLATE_GEMINI_MODEL=gemini-2.0-flash-exp

# Groq
NUXT_AUTO_TRANSLATE_GROQ_KEY=gsk_xxx
NUXT_AUTO_TRANSLATE_GROQ_MODEL=llama-3.3-70b-versatile

# Ollama (local - no API key needed)
NUXT_AUTO_TRANSLATE_OLLAMA_MODEL=llama3.2
NUXT_AUTO_TRANSLATE_OLLAMA_BASE_URL=http://localhost:11434/v1

Locale Configuration

interface LocaleConfig {
  code: string  // e.g., 'en', 'es', 'fr'
  name: string  // e.g., 'English', 'Español', 'Français'
  file?: string // Optional custom filename
}

Usage

There are two ways to run translations:

1. On demand (recommended) — run the CLI when you finish a task. Decoupled from dev/build, so intermediate $t() edits don't trigger translations or churn your JSON files.
2. On build — with enabled: true, the module translates during build:before.
3. On dev watch (opt-in) — set watch: true to re-translate on every source file change during nuxt dev.

CLI (on-demand)

The package ships a nuxt-auto-translate binary. Add a script:

{
  "scripts": {
    "translate": "nuxt-auto-translate"
  }
}

pnpm translate

It reads your autoTranslate + @nuxtjs/i18n config from nuxt.config, loads .env for the provider key, translates new keys once, and exits. Review the JSON diff and commit it like any other file. The module itself can stay enabled: false — the CLI runs independently.

In your components

<template>
  <h1>{{ $t('Welcome to our app') }}</h1>
  <p>{{ $t('Hello {name}, you have {count} messages', { name, count }) }}</p>
</template>

Output

The module generates JSON files in your outputPath:

// i18n/locales/es.json (default locale - key = value)
{
  "Welcome to our app": "Welcome to our app",
  "Hello {name}, you have {count} messages": "Hello {name}, you have {count} messages"
}

// i18n/locales/en.json (translated)
{
  "Welcome to our app": "Bienvenido a nuestra app",
  "Hello {name}, you have {count} messages": "Hola {name}, tienes {count} mensajes"
}

@nuxtjs/i18n Integration

When @nuxtjs/i18n is installed, the module auto-detects the following from your i18n config:

How it works:

• The module reads nuxt.options.i18n during setup — this config is available regardless of module order in the modules array
• The defaultLocale is treated as the source language and excluded from translation targets
• Explicit values in autoTranslate always take precedence over auto-detected values
• If @nuxtjs/i18n is not installed, all values must be configured manually

Provider Comparison

*Ollama speed depends on your hardware

Development

# Install dependencies
npm install

# Generate type stubs
npm run dev:prepare

# Develop with the playground
npm run dev

# Build the playground
npm run dev:build

# Run ESLint
npm run lint

# Run Vitest
npm run test
npm run test:watch

# Release new version
npm run release

License

MIT License