Translator

Translator is the single, consistent interface
for all translation operations across frameworks and environments.

Translator can only be accessed through the following entry points:

  • useTranslator() (Client)
  • getTranslator() (Server)

Translator methods are designed to be accessed via destructuring.
This interface shape is a deliberate design choice in Intor, enabling static analysis (e.g. CLI).

const { t } = useTranslator(...);
const { t } = await getTranslator(...);

In some request-scoped server environments, the Translator may be bound to the execution context for convenient downstream access.

Methods

t()

Resolves a translation key and returns the corresponding message value.
Interpolation values can be provided as the second argument.

// messages: { en: { hello: "Hello, {name}" } }

t("hello"); // → "Hello, {name}"

t("hello", { name: "Intor" }); // → "Hello, Intor"

tRich()

Resolves a translation key while preserving its semantic structure, returning a composable result.
The second argument defines structure mappings, and the third provides interpolation values.

The return type depends on the runtime environment, while the API surface remains identical.

// ――― Returns ReactNode ―――

// messages: { en: { hello: "Hello, <a>{name}</a>" } }

tRich("hello"); // → Hello, <a>{name}</a>

tRich("hello", { a: (children) => <a href="/">{children}</a> }, { name: "Intor" });
// → Hello, <a href="/">Intor</a>
// ――― Returns VNode children ―――

// messages: { en: { hello: "Hello, <a>{name}</a>" } }

tRich("hello"); // → ["Hello, ", VNode]

tRich("hello", { a: (children) => h("a", { href: "/" }, children) }, { name: "Intor" });
// → ["Hello, ", VNode]
// ――― Returns HTML string ―――

// messages: { en: { hello: "Hello, <a>{name}</a>" } }

{@html $tRich("hello")} // → 'Hello, <a>{name}</a>'

{@html $tRich("hello", { a: (children) => `<a href="/">${children}</a>` }, { name: "Intor" })}
// → 'Hello, <a href="/">Intor</a>'
// ――― Returns HTML string ―――

// messages: { en: { hello: "Hello, <a>{name}</a>" } }

tRich("hello") // → 'Hello, <a>{name}</a>'

tRich("hello", { a: (children) => `<a href="/">${children}</a>` }, { name: "Intor" })
// → 'Hello, <a href="/">Intor</a>'

Note
tRich() preserves the structure of the translation content.
Ensure that the translation content and all related inputs are trusted.

hasKey()

Checks whether the specified translation key exists.
By default, the current locale is used; a target locale can be specified explicitly.

// messages: { en: { hello: "Hello" }, fr: {} }

hasKey("hello"); // → true

hasKey("hello", "fr"); // → false

setLocale()

Only available in useTranslator

Switches the active locale.

setLocale("en")

In SSR frameworks, locale changes should be handled through the navigation tools instead of setLocale().

On this page