Core API Reference

import { createI18nCore } from "@better-i18n/core";

const i18n = createI18nCore({
  projectId: "org/project",
  defaultLocale: "en",
});

// Full fetch — all namespaces
const messages = await i18n.getMessages("tr");
// { common: { welcome: "Hoş geldiniz" }, auth: { login: "Giriş Yap" } }

// Selective — only fetch these namespaces (namespaced_folders projects)
const subset = await i18n.getMessages("tr", {
  namespaces: ["common", "hero"],
});
// { common: {...}, hero: {...} }

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

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

// Use cached manifest (default)
const manifest = await i18n.getManifest();

// Force a fresh fetch (bypass cache)
const fresh = await i18n.getManifest({ forceRefresh: true });

interface ManifestResponse {
  projectSlug?: string;
  sourceLanguage?: string;
  languages: ManifestLanguage[];
  files?: Record<string, ManifestFile>;
  updatedAt?: string;
}

console.log(i18n.config.cdnBaseUrl);        // "https://cdn.better-i18n.com"
console.log(i18n.config.manifestCacheTtlMs); // 300000
console.log(i18n.config.workspaceId);        // "org"
console.log(i18n.config.projectSlug);        // "project"

import { clearManifestCache } from "@better-i18n/core";

clearManifestCache();

import { extractLanguages } from "@better-i18n/core";

const manifest = await i18n.getManifest();
const languages = extractLanguages(manifest);
// [{ code: "en", name: "English", nativeName: "English", isDefault: true }, ...]

import { TtlCache } from "@better-i18n/core";

const cache = new TtlCache<string>();

// Store with 60s TTL
cache.set("key", "value", 60_000);

// Retrieve (returns undefined if expired)
const value = cache.get("key"); // "value"

// Check existence
cache.has("key"); // true

// Manual removal
cache.delete("key");

// Clear all entries
cache.clear();

import { detectLocale } from "@better-i18n/core";

const result = detectLocale({
  pathLocale: "tr",
  cookieLocale: "en",
  headerLocale: "de",
  defaultLocale: "en",
  availableLocales: ["en", "tr", "de"],
  project: "org/project",
});

console.log(result.locale);        // "tr"
console.log(result.detectedFrom);  // "path"
console.log(result.shouldSetCookie); // true

import { normalizeConfig } from "@better-i18n/core";

const config = normalizeConfig({
  projectId: "org/project",
  defaultLocale: "en",
});

console.log(config.cdnBaseUrl);        // "https://cdn.better-i18n.com"
console.log(config.manifestCacheTtlMs); // 300000
console.log(config.workspaceId);        // "org"
console.log(config.projectSlug);        // "project"

import { parseProject } from "@better-i18n/core";

const parsed = parseProject("acme/dashboard");
// { workspaceId: "acme", projectSlug: "dashboard" }

import { normalizeConfig, getProjectBaseUrl } from "@better-i18n/core";

const config = normalizeConfig({ projectId: "acme/dashboard", defaultLocale: "en" });
const url = getProjectBaseUrl(config);
// "https://cdn.better-i18n.com/acme/dashboard"

import { buildCacheKey } from "@better-i18n/core";

const key = buildCacheKey("https://cdn.better-i18n.com", "acme/dashboard");
// "https://cdn.better-i18n.com|acme/dashboard"

import { createLogger, normalizeConfig } from "@better-i18n/core";

const config = normalizeConfig({
  projectId: "org/project",
  defaultLocale: "en",
  debug: true,
});

const logger = createLogger(config, "my-module");
logger.debug("loading translations"); // [better-i18n:my-module] loading translations
logger.info("ready");                 // [better-i18n:my-module] ready
logger.warn("cache miss");            // [better-i18n:my-module] cache miss
logger.error("fetch failed");         // [better-i18n:my-module] fetch failed

import type {
  // Configuration
  I18nCoreConfig,
  NormalizedConfig,
  ParsedProject,

  // Manifest
  ManifestResponse,
  ManifestLanguage,
  ManifestFile,
  LanguageOption,

  // Messages
  Messages,
  Locale,

  // Instance
  I18nCore,

  // Cache
  CacheEntry,

  // Logger
  Logger,
  LogLevel,

  // Locale URL utilities
  LocaleConfig,

  // Middleware/Detection
  I18nMiddlewareConfig,
  LocaleDetectionOptions,
  LocaleDetectionResult,
  LocalePrefix,
} from "@better-i18n/core";

interface I18nCoreConfig {
  projectId: string;              // "org/project" slug or canonical UUID (required)
  project?: string;               // @deprecated — use projectId (kept for backward compat)
  defaultLocale: string;          // Fallback locale (required)
  cdnBaseUrl?: string;            // Default: "https://cdn.better-i18n.com"
  manifestCacheTtlMs?: number;    // Default: 300000 (5 min)
  debug?: boolean;                // Default: false
  logLevel?: LogLevel;            // Default: "warn"
  fetch?: typeof fetch;           // Custom fetch function
}

interface ManifestResponse {
  projectSlug?: string;
  sourceLanguage?: string;
  languages: ManifestLanguage[];
  files?: Record<string, ManifestFile>;
  updatedAt?: string;
  /** CDN supports batch namespace fetching via /{locale}/batch.json?ns=... */
  batch?: boolean;
  /** Top-level namespace list for namespaced_folders projects */
  namespaces?: string[];
}

interface ManifestLanguage {
  code: string;                   // "en", "tr", "de"
  name?: string;                  // "Turkish"
  nativeName?: string;            // "Türkçe"
  flagUrl?: string | null;        // Flag icon URL
  isSource?: boolean;             // Source language flag
  lastUpdated?: string | null;    // Last update timestamp
  keyCount?: number;              // Number of translation keys
}

interface LanguageOption {
  code: string;                   // "tr"
  name?: string;                  // "Turkish"
  nativeName?: string;            // "Türkçe"
  flagUrl?: string | null;        // Flag icon URL
  isDefault?: boolean;            // Source/default language
}

interface I18nCore {
  config: NormalizedConfig;
  getManifest(options?: { forceRefresh?: boolean }): Promise<ManifestResponse>;
  getMessages(
    locale: string,
    options?: { namespaces?: string[] },
  ): Promise<Messages>;
  getLocales(): Promise<string[]>;
  getLanguages(): Promise<LanguageOption[]>;
}

interface LocaleDetectionResult {
  locale: string;
  detectedFrom: "path" | "cookie" | "header" | "default";
  shouldSetCookie: boolean;
}