快速开始
本指南将帮助你快速在 Modern.js 项目中集成国际化功能。
安装插件
首先，安装必要的依赖：
pnpm add @modern-js/plugin-i18n i18next react-i18nextInfo
i18next 和 react-i18next 是 peer dependencies，需要手动安装。
基础配置
在 modern.config.ts 中注册插件
import { appTools, defineConfig } from '@modern-js/app-tools';
import { i18nPlugin } from '@modern-js/plugin-i18n';
export default defineConfig({
server: {
publicDir: './locales', // 必需：指定资源文件目录
},
plugins: [
appTools(),
i18nPlugin({
localeDetection: {
localePathRedirect: true, // 启用路径重定向
languages: ['zh', 'en'], // 支持的语言列表
fallbackLanguage: 'en', // 默认语言
},
backend: {
enabled: true, // 启用后端资源加载
// loadPath 默认为 '/locales/{{lng}}/{{ns}}.json'，通常无需修改
// 注意：你也可以省略 'enabled'，只需配置 'loadPath' 或 'addPath'，
// 或者完全省略 backend 配置，让插件自动检测 locales 目录
},
}),
],
});Info
server.publicDir 是必需配置，用于指定资源文件的实际存放位置。即使使用默认的 loadPath 路径，也需要配置此项。
在 src/modern.runtime.ts 中配置运行时选项
创建 src/modern.runtime.ts 文件并配置 i18n 运行时选项：
import { defineRuntimeConfig } from '@modern-js/runtime';
import i18next from 'i18next';
// 建议创建一个新的 i18next 实例，避免使用全局默认实例
const i18nInstance = i18next.createInstance();
export default defineRuntimeConfig({
i18n: {
i18nInstance: i18nInstance,
initOptions: {
fallbackLng: 'en',
supportedLngs: ['zh', 'en'],
},
},
});Info
modern.runtime.ts 是运行时配置文件，用于配置 i18next 的初始化选项。即使是最基础的配置，也建议创建此文件以确保插件正常工作。
建议使用 i18next.createInstance() 创建一个新的实例，而不是直接使用默认导出的 i18next，这样可以避免全局状态污染，并确保每个应用都有独立的 i18n 实例。
创建语言资源文件
在项目根目录创建 locales 文件夹，并按语言组织资源文件：
locales/
├── en/
│ └── translation.json
└── zh/
└── translation.jsonlocales/en/translation.json:
{
"hello": "Hello",
"world": "World",
"welcome": "Welcome to Modern.js"
}locales/zh/translation.json:
{
"hello": "你好",
"world": "世界",
"welcome": "欢迎使用 Modern.js"
}在组件中使用
import { useModernI18n } from '@modern-js/plugin-i18n/runtime';
import { useTranslation } from 'react-i18next';
function App() {
const { language, changeLanguage, supportedLanguages } = useModernI18n();
const { t } = useTranslation();
return (
<div>
<h1>{t('welcome')}</h1>
<p>当前语言: {language}</p>
<div>
{supportedLanguages.map(lang => (
<button
key={lang}
onClick={() => changeLanguage(lang)}
disabled={lang === language}
>
{lang}
</button>
))}
</div>
</div>
);
}
export default App;