About

Better Translate is a type-safe i18n toolkit for TypeScript. Write your translation config once and it works across Next.js, Astro, React, TanStack Router, Node, Bun, and Expo — same API, same types, same experience everywhere. A built-in CLI generates translated locale files using any AI provider or local Ollama models, so you ship multilingual apps without manual work.

Why Better Translate

i18n in TypeScript projects is usually an afterthought. You wire up a library, scatter translation keys across your codebase, and cross your fingers that nothing drifts out of sync. Better Translate treats translations as first-class TypeScript: keys are inferred, interpolations are typed, and the CLI handles generation so you never write a locale file by hand again.

Quick Start

# Install the CLI globally
npm install -g @better-translate/cli

# Install the core package (or a framework adapter)
npm install @better-translate/core

Create a better-translate.config.ts at the root of your project:

import { createGoogleGenerativeAI } from "@ai-sdk/google";
import { defineConfig } from "@better-translate/cli";

const google = createGoogleGenerativeAI({ apiKey: process.env.GOOGLE_API_KEY });

export default defineConfig({
  model: google("gemini-2.0-flash"),
  defaultLocale: "en",
  targetLocales: ["es", "fr", "ja"],
  messagesDir: "./messages",
});

Extract source strings and generate all locale files:

bt extract   # scans source files and updates messages/en.json
bt generate  # translates into every target locale

Use translations in your app:

import { configureTranslations, createTranslationHelpers } from "@better-translate/core";
import en from "./messages/en.json";
import es from "./messages/es.json";

const translator = await configureTranslations({
  availableLocales: ["en", "es"] as const,
  defaultLocale: "en",
  messages: { en, es },
});

const { t } = createTranslationHelpers(translator);

t("hero.title")                        // fully typed, autocomplete works
t("hero.greeting", { params: { name } }) // interpolation is type-checked
t("hero.title", { locale: "es" })      // per-call locale override

Framework Support

Framework / Runtime	Package
Next.js (App Router)	@better-translate/nextjs
Astro	@better-translate/astro
React	@better-translate/react
TanStack Router / Start	@better-translate/tanstack-router
Expo (React Native)	@better-translate/react
Node.js	@better-translate/core
Bun	@better-translate/core
Markdown / MDX	@better-translate/md

Key Features

• Type-safe by default — Full TypeScript inference on translation keys and interpolation variables. Typos and missing keys are compile errors.
• Autocomplete everywhere — Your editor knows every key in your messages object from the moment you type t(".
• Same config, every environment — Write once, run anywhere. Next.js, Astro, React, Node — identical API.
• CLI toolchain — bt extract pulls source strings out of your code. bt generate calls your AI model and writes every locale file.
• Bring your own model — Pass any AI SDK language model to the config: OpenAI, Gemini, Claude, or a local Ollama model.
• Locale switching — Switch locales at runtime without a page reload. Per-call overrides render any locale on demand.
• RTL support — Built-in right-to-left layout utilities for Arabic, Hebrew, and other RTL languages.

Documentation

• Installation
• Core
• CLI
• Next.js
• React
• Astro
• TanStack Router
• Expo
• MD & MDX

Contributing

Better Translate is free and open source under the MIT License. Contributions are welcome.

• Contributing guide
• Report an issue

Security

If you discover a security vulnerability, please see SECURITY.md for responsible disclosure instructions.

License

MIT