API Reference

TranslationsProvider

The provider component that wraps your application.

import { TranslationsProvider } from "@onruntime/translations/react";

<TranslationsProvider
  locale="en"
  locales={{ en, fr }}
  fallbackLocale="en"
>
  {children}
</TranslationsProvider>

Props

useTranslation

Hook for accessing translations in client components.

const { t, locale, setLocale } = useTranslation("namespace");

Parameters

Returns

Example

const { t, locale, setLocale } = useTranslation("common");

// Basic usage
t("greeting");  // "Hello"

// With variables
t("greeting_name", { name: "John" });  // "Hello, John!"

// Nested keys
t("nav.home");  // "Home"

// Change locale
setLocale("fr");

getTranslation

Async function for accessing translations in server components (Next.js).

const { t } = await getTranslation("namespace");

Parameters

Returns

Example

// Server Component
export default async function Page() {
  const { t } = await getTranslation("common");

  return <h1>{t("title")}</h1>;
}

Link Component

Locale-aware Link component for Next.js.

import { Link } from "@onruntime/translations/next";

<Link href="/about">About</Link>

Props

All props from Next.js Link component, plus:

Example

// Uses current locale
<Link href="/about">About</Link>

// Force specific locale
<Link href="/about" locale="fr">À propos</Link>

Translation Function (t)

The t function is used to retrieve translated strings.

Signature

t(key: string, variables?: Record<string, string | number>): string

Parameters

Variable Interpolation

{
  "greeting": "Hello, {name}!",
  "items": "You have {count} items"
}

t("greeting", { name: "Alice" });  // "Hello, Alice!"
t("items", { count: 5 });          // "You have 5 items"

Plurals

A number that changes the wording goes through a plural argument rather than a second key:

{
  "battles": "{count, plural, one {# battle} other {# battles}}"
}

t("battles", { count: 1 });  // "1 battle"
t("battles", { count: 4 });  // "4 battles"

# stands for the count. The branch is chosen by Intl.PluralRules in the locale being read, so each language writes the branches it needs:

{
  "battles": "{count, plural, one {# bitwa} few {# bitwy} many {# bitew} other {# bitwy}}"
}

t("battles", { count: 1 });  // "1 bitwa"
t("battles", { count: 3 });  // "3 bitwy"
t("battles", { count: 5 });  // "5 bitew"

English and French need two forms, Polish and Russian three, Arabic six, and Japanese only one. A hand-written singular/plural pair cannot express that: it writes the 5-and-above form on every count from two upwards.

An exact match takes precedence over its category, which is how a language says "none" without claiming it is the zero category:

{
  "messages": "{count, plural, =0 {No messages} one {# message} other {# messages}}"
}

Select

select matches a value as written and falls back to other. It carries grammatical agreement when your data knows the attribute:

{
  "invited": "{gender, select, f {She} m {He} other {They}} joined the team"
}

t("invited", { gender: "f" });  // "She joined the team"
t("invited", { gender: "x" });  // "They joined the team"

The attribute cannot be derived from the word itself, so pass it as a variable. For a dynamic proper noun, prefer a phrasing that needs no article at all.

Branches nest, so a select may hold a plural, and either may hold plain variables.

Only plural and select are supported. Dates and numbers are better formatted with Intl at the call site, where you know the options you want.

Nested Keys

{
  "user": {
    "profile": {
      "title": "Profile"
    }
  }
}

t("user.profile.title");  // "Profile"

Type Definitions

TranslationNamespaces

Extend this interface for type-safe translations:

declare module "@onruntime/translations" {
  interface TranslationNamespaces {
    common: typeof import("./locales/en/common.json");
    auth: typeof import("./locales/en/auth.json");
  }
}