Skip to main content

Vite Plugin Integration

Translate locale files at build time, with caching, as part of your normal Vite build.

View on GitHubView on npm

Features

Runs during build — no runtime cost and no key in the browser
Caches results so unchanged strings never cost twice
Regional fallback (pt-BR → pt)
Falls back to the source language if a translation fails
Works with any i18n runtime that reads JSON

Prerequisites

  • 1.Vite 4 or 5
  • 2.An Anthropic or OpenAI API key of your own

Installation

npm install -D vite-plugin-shipi18n

Configuration

Set your own LLM key in the environment. It is read at translation time and never written to disk or sent anywhere except your provider:

# .env — never commit this
ANTHROPIC_API_KEY=your-key-here

Use OPENAI_API_KEY instead if you pass --provider openai.

Usage

shipi18n({ provider: 'anthropic', targetLanguages: ['es', 'fr'] })

Examples

vite.config.js

import { defineConfig } from 'vite'
import shipi18n from 'vite-plugin-shipi18n'

export default defineConfig({
  plugins: [
    shipi18n({
      provider: 'anthropic',            // or 'openai'
      targetLanguages: ['es', 'fr', 'de'],
      sourceDir: 'public/locales/en',
      outputDir: 'public/locales',
      // apiKey defaults to ANTHROPIC_API_KEY / OPENAI_API_KEY
    }),
  ],
})

Skip translation when no key is present

// Gate the PLUGIN, not the language list — an empty
// targetLanguages throws rather than skipping.
const translate = process.env.ANTHROPIC_API_KEY
  ? [shipi18n({ provider: 'anthropic', targetLanguages: ['es', 'fr', 'de'] })]
  : []

export default defineConfig({
  plugins: [...translate],
})

Best Practices

  • Leave caching on. A rebuild with unchanged strings makes no model calls at all.
  • Commit the generated locale files so production builds never depend on a model being reachable.
  • Keep the key in CI secrets — the plugin runs at build time, so it never reaches the browser bundle.

Troubleshooting

Translations are not regenerating

That is the cache doing its job. Delete node_modules/.cache/vite-plugin-shipi18n to force a full re-translation.

Build fails with a missing key error

Set ANTHROPIC_API_KEY (or OPENAI_API_KEY) in the build environment, or set targetLanguages to an empty array to skip translation in that environment.

Need help? Read the docs

View on GitHub