API 参考

useModernI18n Hook

useModernI18n 是插件提供的 React Hook，用于在组件中访问国际化功能。

返回值说明

interface UseModernI18nReturn {
  /** 当前语言代码 */
  language: string;

  /** 切换语言的函数 */
  changeLanguage: (newLang: string) => Promise<void>;

  /** i18next 实例（用于高级用法） */
  i18nInstance: I18nInstance;

  /** 支持的语言列表 */
  supportedLanguages: string[];

  /** 检查语言是否支持 */
  isLanguageSupported: (lang: string) => boolean;

  /** 指示当前语言的翻译资源是否已准备好可以使用 */
  isResourcesReady: boolean;
}

使用示例

import { useModernI18n } from '@modern-js/plugin-i18n/runtime';

function LanguageSwitcher() {
  const { language, changeLanguage, supportedLanguages, isLanguageSupported } =
    useModernI18n();

  return (
    <div>
      <p>当前语言: {language}</p>
      <div>
        {supportedLanguages.map(lang => (
          <button
            key={lang}
            onClick={() => changeLanguage(lang)}
            disabled={lang === language}
          >
            {lang}
          </button>
        ))}
      </div>
      <button
        onClick={() => {
          if (isLanguageSupported('ja')) {
            changeLanguage('ja');
          }
        }}
      >
        切换到日语
      </button>
    </div>
  );
}

changeLanguage 方法

changeLanguage 方法用于切换语言，它会：

更新 i18next 实例的语言
更新浏览器缓存（Cookie/LocalStorage）
更新 URL 路径（如果启用 localePathRedirect）

const { changeLanguage } = useModernI18n();

// 切换语言
await changeLanguage('zh');

Info

changeLanguage 是异步函数，返回 Promise。

语言支持检查

isLanguageSupported 用于检查某个语言是否在支持的语言列表中：

const { isLanguageSupported, changeLanguage } = useModernI18n();

function handleLanguageChange(lang: string) {
  if (isLanguageSupported(lang)) {
    changeLanguage(lang);
  } else {
    console.warn(`语言 ${lang} 不受支持`);
  }
}

资源加载状态

isResourcesReady 指示当前语言的翻译资源是否已加载完成并可以使用。这在使用了 SDK 后端动态加载资源时特别有用。

import { useModernI18n } from '@modern-js/plugin-i18n/runtime';

function MyComponent() {
  const { isResourcesReady } = useModernI18n();

  if (!isResourcesReady) {
    return <div>正在加载翻译资源...</div>;
  }

  return <div>翻译资源已准备好</div>;
}

使用场景：

在资源加载时显示加载状态
在资源准备好之前阻止渲染依赖翻译的内容
优雅地处理资源加载错误

Info

isResourcesReady 会自动检查：

i18n 实例是否已初始化
当前语言是否有资源正在加载中（仅 SDK 后端）
当前语言的所有必需命名空间是否已在 store 中加载完成

I18nLink 组件

I18nLink 组件用于创建带语言前缀的链接。

Props 说明

interface I18nLinkProps {
  /** 目标路径（不需要包含语言前缀） */
  to: string;
  /** 子元素 */
  children: React.ReactNode;
  /** 其他 Link 组件的 props（如 replace、state 等） */
  [key: string]: any;
}

使用示例

import { I18nLink } from '@modern-js/plugin-i18n/runtime';

function Navigation() {
  return (
    <nav>
      <I18nLink to="/">首页</I18nLink>
      <I18nLink to="/about">关于</I18nLink>
      <I18nLink to="/contact" replace>
        联系
      </I18nLink>
    </nav>
  );
}

Runtime 插件 API

在 Runtime 插件的 onBeforeRender 钩子中，可以通过 context.changeLanguage 方法修改语言。这对于需要根据请求信息（如用户偏好、地理位置等）动态设置语言的场景非常有用。

context.changeLanguage

在 onBeforeRender 钩子中，i18n 插件会在 context 上添加 changeLanguage 方法，供其他 Runtime 插件使用。

类型定义：

interface TInternalRuntimeContext {
  i18nInstance?: I18nInstance;
  changeLanguage?: (lang: string) => Promise<void>;
}

使用示例

import type { RuntimePlugin } from '@modern-js/runtime';

const myRuntimePlugin = (): RuntimePlugin => ({
  name: 'my-runtime-plugin',
  setup: api => {
    api.onBeforeRender(async context => {
      // 检查是否有 changeLanguage 方法（确保 i18n 插件已加载）
      if (context.changeLanguage) {
        // 根据某些条件决定语言
        const userLang = getUserLanguageFromRequest(context);

        // 修改语言
        await context.changeLanguage(userLang);
      }
    });
  },
});

function getUserLanguageFromRequest(context: any): string {
  // 从请求头、Cookie 或其他来源获取用户语言
  const acceptLanguage = context.ssrContext?.req?.headers['accept-language'];
  // 解析并返回合适的语言代码
  return parseAcceptLanguage(acceptLanguage) || 'zh';
}

export default myRuntimePlugin;

注意事项

执行顺序：确保 i18n 插件在其他使用 changeLanguage 的插件之前注册，这样 context.changeLanguage 才会可用。
异步操作：changeLanguage 是异步方法，需要使用 await 等待完成。
错误处理：如果传入无效的语言代码，会抛出错误，建议添加错误处理：

