i18n (translations)

This SDK ships full i18n. The TypeScript SDK is the reference implementation: it owns the browser loader, the SSR bootstrap of strings, and the i18n.t() render API. There is no separate i18n configuration — i18n rides the same shipeasy() / configure() initialisation as flags.

How it works

1. The browser loader script (emitted by the SSR bootstrap, or installed as a <script> tag) fetches the active locale profile (e.g. {{PROFILE}}) and exposes window.i18n.
2. The SSR bootstrap carries the evaluated strings inline (data-strings) so the first paint has translations with no flash, plus the public client key so the loader can revalidate at runtime.
3. Call sites render with i18n.t(key, fallback, variables?) from @shipeasy/sdk/client. t() returns the fallback (or the key itself) when the loader hasn't run yet, so call sites never need a null-check.

Wire the loader (SSR bootstrap)

The i18n loader tag is the second tag returned by getBootstrapData() / getBootstrapTags() — render it alongside the bootstrap tag in your root layout (see Configuration → SSR bootstrap):

import { shipeasy } from "@shipeasy/sdk/server";

const se = await shipeasy({ serverKey: process.env.SHIPEASY_SERVER_KEY ?? "" });
const boot = se.getBootstrapData({ clientKey: process.env.NEXT_PUBLIC_SHIPEASY_CLIENT_KEY });
// …
{
  boot.i18nLoader && <script src={boot.i18nLoader.src} {...boot.i18nLoader.attrs} />;
}

Without a build step, install the loader script directly so it carries the {{PROFILE}} profile and hydrates window.i18n.

Render a label — i18n.t()

import { i18n } from "@shipeasy/sdk/client";

// key + fallback (recommended — the fallback is the source string)
i18n.t("checkout.cta", "Place order");

// with interpolation variables
i18n.t("cart.count", "{count} items", { count: cart.length });

// key only (returns the key if no translation/fallback resolves)
i18n.t("checkout.cta");

Rich text and readiness

// <tag>…</tag> segments rendered via per-call components (framework-agnostic)
i18n.rich("terms.line", "Accept the <a>terms</a>", { a: (txt) => link(txt) });

i18n.locale; // current locale string | null
i18n.ready; // true once a locale is loaded
await i18n.whenReady(); // resolves when the loader has a locale
i18n.onUpdate(() => rerender()); // fires on locale / strings change

i18n.t() works on the server too (during SSR it reads the bootstrapped string store); off the server with no loader it returns the fallback. The render API is pure string parsing — no React dependency in the SDK itself.

The deprecated i18n.tEl() now just delegates to t() and returns a string; prefer t().