企业官网建设流程全解析

smc.peering.tw 是一个展示台湾海底电缆实时状态的国际化工具仪表盘，支持繁体中文与英文双语界面。本文以该项目为例，手把手带你用 i18next 国际化方案实现 React 项目的繁中/英文一键切换，涵盖语言包组织、localStorage 记忆、语言切换器三大核心技巧。

项目亮点：多语言支持如何落地

smc.peering.tw 的技术栈为 React + TypeScript + Vite，其 README.md 中将Multi-language Support（多语言支持）列为核心特性之一。整个国际化功能由三个部分组成：

这种「代码与文案分离」的设计是 i18next 国际化的最佳实践：开发时不写死任何界面文字，全部通过 key 查找，换语言包即可扩展新语言。

第 1 步：安装 i18next 国际化依赖

在 package.json 中，项目安装了三组核心依赖：

"i18next": "^25.2.1", "i18next-browser-languagedetector": "^8.2.0", "react-i18next": "^15.5.3"

它们各司其职：

• i18next：国际化核心引擎，负责资源存储与翻译查找
• react-i18next：React 绑定层，提供useTranslationHook
• i18next-browser-languagedetector：浏览器语言检测器（本项目作为可选扩展，见文末「进阶技巧」）

第 2 步：编写 i18next 初始化文件

整个国际化的「大脑」只有 31 行代码，位于 src/i18n/index.ts，关键配置如下：

i18n .use(initReactI18next) .init({ lng: storedLng || undefined, supportedLngs: ["en", "zh-TW"], resources: { en: { translation: enTranslations }, "zh-TW": { translation: zhTWTranslations }, }, fallbackLng: "en", });

逐行拆解三个关键配置：

用 localStorage 记忆用户语言偏好

const storedLng = typeof window !== "undefined" ? (window.localStorage.getItem("i18nextLng") ?? "").trim() : "";

打开时读取i18nextLng这个 localStorage 键，有记录就用用户上次的选择，没有则交给兜底逻辑。用户切换一次语言，之后每次访问都自动保持——这是国际化体验的细节所在。

supportedLngs 声明支持的语言

["en", "zh-TW"]明确声明只支持英文和繁体中文，避免 i18next 为不支持的语言做无谓回退。

fallbackLng 设置兜底语言

fallbackLng: "en"表示：如果某个 key 在繁中语言包里缺失，自动回退到英文。这保证界面**永远不会出现「key 裸露」**的尴尬。

第 3 步：组织双语语言包

两个 JSON 文件采用完全一致的嵌套结构，通过分组 key管理全站文案。以界面侧边栏为例，en.json 与 zh-tw.json 成对出现：

"tab": { "incidents": "Incidents", "timeline": "Timeline", "topology": "Topology", "about": "About" }

"tab": { "incidents": "事件", "timeline": "時間軸", "topology": "拓撲", "about": "關於" }

语言包中还有两个值得学习的细节：

1. 插值变量：zh-tw.json 中"uptimePercentage": "{{value}}% 可用率"，通过{{value}}占位符把动态数字嵌入固定句式，两种语言的语序还能不同。
2. HTML 内容：英文的免责提示中直接用<br>排版长段落，配合初始化时escapeValue: false的配置，让翻译文案支持富文本。

第 4 步：在组件中用 t() 调用翻译

React 组件通过useTranslationHook 拿到翻译函数t和实例i18n。src/components/OutageCounter.tsx 的用法非常典型：

const { t } = useTranslation(); // ... {t("common.online")} // 英文显示 Online，繁中显示「正常」

再看 src/components/Sidebar.tsx 的一个防漏技巧——defaultValue：

{t(tab.labelKey, { defaultValue: tab.id })}

万一语言包缺少该 key，显示 key 本身对应的默认值而非乱码，属于国际化的「双保险」。

项目中共有 17 个组件调用了useTranslation，覆盖地图、事件列表、时间轴、拓扑图等全部界面，真正做到零硬编码文案。

第 5 步：打造一键切换语言按钮 🌐

这是用户能直接感知的功能。项目的切换逻辑封装在 src/components/Sidebar.tsx 的ChangeLanguageButton中：

function changeLanguage(lang: string) { localStorage.setItem("i18nextLng", lang); i18n.changeLanguage(lang); } // 点击即翻转：英文 → zh-TW，繁中 → 英文 onClick={() => i18n.language === "en" ? changeLanguage("zh-TW") : changeLanguage("en") }

两步走：先写入 localStorage 持久化，再调用i18n.changeLanguage立即生效。得益于 i18next 与 React 的响应式绑定，全界面文字瞬间更新，无需刷新页面。

首次访问的语言选择弹窗

用户第一次打开网站、没有语言偏好时怎么办？src/App.tsx 检测到 localStorage 为空，就弹出强制选择的语言弹窗 src/components/dialog/LanguageSelect.tsx：

function selectLanguage(lng: "en" | "zh-TW") { localStorage.setItem(LANG_KEY, lng); i18n.changeLanguage(lng); onDone(); }

这个弹窗标题特意写成Select language / 選擇語言双语——因为用户还没选语言，界面本身无法确定该显示什么语言，这是一个很巧妙的边界处理。

进阶技巧：同步 HTML 的 lang 属性

src/App.tsx 还有一处容易被忽略的好实践：

useEffect(() => { document.documentElement.lang = i18n.language; }, [i18n.language]);

切换语言时同步更新<html lang>标签。这能让浏览器正确进行繁中/英文的断词、拼写检查与屏幕阅读器朗读，是国际化完整性的最后一块拼图。

总结：一套可复用的 i18next 国际化清单

回顾 smc.peering.tw 的实践，你的 React 项目按同样五步即可复制这套繁中/英文切换方案：

1. ✅ 安装i18next+react-i18next依赖
2. ✅ 编写初始化文件：声明supportedLngs与fallbackLng，用 localStorage 记忆语言
3. ✅ 维护结构对齐的双语 JSON 语言包
4. ✅ 组件内统一用t()取文案，善用defaultValue与{{插值}}
5. ✅ 提供切换按钮 + 首次访问选择弹窗，并同步document.documentElement.lang

完整代码可参照 src/i18n/ 目录及 src/components/Sidebar.tsx、src/components/dialog/LanguageSelect.tsx，总代码量不到 200 行，却能给整个仪表盘带来流畅的双语体验。