# @better-i18n/core 中文文档

规范地址：https://npmcn.com/package/%40better-i18n/core/

版本：0\.15\.0
npm 元数据更新时间：2026-10-26T13:32:01.695Z
中文译文更新时间：2026-11-08T00:04:53.458Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40better-i18n/core
原文对照：https://npmcn.com/package/%40better-i18n/core/?lang=original
项目主页：https://github.com/better-i18n/better-i18n/tree/main/packages/core
源码仓库：https://github.com/better-i18n/better-i18n

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：400 kB，98 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：react \>=18\.0\.0，@floating-ui/react \>=0\.26\.0
- 首次发布：2026-01-16T15:07:34.924Z
- 最新版本发布：2026-10-26T13:32:00.923Z
- 近 30 天下载量：4326（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：31（近 12 个月 31 个）

## 中文简介

改善i18n框架不可知的核心公用事业

## 安装

```sh
npm install @better-i18n/core
```

也可以使用：`pnpm add @better-i18n/core`、`yarn add @better-i18n/core`、`bun add @better-i18n/core`

## README

# @ better-i18n/ core (英语)

从Better i18n CDN获取翻译的框架不可知的核心公用事业.

## 特征

-   **框架不可知论** - 任何JavaScript运行时间的工作
-   **边缘准备** - 边缘环境优化(Cloudflare、Vercel等)
-   **类型安全** - 全部类型脚本支持
-   **缓存** - 装有可配置的TTL的装箱
-   **下行后退** - 5层后退链:TtlCache → CDN(含ETag 304) → 持续存储 → 静态数据
-   **耐受性** - 可配置取出超时并重试以指数回放

## 安装

```bash
npm install @better-i18n/core
# or
bun add @better-i18n/core
```

## 使用量

```typescript
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();
```

## 配置

```typescript
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
```

1.  **Ttl 缓存** ——可配置 TTL 的内元缓存(默认:5分). 立即,没有I/O.
2.  **CDN 获取** ——来自Better i18n CDN的新鲜翻译数据.
3.  **CDN 304(ETag)** ——如果CDN返回"未修改",再利用缓存版本.
4.  **存储** ——持久缓存(localStorage,AsyncStorage等)活了应用重启.
5.  **静态数据** ——包干翻译作为绝对最后手段.

### 存储适配器

本地持续翻译

```typescript
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).

### 静态数据

装订翻译为后退 :

```typescript
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`](https://www.npmjs.com/package/@better-i18n/next) | 下一个.js | `next-intl` |
| [`@better-i18n/use-intl`](https://www.npmjs.com/package/@better-i18n/use-intl) | 反应, Vite, TanStack 启动 | `use-intl` |
| [`@better-i18n/expo`](https://www.npmjs.com/package/@better-i18n/expo) | 博览会/ 反应原生 | `i18next` |

如果你使用其中的一个框架, 安装框架 SDK代替—— `@better-i18n/core` 自动列为依赖.

## 文档

备有文件全文 [docs.better-i18n.com/core 页面存档备份,存于互联网档案馆](https://docs.better-i18n.com/core)

## 许可证

麻省理工学院 [更好的i18n (英语)](https://better-i18n.com/)

## 常见问题

### @better-i18n/core 是什么？

改善i18n框架不可知的核心公用事业

### 如何安装 @better-i18n/core？

在项目目录运行 npm install @better-i18n/core，或使用 pnpm add / yarn add / bun add。

### @better-i18n/core 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @better-i18n/core 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @better-i18n/core 可以商用吗？

@better-i18n/core 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @better-i18n/core 的下载量有多少？

根据 npm 官方下载统计，@better-i18n/core 在 2026/10/08 – 2026/11/06 这 30 天内被下载 4,326 次，日均约 144 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @better-i18n/core 还在维护吗？

最新版本 0\.15\.0 发布于 2026/10/26（12 天前）；至今共发布 31 个版本，其中过去 12 个月发布了 31 个；首次发布于 2026/01/16。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。