i18n-email

`createI18nEmail(config)`

Creates and returns an i18n-email client.

import { createI18nEmail } from "i18n-email";

const i18nEmail = createI18nEmail(config);

`I18nEmailConfig`

I18nEmailConfig is a discriminated union. Choose exactly one backend:

OpenAI (default)

Option	Type	Required	Default	Description
`openaiApiKey`	`string`	Yes	—	OpenAI API key
`model`	`string`	No	`"gpt-4o"`	OpenAI model name
`baseURL`	`string`	No	—	Override the API base URL (Azure, Groq…)
`maxRetries`	`number`	No	`2`	Retries on transient errors

Vercel AI SDK

Set model to any Vercel AI SDK LanguageModel (e.g. openai("gpt-4o") from @ai-sdk/openai). openaiApiKey, baseURL, and maxRetries are not available — the provider handles authentication.

Set adapter to any TanStack AI TextAdapter (e.g. createOpenaiChat(...) from @tanstack/ai-openai). openaiApiKey, baseURL, and maxRetries are not available — the adapter handles authentication.

Shared options

Option	Type	Required	Default	Description
`batchSize`	`number`	No	`50`	Max strings per API request
`cache`	`CacheProvider`	No	—	Cache adapter to skip redundant calls
`onTranslate`	`(info) => void`	No	—	Hook called after every translate call

Returns

{
  translate: (options: TranslateOptions) => Promise<TranslateResult>;
}

`translate(options)`

Translates an email's subject and body to the target locale.

const result = await i18nEmail.translate(options);

`TranslateOptions`

Exactly one of react or html must be provided.

Option	Type	Required	Description
`locale`	`string`	Yes	BCP 47 locale code of the target language (e.g. `"fr"`, `"ar"`, `"zh-TW"`)
`subject`	`string`	Yes	Email subject line to translate
`react`	`ReactElement`	One of	React Email component — rendered to HTML before translation
`html`	`string`	One of	Raw HTML string to translate directly

`TranslateResult`

interface TranslateResult {
  subject: string;
  html: string;
}

Field	Description
`subject`	Translated subject line
`html`	Translated HTML body

If the source email is already in the target locale, the original subject and html are returned unchanged.

`CacheProvider`

interface CacheProvider {
  prefix?: string;
  get: (key: string) => Promise<string | null>;
  set: (key: string, value: string) => Promise<void>;
}

Member	Type	Description
`prefix`	`string`	Optional string prepended to every cache key
`get`	`(key: string) => Promise<string \| null>`	Returns the cached value, or `null` on a miss
`set`	`(key: string, value: string) => Promise<void>`	Stores a value under the given key

Cache keys are SHA-256 hashes of the concatenated HTML, subject, and locale. See Caching for adapter examples.

Exported types

All types are available as named exports from i18n-email:

import type {
  I18nEmailConfig,
  AiLanguageModel,
  TanstackAiTextAdapter,
  CacheProvider,
  TranslateOptions,
  TranslateOptionsReact,
  TranslateOptionsHtml,
  TranslateResult,
  TranslationResponse,
  TranslateCallbackInfo,
} from "i18n-email";

Errors

The library throws a plain Error with a descriptive message in these cases:

Situation	Message prefix
No `openaiApiKey` when using string model	`i18n-email: openaiApiKey is required when...`
`ai` package not installed for AI SDK model	`i18n-email: The "ai" package is required...`
`@tanstack/ai` not installed for TanStack model	`i18n-email: The "@tanstack/ai" package is required...`
React component fails to render	`i18n-email: Failed to render React component:`
OpenAI returns an empty response	`i18n-email: OpenAI returned an empty response`
OpenAI returns malformed JSON	`i18n-email: OpenAI returned malformed JSON:`
Response shape is unexpected	`i18n-email: Unexpected response shape from OpenAI:`
Translation count doesn't match input	`i18n-email: Translation count mismatch.`

API Reference