API Reference
Complete API documentation for @better-i18n/core
Complete API reference for the core package. All framework SDKs (Next.js, Vite, TanStack Start, Expo) are built on top of these primitives.
createI18nCore
Creates an i18n core instance for fetching translations, languages, and manifests from the CDN.
import { createI18nCore } from "@better-i18n/core";
const i18n = createI18nCore({
project: "org/project",
defaultLocale: "en",
});Instance Methods
clearManifestCache
Clears the global manifest cache across all instances. Useful for testing or forcing a fresh fetch.
import { clearManifestCache } from "@better-i18n/core";
clearManifestCache();extractLanguages
Extracts and normalizes language information from a raw manifest response. Useful when you have a manifest and need to convert it to UI-friendly language options.
import { extractLanguages } from "@better-i18n/core";
const manifest = await i18n.getManifest();
const languages = extractLanguages(manifest);
// [{ code: "en", name: "English", nativeName: "English", isDefault: true }, ...]| Parameter | Type | Description |
|---|---|---|
manifest | ManifestResponse | Raw manifest from CDN |
Returns: LanguageOption[] — Normalized language options
In most cases, use i18n.getLanguages() instead — it handles fetching the manifest and extracting languages in one call.
TtlCache
Generic in-memory cache with automatic TTL expiration. Used internally for manifest caching, but available for custom use.
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();Methods
| Method | Signature | Description |
|---|---|---|
get | (key: string) => T | undefined | Get value (auto-deletes if expired) |
set | (key: string, value: T, ttlMs: number) => void | Store with TTL in ms |
has | (key: string) => boolean | Check if key exists and is not expired |
delete | (key: string) => boolean | Remove a key |
clear | () => void | Clear all entries |
detectLocale
Framework-agnostic locale detection with priority-based selection. Detects the best locale from path, cookie, and header sources.
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); // trueDetection Priority
- Path — Locale from URL (e.g.,
/tr/about) - Cookie — Stored user preference
- Header — Browser's
Accept-Languageheader - Default — Fallback to
defaultLocale
Options
| Option | Type | Description |
|---|---|---|
project | string | Project identifier |
defaultLocale | string | Fallback locale |
pathLocale | string | null | Locale from URL path |
cookieLocale | string | null | Locale from cookie |
headerLocale | string | null | Locale from Accept-Language |
availableLocales | string[] | Supported locale codes |
Result
| Property | Type | Description |
|---|---|---|
locale | string | Detected locale code |
detectedFrom | "path" | "cookie" | "header" | "default" | Detection source |
shouldSetCookie | boolean | Whether to update the locale cookie |
Configuration Utilities
createLogger
Creates a namespaced logger instance with level filtering.
import { createLogger, normalizeConfig } from "@better-i18n/core";
const config = normalizeConfig({
project: "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 failedLog Levels
| Level | Value | Description |
|---|---|---|
"debug" | 0 | All messages |
"info" | 1 | Info and above |
"warn" | 2 | Warnings and above (default) |
"error" | 3 | Errors only |
"silent" | 4 | No output |
Types
All types are exported from @better-i18n/core:
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";