Server SDK

@better-i18n/server is a standalone i18n package for pure API servers. It runs on any JavaScript runtime — Node.js, Bun, Deno, and Cloudflare Workers — with no React or SSR framework dependency.

When to Use This Package #

Installation #

npm install @better-i18n/server

Quick Start #

Create the i18n singleton #

Instantiate createServerI18n once at module scope — not inside a request handler. The singleton shares a TtlCache across all requests, avoiding redundant CDN fetches.

import { createServerI18n } from "@better-i18n/server";

export const i18n = createServerI18n({
  projectId: "my-org/api",
  defaultLocale: "en",
});

Use the translator #

No middleware needed — call getTranslator directly with a locale string. This works on any runtime.

import { i18n } from "./i18n";

export async function sendWelcomeEmail(userId: string, locale: string) {
  const t = await i18n.getTranslator(locale);

  await mailer.send({
    to: userId,
    subject: t("emails.welcome.subject"),
    body: t("emails.welcome.body"),
  });
}

import { i18n } from "../i18n";

// With namespace scoping
const t = await i18n.getTranslator("tr", "errors");
t("notFound"); // → "Bulunamadı"

Choose an adapter (optional) #

If you use a web framework and want automatic Accept-Language detection injected into the request context, pick the right adapter:

No framework? Skip adapters entirely and call i18n.detectLocaleFromHeaders(request.headers) with any Web Standards Headers object.

Next Steps #

• Hono — Set up the Hono middleware with full TypeScript variable types.
• Express & Fastify — Node.js HTTP adapter — use betterI18nMiddleware with Express or fromNodeHeaders with Fastify.
• Supabase — Detect locale and translate in Supabase Edge Functions (Deno).
• tRPC — Inject locale and t into tRPC context for localized error messages.
• API Reference — Full reference for createServerI18n, ServerI18n, and all exports.