intl-ai

Appearance

Getting Started ​

This guide will help you set up @intl-ai/unplugin in your project.

Installation ​

Prerequisites ​

  • Node.js 22+
  • A package manager: npm, pnpm, or yarn
  • An AI model provider (see AI Model Setup for options)

Install the Package ​

sh
npm install @intl-ai/unplugin
sh
pnpm add @intl-ai/unplugin
sh
yarn add @intl-ai/unplugin
sh
bun add @intl-ai/unplugin

For Next.js Projects ​

Install the @intl-ai/next package in your Next.js project:

sh
npm install @intl-ai/next
sh
pnpm add @intl-ai/next
sh
yarn add @intl-ai/next
sh
bun add @intl-ai/next

Quick Start ​

1. Create Configuration File ​

Create an intl-ai.config.ts file in your project root. If you do not have a local model or cloud API key, you can use OpenRouter's free tier with no account setup beyond an API key.

Local model (LM Studio) ​

typescript
import { createOpenAICompatible } from "@ai-sdk/openai-compatible";

const lmstudio = createOpenAICompatible({
  name: "lmstudio",
  baseURL: "http://127.0.0.1:1234/v1",
});

export default {
  model: lmstudio("your-model-name"),
  defaultLocale: "en",
  locales: ["en", "de", "es", "fr"],
  localeDir: "./locales",
};

Cloud model (OpenRouter free tier) ​

typescript
import { createOpenAICompatible } from "@ai-sdk/openai-compatible";

const openrouter = createOpenAICompatible({
  name: "openrouter",
  baseURL: "https://openrouter.ai/api/v1",
});

export default {
  model: openrouter("google/gemini-2.0-flash-exp:free"),
  defaultLocale: "en",
  locales: ["en", "de", "es", "fr"],
  localeDir: "./locales",
};

See AI model setup for all provider options.

Key Configuration:

  • model: Your AI model instance (see AI model setup for other providers)
  • defaultLocale: The primary language for your application
  • locales: Array of supported language codes
  • localeDir: Directory where translation files will be stored

2. Set Up Your Bundler ​

typescript
import { defineConfig } from "vite";
import intlAi from "@intl-ai/unplugin/vite";

export default defineConfig({
  plugins: [intlAi()],
});
javascript
const IntlAiPlugin = require("@intl-ai/unplugin/webpack");

module.exports = {
  plugins: [new IntlAiPlugin()],
};

See Build systems for Next.js, Rollup, esbuild, Rspack, Rolldown, Farm, and more.

3. Create Directory and Translation Files ​

Create the directory specified in your config (default: ./locales), then add your first translation file for the default locale:

locales/en.json:

json
{
  "greeting": "Hello, {name}!",
  "welcome": "Welcome to our application",
  "description": "This is a sample translation"
}

Supported Bundlers ​

@intl-ai/unplugin works with all major bundlers. See Build systems for dedicated setup guides:

  • Vite - Modern, fast build tool
  • Webpack - Industry standard bundler
  • Rollup - Flexible module bundler
  • esbuild - Extremely fast JavaScript bundler
  • Rspack - Rust-based, webpack-compatible bundler
  • Rolldown - Rust-powered Rollup-compatible bundler
  • Farm - Rust-based web build tool
  • Next.js - React framework with Turbopack bridge

Verify Installation ​

To verify everything is working:

  1. Start your development server: npm run dev, pnpm dev, or yarn dev
  2. Check that your bundler loads without errors and translation files are being processed
  3. Verify translations render correctly in your application

If you encounter issues, check the AI model setup guide to ensure your model provider is configured correctly.