api.onBeforeRender(async context => {
  if (context.changeLanguage) {
    try {
      await context.changeLanguage('zh');
    } catch (error) {
      console.error('Failed to change language:', error);
    }
  }
});

语言验证：建议在调用 changeLanguage 前验证语言是否在支持的语言列表中：

api.onBeforeRender(async context => {
  if (context.changeLanguage && context.i18nInstance) {
    const supportedLngs = context.i18nInstance.options?.supportedLngs || [];
    const targetLang = 'zh';

    if (supportedLngs.includes(targetLang)) {
      await context.changeLanguage(targetLang);
    }
  }
});

Info

changeLanguage 方法会：

更新 i18n 实例的语言
在浏览器环境中缓存语言选择（Cookie/LocalStorage）
触发语言切换相关的回调

但不会自动更新 URL 路径，如果需要更新 URL，需要配合路由插件或手动处理。

与 react-i18next 集成

插件完全兼容 react-i18next，可以使用 useTranslation Hook 和其他 react-i18next 功能。

useTranslation Hook

import { useTranslation } from 'react-i18next';

function MyComponent() {
  const { t, i18n } = useTranslation();

  return (
    <div>
      <h1>{t('welcome')}</h1>
      <p>{t('description', { name: 'Modern.js' })}</p>
    </div>
  );
}

i18next 实例访问

可以通过 useModernI18n 获取 i18next 实例：

import { useModernI18n } from '@modern-js/plugin-i18n/runtime';
import { useTranslation } from 'react-i18next';

function MyComponent() {
  const { i18nInstance } = useModernI18n();
  const { t } = useTranslation();

  // 直接访问 i18next 实例
  console.log(i18nInstance.language);
  console.log(i18nInstance.options);

  return <div>{t('hello')}</div>;
}

类型定义

I18nInstance 接口

interface I18nInstance {
  language: string;
  isInitialized: boolean;
  init: (options?: I18nInitOptions) => void | Promise<void>;
  changeLanguage: (lang: string) => void | Promise<void>;
  use: (plugin: any) => void;
  createInstance: (options?: I18nInitOptions) => I18nInstance;
  cloneInstance?: () => I18nInstance;
  services?: {
    languageDetector?: {
      detect: (request?: any, options?: any) => string | string[] | undefined;
      [key: string]: any;
    };
    [key: string]: any;
  };
  options?: {
    backend?: BackendOptions;
    [key: string]: any;
  };
}

I18nInitOptions 接口

interface I18nInitOptions {
  lng?: string;
  fallbackLng?: string;
  supportedLngs?: string[];
  initImmediate?: boolean;
  detection?: LanguageDetectorOptions;
  backend?: BackendOptions;
  resources?: Resources;
  ns?: string | string[];
  defaultNS?: string | string[];
  react?: {
    useSuspense?: boolean;
    [key: string]: any;
  };
  [key: string]: any;
}

LanguageDetectorOptions 接口

interface LanguageDetectorOptions {
  /** 检测顺序 */
  order?: string[];
  /** 查询参数的键名，默认 'lng' */
  lookupQuerystring?: string;
  /** Cookie 的键名，默认 'i18next' */
  lookupCookie?: string;
  /** LocalStorage 的键名，默认 'i18nextLng'（仅浏览器环境） */
  lookupLocalStorage?: string;
  /** SessionStorage 的键名（仅浏览器环境） */
  lookupSession?: string;
  /** 从路径的哪个位置开始检测语言，默认 0 */
  lookupFromPathIndex?: number;
  /** 缓存方式，可以是 false、字符串数组（如 ['cookie', 'localStorage']） */
  caches?: boolean | string[];
  /** Cookie 过期时间（分钟） */
  cookieMinutes?: number;
  /** Cookie 过期日期（Date 对象，优先级高于 cookieMinutes） */
  cookieExpirationDate?: Date;
  /** Cookie 域名 */
  cookieDomain?: string;
  /** 请求头的键名，默认 'accept-language' */
  lookupHeader?: string;
}

Resources 类型

type Resources = {
  [lng: string]: {
    [ns: string]: string | Record<string, string>;
  };
};

Info

命名空间的值可以是字符串（用于简单的键值对）或对象（用于嵌套的翻译结构）。

#API 参考

#useModernI18n Hook

#返回值说明

#使用示例

#changeLanguage 方法

#语言支持检查

#资源加载状态

#I18nLink 组件

#Props 说明

#使用示例

#Runtime 插件 API

#context.changeLanguage

#使用示例

#注意事项

#与 react-i18next 集成

#useTranslation Hook

#i18next 实例访问

#类型定义

#I18nInstance 接口

#I18nInitOptions 接口

#LanguageDetectorOptions 接口

#Resources 类型

API 参考

useModernI18n Hook

返回值说明

使用示例

changeLanguage 方法

语言支持检查

资源加载状态

I18nLink 组件

Props 说明

使用示例

Runtime 插件 API

context.changeLanguage

使用示例

注意事项

与 react-i18next 集成

useTranslation Hook

i18next 实例访问

类型定义

I18nInstance 接口

I18nInitOptions 接口

LanguageDetectorOptions 接口

Resources 类型