OpenMax
免费试用

国际化

设置聊天界面语言、接入 i18next,并在运行时切换语言。

国际化

聊天自带中英文文案。用 locale 选语言,再在外层包一个你自己装的 react-i18next 的 I18nextProvider,实例用 createChatI18n 建。

i18n-language-switch demo

演示截图。演示跑在内存里的示例 host 上(演示工具包里的 useDemoHost,不在发布的包里);你的应用里换成 createChatHost() 创建的 host。

演示源码(用到文档站的演示工具包和 Tailwind CSS 类名,不能直接复制使用): i18n-language-switch.tsx
"use client";

import { ChatHostProvider } from "@openmaxai/chat/host";
import { MessageThread } from "@openmaxai/chat/message-thread";
import { useState } from "react";
// Docs helpers: useDemoHost() is an in-memory host with sample data (no backend).
// In your app, pass the host from createChatHost() or your own ChatHost instead.
import { useDemoData, useDemoHost } from "./kit";

export default function LanguageSwitchDemo() {
	const host = useDemoHost();
	// `i18n` is the i18next instance from `createI18n()` that you pass to <I18nextProvider>.
	// The demo host's `i18n` capability reads from the same instance.
	const { conversations, i18n } = useDemoData();
	const [language, setLanguage] = useState(i18n.language);

	const change = async (next: string) => {
		await i18n.changeLanguage(next);
		setLanguage(next);
	};

	return (
		<ChatHostProvider host={host}>
			<div className="flex h-full flex-col bg-background text-foreground">
				<div className="flex gap-2 border-b p-2 text-xs">
					{["en", "zh"].map((lng) => (
						<button
							key={lng}
							type="button"
							onClick={() => change(lng)}
							className={`rounded-md border px-2 py-1 ${
								language === lng ? "bg-primary text-primary-foreground" : ""
							}`}
						>
							{lng === "en" ? "English" : "中文"}
						</button>
					))}
				</div>
				{/* Strings read through `host.i18n.t` are picked up on the next render: re-mount. */}
				<MessageThread key={language} conversation={conversations[0]} />
			</div>
		</ChatHostProvider>
	);
}

演示里的 useDemoHost() 是带示例数据的内存宿主;实际项目中换成 createChatHost 创建的宿主。

语言设置

使用 createChatHost 时传 locale:

import { createChatHost } from "@openmaxai/chat-openmax/react";

const host = createChatHost({
  baseUrl: "https://openmax.com",
  wsUrl: "wss://openmax.com/ws",
  auth: { mode: "token", getToken },
  orgId: currentOrgId,
  locale: "zh-CN",
});

上面是接 OpenMax 的一行写法,连接那几项见接入 OpenMax。接自己的后台时用 @openmaxai/chat-sdk/react 的 createChatHost({ adapter, locale }),locale 写法相同。

自定义宿主则传给 createLocalPorts:

...createLocalPorts({ scope: "my-chat", currentUserId: () => ME, locale: "zh-CN" }),

locale 是 BCP-47 标签:主标签为 en 时用英文,其余都用中文,默认 "zh-CN"。日期也按它格式化。

i18next Provider

文案有两个来源,都要接上:

来源 组件 你要提供
宿主的 i18n 能力 消息区、输入框、头部、会话列表、卡片、群管理;ChatProvider 之内的浮窗 / 停靠栏 / 抽屉外壳 无需额外操作,createChatHost / createLocalPorts 已提供
react-i18next 的 useTranslation() @ 提及面板、可拖宽的会话列表栏;浮窗 / 停靠栏 / 抽屉外壳在 i18n 认不得某个词时退回它,挂在 ChatProvider 之外时只用它 外层的 I18nextProvider,实例用 createChatI18n 建

src/app.tsx

import { createChatI18n } from "@openmaxai/chat-sdk";
import { I18nextProvider } from "react-i18next";

const i18n = createChatI18n({ locale: "zh-CN" });

export function App() {
  return (
    <I18nextProvider i18n={i18n}>
      <ChatProvider host={host}>{/* 聊天 */}</ChatProvider>
    </I18nextProvider>
  );
}

不包 provider,第二行的组件会直接显示翻译 key。createChatI18n 的 locale 要和宿主的 locale 一致。

createChatI18n 每次调用都新建一份独立的 i18next 实例,内置聊天的中英文文案。它不挂 initReactI18next,不改你应用全局的 react-i18next 实例,所以你自己组件里的 useTranslation 照旧读你的实例,除非它们渲染在这个 I18nextProvider 之内。react-i18next、i18next 是 peer 依赖:I18nextProvider、useTranslation 一律从你装的那份 react-i18next 取,和聊天组件读的是同一个模块,SDK 不转出它们。

createLocalPorts 的 i18n 能力也用私有的 i18next 实例,不影响页面其他地方的 useTranslation。

运行时切换

默认的 i18n 能力固定在创建时的 locale。要运行时切换,让它指向交给 I18nextProvider 的那份实例:

src/app.tsx

import { createChatI18n } from "@openmaxai/chat-sdk";
import { createChatHost } from "@openmaxai/chat-openmax/react";
import { useTranslation } from "react-i18next";

const i18n = createChatI18n({ locale: "zh-CN" });

const host = createChatHost({
  baseUrl: "https://openmax.com",
  wsUrl: "wss://openmax.com/ws",
  auth: { mode: "token", getToken },
  orgId: currentOrgId,
  ports: {
    i18n: {
      t: (key, vars) => i18n.t(key, { ns: "chat", ...vars }),
      locale: () => (i18n.language === "zh" ? "zh-CN" : "en-US"),
    },
  },
});

function ChatArea() {
  const { i18n } = useTranslation();
  // 用 i18n.changeLanguage("en") 切换;语言一变就重新挂载聊天。
  return <Chat key={i18n.language} />;
}
  • 例子用的是接 OpenMax 的一行写法,连接那几项见接入 OpenMax。接自己的后台时改用 @openmaxai/chat-sdk/react 的 createChatHost({ adapter, ports }),ports 写法相同。
  • 有些组件会在 vars.ns 里指定别的命名空间,所以 vars 要展开在 ns: "chat" 后面。
  • 依赖 i18n 能力的组件不会因语言变化自动重渲染,所以给聊天子树加 key。重新挂载不会丢失已缓存的会话和消息。

createChatI18n 建的实例两种语言都内置,changeLanguage 不用等加载。它不检测、也不记住语言:用户的选择(cookie、设备语言等)由你读出来作为 locale 传入,调 changeLanguage 时自己保存。

支持的语言

en 和 zh,createChatI18n 和默认的 i18n 能力都内置了这两种。聊天文案在 chat 命名空间,@ 提及面板在 components。