@ better-i18n/ core (英语)
从Better i18n CDN获取翻译的框架不可知的核心公用事业.
特征
- 框架不可知论 - 任何JavaScript运行时间的工作
- 边缘准备 - 边缘环境优化(Cloudflare、Vercel等)
- 类型安全 - 全部类型脚本支持
- 缓存 - 装有可配置的TTL的装箱
- 下行后退 - 5层后退链:TtlCache → CDN(含ETag 304) → 持续存储 → 静态数据
- 耐受性 - 可配置取出超时并重试以指数回放
安装
npm install @better-i18n/core
# or
bun add @better-i18n/core
使用量
import { createI18nCore } from "@better-i18n/core";
const i18n = createI18nCore({
project: "your-org/your-project",
defaultLocale: "en",
});
// Fetch messages for a locale
const messages = await i18n.getMessages("en");
// Get available locales
const locales = await i18n.getLocales();
// ["en", "tr", "de", ...]
// Get language options with metadata (for UI)
const languages = await i18n.getLanguages();
// [{ code: "en", name: "English", nativeName: "English", flagUrl: "..." }, ...]
// Get manifest
const manifest = await i18n.getManifest();
配置
interface I18nCoreConfig {
// Required
project: string; // "org/project" format
defaultLocale: string; // e.g., "en"
// Optional
cdnBaseUrl?: string; // default: "https://cdn.better-i18n.com"
manifestCacheTtlMs?: number; // default: 300000 (5 minutes)
debug?: boolean; // default: false
logLevel?: LogLevel; // default: "warn"
fetch?: typeof fetch; // custom fetch function
// Fallback & Resilience
storage?: TranslationStorage; // persistent cache (localStorage, AsyncStorage, etc.)
staticData?: Record<string, Messages> | (() => Promise<Record<string, Messages>>);
fetchTimeout?: number; // default: 10000 (10s) — abort if CDN doesn't respond
retryCount?: number; // default: 1 — retry attempts on CDN failure
}
下行后退
翻译通过5层倒转链解决:
TtlCache (in-memory) → CDN fetch → CDN 304 (ETag) → Storage (persistent cache) → Static Data (bundled) → throw
- Ttl 缓存 ——可配置 TTL 的内元缓存(默认:5分). 立即,没有I/O.
- CDN 获取 ——来自Better i18n CDN的新鲜翻译数据.
- CDN 304(ETag) ——如果CDN返回"未修改",再利用缓存版本.
- 存储 ——持久缓存(localStorage,AsyncStorage等)活了应用重启.
- 静态数据 ——包干翻译作为绝对最后手段.
存储适配器
本地持续翻译
import { createI18nCore, createLocalStorage } from "@better-i18n/core";
const i18n = createI18nCore({
project: "your-org/your-project",
defaultLocale: "en",
storage: createLocalStorage(), // browser localStorage
});
内置适配器:
| 适配器 | 环境 | 导入 |
|---|---|---|
createLocalStorage() | 浏览器 | @better-i18n/core |
createMemoryStorage() | 任何(非持久性) | @better-i18n/core |
createAutoStorage() | 自动探测器( 本地存储器或内存) | @better-i18n/core |
您也可以提供执行中的任何对象 { get, set, remove? } 用于自定义商店(如AsyncStorage,MMKV).
静态数据
装订翻译为后退 :
const i18n = createI18nCore({
project: "your-org/your-project",
defaultLocale: "en",
// Static import
staticData: {
en: { common: { hello: "Hello" } },
tr: { common: { hello: "Merhaba" } },
},
// Or lazy import (code-split)
// staticData: () => import('./fallback-translations.json'),
});
框架整合
这个软件包是所有更好的i18n SDK的基础:
| 软件包 | 框架 | 内建于 |
|---|---|---|
@better-i18n/next | 下一个.js | next-intl |
@better-i18n/use-intl | 反应, Vite, TanStack 启动 | use-intl |
@better-i18n/expo | 博览会/ 反应原生 | i18next |
如果你使用其中的一个框架, 安装框架 SDK代替—— @better-i18n/core 自动列为依赖.
文档
备有文件全文 docs.better-i18n.com/core 页面存档备份,存于互联网档案馆
许可证
麻省理工学院 更好的i18n (英语)