Vite Plugin

@babelize/vite scans your source code for babelize() calls and generates a lockfile at build time. No manual configuration — just add the plugin and run your build.

Setup

// vite.config.ts
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import babelize from "@babelize/vite";

export default defineConfig({
  plugins: [
    react(),
    babelize({
      locales: ["ja", "fr", "de"],
    }),
  ],
});

How It Works

The plugin hooks into Vite's build pipeline and performs these steps:

Scans every source file using AST analysis via Babel parser
Extracts all unique strings from babelize("..."), babelize.p(...), and <BabelizeTag> calls
Translates them via the Babelize API for each configured locale
Generates babelize-lock.json in your project root

Source files
    │
    ▼
AST Scanner ──→ babelize("Welcome")
                babelize.p("{count} item", ...)
                <BabelizeTag template="..." />
    │
    ▼
Babelize API ──→ Translates for each locale
    │
    ▼
babelize-lock.json

What Gets Scanned

Static strings — string literals passed to babelize():

babelize("Welcome")                         // ✓ extracted
babelize("Hello {name}", { name })          // ✓ extracted (variables stripped)
babelize(dynamicVariable)                   // ✗ skipped

For dynamic strings that can't be statically analyzed, the SDK fetches translations at runtime. The lockfile provides all pre-known strings, and the API handles the rest.

Plural forms — from babelize.p() and babelize.plural():

babelize.p("{count} item", "{count} items", items.length)
// ✓ extracted as plural with forms ["one", "other"]

babelize.plural({
  one: "{count} item",
  other: "{count} items",
}, { count })
// ✓ extracted with all explicit forms

Tag templates — from <BabelizeTag>:

<BabelizeTag
  template="Welcome to {Babelize}, a platform {for localization}"
  segments={{ Babelize: <strong>Babelize</strong> }}
/>
// ✓ template extracted as a single translation unit

Lockfile Output

The generated babelize-lock.json is placed in your project root:

{
  "version": 1,
  "meta": {
    "generatedAt": "2026-07-30T12:00:00Z",
    "locales": ["ja", "fr", "de"],
    "totalStrings": 42
  },
  "strings": {
    "Welcome": {
      "ja": "ようこそ",
      "fr": "Bienvenue"
    }
  },
  "plurals": {
    "{count} item": {
      "forms": ["one", "other"],
      "fr": {
        "one": "{count} élément",
        "other": "{count} éléments"
      }
    }
  }
}

Virtual Module

The plugin exposes a virtual module virtual:babelize-lockfile that serves the lockfile content:

import lockfile from "virtual:babelize-lockfile";

lockfile && babelize.loadLockfile(lockfile);

Add a type declaration for TypeScript:

// src/vite-env.d.ts
declare module "virtual:babelize-lockfile" {
  const data: {
    version: number;
    strings: Record<string, Record<string, string>>;
    plurals?: Record<string, any>;
  };
  export default data;
}

Options

interface BabelizePluginOptions {
  apiKey?: string;         // API key (default: BABELIZE_API_KEY env)
  locales?: string[];      // Target locales
  output?: string;          // Lockfile path (default: "babelize-lock.json")
  functionName?: string;    // Function name to scan (default: "babelize")
  apiUrl?: string;          // API endpoint
  mock?: boolean;           // Fake translations for testing
}

Mock Mode

For testing without an API key, enable mock mode. The plugin generates fake translations by appending the locale code:

babelize({
  locales: ["ja", "fr"],
  mock: true,
});

// Result: "Welcome" → "Welcome [ja]", "Welcome [fr]"