better-i18n.com
Geliştirici DokümanlarıYardım MerkeziSürüm Notları

Server SDK API Reference

Bu sayfada

Complete API reference for the Server SDK.

createServerI18n(config) #

Factory function that creates a server-side i18n instance. Call this once at module scope — never inside a request handler.

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

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

Config Options #

OptionTypeDefaultDescription
projectstringRequiredProject identifier in org/project format
defaultLocalestringRequiredFallback locale when detection fails
cdnBaseUrlstring"https://cdn.better-i18n.com"CDN base URL override
fetchTimeoutnumber10000CDN fetch timeout in milliseconds
retryCountnumber1Number of retries on CDN failure
debugbooleanfalseEnable debug logging
logLevel"debug" | "info" | "warn" | "error" | "silent""warn"Log verbosity

Return Value #

Returns a ServerI18n instance — see the ServerI18n interface below.

ServerI18n Interface #

The instance returned by createServerI18n.

Fetches messages for the given locale and returns a Translator function. Messages are cached by TtlCache — repeat calls within the TTL window return instantly.

TypeScript
// Without namespace — access all keys with dot notation
const t = await i18n.getTranslator("tr");
t("errors.notFound"); // → "Bulunamadı"

// With namespace — access keys relative to the namespace
const t = await i18n.getTranslator("tr", "errors");
t("notFound"); // → "Bulunamadı"
ParameterTypeDescription
localestringLocale code (e.g., "tr", "de")
namespacestring (optional)Namespace prefix for key lookups

Returns: Promise<Translator>

Parses the Accept-Language header and returns the best-matching locale from your project's available locales. Falls back to defaultLocale if no match is found.

TypeScript
// Web Standards Headers object
const locale = await i18n.detectLocaleFromHeaders(request.headers);

// From Node.js IncomingHttpHeaders (use fromNodeHeaders first)
import { fromNodeHeaders } from "@better-i18n/server/node";
const headers = fromNodeHeaders(req.headers);
const locale = await i18n.detectLocaleFromHeaders(headers);
ParameterTypeDescription
headersHeadersWeb Standards Headers object

Returns: Promise<string> — matched locale or defaultLocale

Returns the list of available locale codes from the CDN manifest. Cached with TtlCache.

TypeScript
const locales = await i18n.getLocales();
// ["en", "tr", "de", "fr"]

Returns: Promise<string[]>

Returns language metadata (name, native name, flag URL) for all available locales. Useful for building language-selection responses in your API.

TypeScript
const languages = await i18n.getLanguages();
// [
//   { code: "en", name: "English", nativeName: "English", flagUrl: "..." },
//   { code: "tr", name: "Turkish", nativeName: "Türkçe", flagUrl: "..." },
// ]

Returns: Promise<LanguageOption[]>

@better-i18n/server/hono #

Hono middleware that detects locale from the Accept-Language header and sets locale and t on the context.

TypeScript
import { Hono } from "hono";
import { betterI18n } from "@better-i18n/server/hono";
import { i18n } from "./i18n";
import type { Translator } from "@better-i18n/server";

const app = new Hono<{
  Variables: {
    locale: string;
    t: Translator;
  };
}>();

app.use("*", betterI18n(i18n));

app.get("/", (c) => {
  const t = c.get("t");
  return c.json({ message: t("home.welcome") });
});
ParameterTypeDescription
i18nServerI18nInstance from createServerI18n

Sets on context:

VariableTypeDescription
localestringDetected locale
tTranslatorReady-to-use translator for the detected locale

@better-i18n/server/node #

Express/Connect-compatible middleware. Injects req.locale and req.t into every request.

TypeScript
import express from "express";
import { betterI18nMiddleware } from "@better-i18n/server/node";
import { i18n } from "./i18n";

const app = express();
app.use(betterI18nMiddleware(i18n));

app.get("/", (req, res) => {
  res.json({ message: req.t("home.welcome") });
});
ParameterTypeDescription
i18nServerI18nInstance from createServerI18n

Injects on req:

PropertyTypeDescription
req.localestringDetected locale
req.tTranslatorReady-to-use translator

Converts a Node.js IncomingHttpHeaders object to a Web Standards Headers object. Use this to bridge Fastify, Koa, or raw http.IncomingMessage with detectLocaleFromHeaders.

TypeScript
import { fromNodeHeaders } from "@better-i18n/server/node";

// Fastify
const headers = fromNodeHeaders(request.headers);
const locale = await i18n.detectLocaleFromHeaders(headers);

// Raw Node.js http.IncomingMessage
import http from "node:http";
http.createServer(async (req, res) => {
  const headers = fromNodeHeaders(req.headers);
  const locale = await i18n.detectLocaleFromHeaders(headers);
  const t = await i18n.getTranslator(locale);
  res.end(t("home.welcome"));
});
ParameterTypeDescription
nodeHeadersIncomingHttpHeadersHeaders from req.headers

Returns: Headers — Web Standards Headers object

Types #

Configuration for createServerI18n. Mirrors I18nCoreConfig from @better-i18n/core.

TypeScript
import type { ServerI18nConfig } from "@better-i18n/server";

const config: ServerI18nConfig = {
  projectId: "my-org/api",
  defaultLocale: "en",
  cdnBaseUrl: "https://cdn.better-i18n.com", // optional
  fetchTimeout: 10000,                         // optional
  retryCount: 1,                               // optional
  debug: false,                                // optional
};

The translator function type returned by getTranslator. Thin alias for use-intl/core's createTranslator return type.

TypeScript
import type { Translator } from "@better-i18n/server";

// Usage in function signatures
function formatError(t: Translator, code: string): string {
  return t(`errors.${code}`);
}

// With interpolation
const t = await i18n.getTranslator("tr");
t("user.greeting", { name: "Osman" }); // → "Merhaba, Osman!"

Language metadata from the CDN manifest. Returned by getLanguages().

TypeScript
import type { LanguageOption } from "@better-i18n/core";

interface LanguageOption {
  code: string;          // "tr", "en", "de"
  name?: string;         // "Turkish", "English"
  nativeName?: string;   // "Türkçe", "English"
  flagUrl?: string | null; // CDN URL to flag image
}