API reference

This page lists the developer-facing APIs you configure or import from Better Translation.

Vite plugin

Import betterTranslation from better-translation/vite.

betterTranslation({
  locales: ["en", "es", "fr"],
  defaultLocale: "en",
})

Local runtime

Local mode writes flat Locale value files into your app and generates a local better-translation/messages loader.

type LocalRuntime = {
  type: "local"
  target?: "module" | "public"
  output?: string
  basePath?: string
  editor?: boolean | LocalEditorOptions
} & (
  | {
      translate: TranslateFn
      translationBatchSize?: number
    }
  | {
      translate?: undefined
      translationBatchSize?: never
    }
)

translationBatchSize is available only when translate is provided. The plugin persists the translation cache and Runtime bundles after each completed batch.

Translation callback

TranslateFn receives missing Messages for one Locale and returns any completed Locale values keyed by lookup id.

type TranslateFn = (
  messages: Array<{
    id: string
    text: string
    meta: {
      id?: string
      context?: string
    }
    placeholders: string[]
    sources: Array<{
      file: string
      kind: "call" | "component"
      marker: string
    }>
  }>,
  locale: string,
) => Promise<Record<string, string>>

The returned record may omit a Message when no value was produced. Every returned value must preserve the source Variable placeholders and numbered Rich-text slots. The plugin rejects incompatible results before adding them to the cache or Runtime bundle.

Local editor

The local editor is only served during vite dev and only for runtime.type: "local".

type LocalEditorOptions = {
  enabled?: boolean
  path?: string
  open?: boolean
}

betterTranslation({
  locales: ["en", "es", "fr"],
  defaultLocale: "en",
  runtime: {
    type: "local",
    editor: {
      path: "/translations",
      open: true,
    },
  },
})

Remote runtime

Remote mode syncs the Manifest to the hosted platform and generates a branch-aware runtime loader.

type RemoteRuntime = {
  type: "remote"
  endpoint?: string
  projectId: string
  apiKey?: string
  branch?: "auto" | string
  dev?: {
    offline?: boolean
  }
}

Translation options

T, useT, getT, and createT accept the same message options.

type TranslateOptions = {
  id?: string
  context?: string
}

React runtime

Import these from better-translation/react.

<T context="billing button">
  Pay <Var amount="$10" /> now
</T>

const t = useT()

t("Invite {email}", { email: user.email }, { context: "invitation title" })

Svelte runtime

Import these from better-translation/svelte.

<script>
  import { T, Var } from "better-translation/svelte"
</script>

<T>
  Hello <Var name="name" value={user.name} />
</T>

Rich-text contract

Rich text is part of T; it is not a separate package export. Put supported native inline elements or source-owned React and Svelte components directly inside the marker. The Vite plugin represents them as numbered Rich-text slots in the Message, and each runtime renders translated children through the exact authored renderer while retaining its props and behavior.

Consumer apps do not import a Message parser or structure validator, and they do not register tag callbacks. Those are private plugin/runtime details. A translated Locale value must retain the source Variable placeholders, numbered slots, paired/self-closing form, and parent topology. When that contract is not met, T falls back to its authored source content rather than interpreting the value as HTML.

The plugin injects private transform props needed by the runtime. They are not author-facing T options; Consumer apps should use only id, context, children, and Var.

Runtime translator

Import createT from better-translation/runtime.

Generated messages module

Import these from better-translation/messages. The Vite plugin generates this module from your runtime config.

AI translation helper

Import createAiTranslate from better-translation/ai. Use it as local runtime translate in local mode.

import { createAiTranslate } from "better-translation/ai"

betterTranslation({
  locales: ["en", "es", "fr"],
  defaultLocale: "en",
  runtime: {
    type: "local",
    translate: createAiTranslate({
      prompt: "Friendly, concise product UI copy.",
    }),
  },
})