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

| Option | Type | Default | Description | |--------|------|---------|-------------| | enabled | boolean | false | Enable/disable auto-translate | | provider | string | 'openai' | LLM provider to use | | defaultLocale | string | auto / 'es' | Source language code (auto-detected from i18n) | | locales | LocaleConfig[] | auto / [] | Target locales (auto-detected from i18n, excludes defaultLocale) | | outputPath | string | auto / 'i18n/locales' | Output directory for JSON files (auto-detected from i18n langDir) | | backupPath | string | - | Backup directory (optional) | | targetFolders | string[] | ['components', 'pages', ...] | Folders to scan | | rootFiles | string[] | [] | Root files to scan (e.g., app.vue) | | fileExtensions | string[] | ['.vue', '.ts', '.js'] | File types to scan | | enableCache | boolean | true | Only translate new keys | | cleanOrphaned | boolean | false | Remove unused translations | | backupBeforeClean | boolean | true | Backup before cleaning | | maxBackups | number | 3 | Max backups per locale |

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

Once configured, the module will:

1. On build: Scan source code and translate new keys
2. On dev watch: Re-translate when source files change

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:

| Setting | Auto-detected from | Fallback | |---------|-------------------|----------| | defaultLocale | i18n.defaultLocale | 'es' | | locales | i18n.locales (excludes defaultLocale) | [] | | outputPath | i18n.langDir | 'i18n/locales' |

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

| Provider | Cost | Speed | Offline | Best For | |----------|------|-------|---------|----------| | OpenAI | $$ | Fast | No | Production, highest quality | | Anthropic | $$ | Fast | No | Production alternative | | Gemini | $ | Fast | No | Budget-conscious | | Groq | $ | Very Fast | No | Speed + economy | | Ollama | Free | Slow* | Yes | Development, privacy |

*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