Core — Better I18N

Sur cette page

Overview
Install
Quick Start
Common Use Cases
Fetch Available Languages
Fetch the Manifest
Pre-load Translations
Configuration
Next Steps

Overview #

@better-i18n/core is the foundation package that powers all Better i18n SDKs. It provides a framework-agnostic API for fetching translations, discovering languages, managing caches, and handling locale URLs.

Use @better-i18n/core directly when:

You're building a custom integration outside Next.js, Vite, TanStack, or Expo
You need to fetch available languages with metadata (name, native name, flags)
You're writing server-side scripts or CLI tools that interact with the CDN
You want locale URL utilities for routing in any framework

Install #

npm install @better-i18n/core

Quick Start #

Create an i18n core instance and start fetching translations:

i18n.ts

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

const i18n = createI18nCore({
  projectId: "my-company/web-app",
  defaultLocale: "en",
});

// Fetch translation messages for a locale
const messages = await i18n.getMessages("tr");
// { common: { welcome: "Hoş geldiniz", logout: "Çıkış" } }

// Get all available locale codes
const locales = await i18n.getLocales();
// ["en", "tr", "de", "fr"]

// Get languages with full metadata (name, native name, flag)
const languages = await i18n.getLanguages();

Common Use Cases #

Fetch Available Languages #

The most common use case — building a language switcher or listing available translations:

TypeScript

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

const i18n = createI18nCore({
  projectId: "my-company/web-app",
  defaultLocale: "en",
});

const languages = await i18n.getLanguages();

languages.forEach((lang) => {
  console.log(`${lang.code}: ${lang.nativeName} ${lang.isDefault ? "(default)" : ""}`);
});

Fetch the Manifest #

The manifest contains all project metadata — languages, files, timestamps:

TypeScript

const manifest = await i18n.getManifest();

console.log(manifest.sourceLanguage); // "en"
console.log(manifest.languages);      // Full language metadata
console.log(manifest.files);          // CDN file URLs and sizes
console.log(manifest.updatedAt);      // Last update timestamp

Pre-load Translations #

Fetch messages for multiple locales at once (useful for SSR or static generation):

TypeScript

const locales = await i18n.getLocales();

const allMessages = await Promise.all(
  locales.map(async (locale) => ({
    locale,
    messages: await i18n.getMessages(locale),
  }))
);

Configuration #

TypeScript

const i18n = createI18nCore({
  // Required
  projectId: "org/project",     // Project identifier
  defaultLocale: "en",          // Fallback locale

  // Optional
  cdnBaseUrl: "https://cdn.better-i18n.com", // Custom CDN URL
  manifestCacheTtlMs: 300_000,               // Cache TTL (default: 5 min)
  debug: false,                              // Enable debug logging
  logLevel: "warn",                          // "debug" | "info" | "warn" | "error" | "silent"
  fetch: customFetch,                        // Custom fetch (for testing)
});

Option	Type	Default	Description
`projectId`	`string`	Required	Project ID — accepts `org/project` slug or canonical UUID
`defaultLocale`	`string`	Required	Fallback locale code
`cdnBaseUrl`	`string`	`"https://cdn.better-i18n.com"`	CDN base URL
`manifestCacheTtlMs`	`number`	`300000` (5 min)	Manifest cache TTL in ms
`debug`	`boolean`	`false`	Enable debug logging
`logLevel`	`LogLevel`	`"warn"`	Log level threshold
`fetch`	`typeof fetch`	`globalThis.fetch`	Custom fetch function

Next Steps #

Explore the API Reference for all methods and types
Learn about Locale URL Utilities for routing
See framework-specific guides: Next.js, Vite, TanStack Start, Expo