# @better-i18n/next 中文文档
规范地址：https://npmcn.com/package/%40better-i18n/next/
版本：0\.10\.0
npm 元数据更新时间：2026-10-26T13:44:30.807Z
中文译文更新时间：2026-11-08T00:05:26.968Z
软件包许可：MIT
本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。
原始 npm 页面：https://www.npmjs.com/package/%40better-i18n/next
原文对照：https://npmcn.com/package/%40better-i18n/next/?lang=original
项目主页：https://github.com/better-i18n/better-i18n/tree/main/packages/next
源码仓库：https://github.com/better-i18n/better-i18n
## 关键信息（来自 npm 元数据）
- 包体积（解压后）：123 kB，54 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：2 个
- peer 依赖：next \>=15\.0\.0，react \>=18\.0\.0，next-intl \>=4\.0\.0，react-dom \>=18\.0\.0
- 首次发布：2025-12-20T13:29:40.589Z
- 最新版本发布：2026-10-26T13:44:30.444Z
- 近 30 天下载量：2450（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：39（近 12 个月 39 个）
## 中文简介
更好的i18n Next.js 整合
## 安装
```sh
npm install @better-i18n/next
```
也可以使用：`pnpm add @better-i18n/next`、`yarn add @better-i18n/next`、`bun add @better-i18n/next`
## README
# @ better-i18n/ 下一个
下一个.js 整合 [更好的i18n (英语)](https://better-i18n.com/)。提供无缝 `next-intl` 与 CDN 驱动的翻译获取集成 .
## 特征
- **零配置同步** - 通过下列方式连接您的项目: `i18n.config.ts`
- **边缘准备缓存** - 内设的伊斯兰社支持公开和信息
- **类型安全** - 全部类型脚本支持
- **下图** - 设计为 `next-intl`
## 安装
```bash
npm install @better-i18n/next next-intl
# or
bun add @better-i18n/next next-intl
```
## 快速启动
### 1\. 创建i18n配置
```ts
// i18n.config.ts
import { createI18n } from "@better-i18n/next";
export const i18n = createI18n({
project: "your-org/your-project", // Format: "org-slug/project-slug"
defaultLocale: "en",
});
```
### 2\. 设置请求配置
```ts
// src/i18n/request.ts
import { i18n } from "../i18n.config";
export default i18n.requestConfig;
```
### 3\. 添加中间软件
```ts
// middleware.ts
import { i18n } from "./i18n.config";
export default i18n.middleware;
export const config = {
matcher: ["/((?!api|_next|.*\\..*).*)"],
};
```
### 4\. 使用翻译
```tsx
// app/page.tsx
import { useTranslations } from "next-intl";
export default function Home() {
const t = useTranslations("common");
return {t("welcome")}
;
}
```
## 高级中件
为了更多的控制,使用 `createBetterI18nMiddleware`数字 :
```ts
import { createBetterI18nMiddleware, composeMiddleware } from "@better-i18n/next/middleware";
const i18nMiddleware = createBetterI18nMiddleware({
project: "org/project",
defaultLocale: "en",
detection: {
cookie: true,
browserLanguage: true,
cookieName: "locale",
cookieMaxAge: 31536000, // 1 year
},
});
// Compose with other middleware
export default composeMiddleware(i18nMiddleware, authMiddleware);
```
## 客户钩
```tsx
"use client";
import { useManifestLanguages } from "@better-i18n/next/client";
export function LanguageSwitcher() {
const { languages, isLoading, error } = useManifestLanguages({
project: "your-org/your-project",
defaultLocale: "en",
});
if (isLoading) return Loading...;
if (error) return Error: {error.message};
return (
);
}
```
## 服务器公用事业
```ts
import {
getMessages,
getLocales,
getManifestLanguages,
} from "@better-i18n/next/server";
const config = { project: "org/project", defaultLocale: "en" };
const locales = await getLocales(config);
const messages = await getMessages(config, "tr");
const languages = await getManifestLanguages(config);
```
## 配置选项
| 选项 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `project` | `string` | 所需经费 | 项目标识符( E)`org/project` 格式) |
| `defaultLocale` | `string` | 所需经费 | 默认/ 退后地块代码 |
| `cdnBaseUrl` | `string` | 自动 | CDN 基础 URL (自动检测) |
| `localePrefix` | `"as-needed"` | `"always"` | `"never"` | `"as-needed"` | URL 语言前缀行为 |
| `cookieName` | `string` | `"locale"` | 地方持久性的 Cookie 名 |
| `manifestRevalidateSeconds` | `number` | `3600` | 下一.js ISR 重新验证显示 |
| `messagesRevalidateSeconds` | `number` | `30` | Next.js ISR 对消息的再验证 |
| `storage` | `TranslationStorage` | `undefined` | 持续的离线后退缓存(见 `@better-i18n/core`(中文(简体) ) |
| `staticData` | `Record | () => Promise` | `undefined` | 装订的翻译为后退 |
| `fetchTimeout` | `number` | `10000` | CDN 获取超时( ms) |
| `retryCount` | `number` | `1` | 重试对 CDN 失败的尝试 |
| `debug` | `boolean` | `false` | 启用调试日志 |
| `logLevel` | `LogLevel` | `"warn"` | 记录动词 |
## 除错日志
启用环境变量 :
- `BETTER_I18N_DEBUG=1`
- `BETTER_I18N_LOG_LEVEL=debug|info|warn|error|silent`
## 文档
备有文件全文 [docs.better-i18n.com/ next (中文(简体) )](https://docs.better-i18n.com/docs/next)
## 许可证
麻省理工学院 [更好的i18n (英语)](https://better-i18n.com/)
## 常见问题
### @better-i18n/next 是什么？
更好的i18n Next\.js 整合
### 如何安装 @better-i18n/next？
在项目目录运行 npm install @better-i18n/next，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：next（\>=15\.0\.0）、react（\>=18\.0\.0）、next-intl（\>=4\.0\.0）、react-dom（\>=18\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。
### @better-i18n/next 支持 TypeScript 吗？
支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。
### @better-i18n/next 支持 ESM 还是 CommonJS？
以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。
### @better-i18n/next 可以商用吗？
@better-i18n/next 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。
### @better-i18n/next 的下载量有多少？
根据 npm 官方下载统计，@better-i18n/next 在 2026/10/08 – 2026/11/06 这 30 天内被下载 2,450 次，日均约 82 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。
### @better-i18n/next 还在维护吗？
最新版本 0\.10\.0 发布于 2026/10/26（12 天前）；至今共发布 39 个版本，其中过去 12 个月发布了 39 个；首次发布于 2025/12/20。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。