Namespaces & Scoping

Organizing translation keys by functional module or page avoids key collisions and simplifies call paths.

Scoped Translators

Passing a namespace as the second argument when calling getTranslations returns a translation function scoped to that namespace:

const messages = {
  admin: {
    dashboard: {
      metrics: "Live Statistics",
      refresh: "Refresh Data",
    },
  },
} as const;

// Scope to nested namespace
const t = getTranslations("en-US", "admin.dashboard");

t("metrics"); // "Live Statistics"
t("refresh"); // "Refresh Data"

Global Flat Translators

If the namespace parameter is omitted, getTranslations returns a root translator supporting nested key access via dot-separated paths:

const t = getTranslations("en-US");

t("admin.dashboard.metrics"); // "Live Statistics"

Extracting Raw Data t.raw()

When you need to directly obtain raw structures such as configuration objects or arrays, you can use t.raw():

const messages = {
  config: {
    maxRetries: 3,
    endpoints: ["api-1.example.com", "api-2.example.com"],
  },
} as const;

const t = getTranslations("en-US");

const endpoints = t.raw("config.endpoints");
// Inferred type: readonly ["api-1.example.com", "api-2.example.com"]

Checking Key Existence t.has()

Checks whether a specified key exists in the current language or fallback language without triggering missing key warnings:

const t = getTranslations("en-US", "features");

if (t.has("betaFeatureBadge")) {
  renderBadge(t("betaFeatureBadge"));
}