solid-translate weekly downloads statistics

solid-translate

AI-powered i18n for SolidJS — full feature parity with General Translation, but open-source and BYOK (bring your own API key).

Write your app in one language. Wrap text in <T>. Get translations generated automatically at build time. No JSON key management. No external service required.

Features

• <T> Component — wrap any text for translation. Source text = key (no JSON wrangling)
• <Var> — protect dynamic content from translation
• <Num> — locale-aware number formatting via Intl.NumberFormat
• <Currency> — locale-aware currency formatting
• <DateTime> — locale-aware date/time formatting
• <Plural> — CLDR plural rules (zero/one/two/few/many/other)
• <LocaleSelector> — drop-in locale picker component
• AI Context — context prop for disambiguation ("Save" = save file vs. save money)
• Auto Locale Detection — detects from navigator.languages when locale prop is omitted
• msg() — mark strings for extraction outside of JSX
• CLI Tool — translate JSON, Markdown, and MDX files from the command line
• check Command — CI freshness gate, no AI calls (exit 1 when translations are stale)
• Vite Plugin — build-time translation with smart change detection
• Lazy Locale Chunks — virtual:solid-translate/lazy code-splits each locale, loads on demand without suspending
• Locale Persistence — opt-in persistLocale remembers the user's choice in localStorage
• GitHub Action — omniaura/solid-translate@v1 for CI/CD translation automation
• BYOK — use any Vercel AI SDK provider (OpenRouter, OpenAI, Anthropic, Google, etc.)

Install

bun add solid-translate
bun add -d ai @ai-sdk/openai  # or any AI SDK provider

Quick Start

1. Configure the Vite plugin

// vite.config.ts
import { defineConfig } from "vite";
import solidPlugin from "vite-plugin-solid";
import { solidTranslate } from "solid-translate/vite";
import { createOpenAI } from "@ai-sdk/openai";

const openrouter = createOpenAI({
  baseURL: "https://openrouter.ai/api/v1",
  apiKey: process.env.OPENROUTER_API_KEY,
});

export default defineConfig({
  plugins: [
    solidPlugin(),
    solidTranslate({
      sourceLocale: "en",
      targetLocales: ["es", "fr", "de", "ja"],
      localesDir: "./src/locales",
      model: openrouter("openai/gpt-4o-mini"),
      autoExtract: true, // auto-discover <T> and msg() strings
    }),
  ],
});

2. Write your app

import { TranslationProvider, T, Var, Num, Plural, useTranslation, LocaleSelector } from "solid-translate";
import translations from "virtual:solid-translate";

function App() {
  return (
    <TranslationProvider
      sourceLocale="en"
      translations={translations}
      // locale="es"  ← optional! auto-detects from browser if omitted
    >
      <Page />
    </TranslationProvider>
  );
}

function Page() {
  const { t } = useTranslation();
  const [count, setCount] = createSignal(3);
  const userName = () => "Alice";

  return (
    <div>
      <h1><T>Welcome to our app!</T></h1>

      {/* Dynamic content protected with <Var> */}
      <p><T>Hello <Var>{userName()}</Var>, nice to see you!</T></p>

      {/* AI context for disambiguation */}
      <button><T context="save a document to disk">Save</T></button>

      {/* Explicit key */}
      <a><T id="nav.home">Home</T></a>

      {/* Interpolation */}
      <p>{t("items.count", { count: count() })}</p>

      {/* Pluralization */}
      <Plural n={count()}
        zero="No items in your cart"
        one="1 item in your cart"
        other={`${count()} items in your cart`}
      />

      {/* Locale-aware number */}
      <p>Total: <Num>{1234567.89}</Num></p>

      {/* Locale switcher */}
      <LocaleSelector labels={{ en: "English", es: "Español", fr: "Français" }} />
    </div>
  );
}

3. Build

bun run build

On the first build, the plugin generates translation files:

src/locales/
├── en.json                    # Source (auto-generated or manual)
├── es.json                    # AI-generated
├── fr.json                    # AI-generated
├── de.json                    # AI-generated
├── ja.json                    # AI-generated
└── .solid-translate.lock      # Change tracking

On subsequent builds, only changed/new keys are re-translated. Check everything into git.

API Reference

Components

<T> — Translatable Text

// Source text as key (no JSON file entry needed)
<T>Hello world</T>

// Explicit key
<T id="greeting">Hello world</T>

// With interpolation
<T params={{ name: userName() }}>Hello {{name}}</T>

// AI context for disambiguation
<T context="financial institution, not river bank">Bank</T>

// Mixed JSX with Var
<T>Welcome <Var>{userName()}</Var>, you have <Num>{count()}</Num> items</T>

<Var> — Variable Protection

Marks dynamic content that should NOT be translated. When used inside <T>, the surrounding text is translated but <Var> content is preserved.

<T>Hello <Var>{userName()}</Var></T>
// Spanish: "Hola {userName()}"

<Num> — Number Formatting

Locale-aware number formatting using Intl.NumberFormat.

<Num>{1000000}</Num>                              // "1,000,000" (en) / "1.000.000" (de)
<Num options={{ style: "percent" }}>{0.42}</Num>   // "42%"
<Num options={{ notation: "compact" }}>{1500}</Num> // "1.5K"

<Currency> — Currency Formatting

<Currency currency="USD">{29.99}</Currency>    // "$29.99" (en-US) / "29,99 $US" (fr)
<Currency currency="EUR">{1000}</Currency>     // "€1,000.00" (en) / "1.000,00 €" (de)

<DateTime> — Date/Time Formatting

<DateTime>{new Date()}</DateTime>
<DateTime options={{ dateStyle: "long" }}>{new Date()}</DateTime>
<DateTime options={{ hour: "numeric", minute: "numeric" }}>{Date.now()}</DateTime>

<Plural> — Pluralization (CLDR)…