后端前端移动开发【免费下载链接】SparkyFitnessSparkyFitness: Built for Families. Powered by AI. Track food, fitness, water, and health — together.项目地址https://gitcode.com/gh_mirrors/sp/SparkyFitness点击查看免费下载本文系统讲解 SparkyFitness 前端SparkyFitnessFrontend基于i18nextreact-i18next搭建的多语言体系从语言包目录结构、i18next实例配置、React 应用挂载到语言偏好同步、组件内t()调用与设置页语言切换器的完整链路。读完本文你将掌握该项目的国际化技术方案并能独立完成「在代码中新增翻译文案、接入语言切换、为项目添加一门新语言」三类实战任务。1. 核心依赖库与版本SparkyFitness 前端将 i18n 能力拆分为四个 npm 包分工明确全部声明在 SparkyFitnessFrontend/package.json 的dependencies中依赖包作用仓库中的版本i18next核心国际化运行时负责语言包管理、插值、复数与回退^26.4.2react-i18nextReact 集成层提供useTranslationHook 与Trans组件^17.0.13i18next-browser-languagedetector浏览器端语言探测localStorage、cookie、navigator 等^8.2.1i18next-http-backend通过 HTTP 按需加载public/locales下的 JSON 语言包^4.0.2需要特别强调的是协作约定只有英文en语言包允许手工编辑其余语言全部通过 Weblate 众包翻译平台完成翻译再由维护者从 SparkyFitnessTranslations 翻译仓库同步回本仓库。这一约定决定了后续所有工作流见第 8 节「新增语言」。2. 翻译文件结构与 JSON 组织方式所有语言包存放在 SparkyFitnessFrontend/public/locales 目录遵循固定命名规范public/locales/{{languageCode}}/translation.json当前仓库已包含 37 个语言目录ar、ca、cs、da、de、el、en、es、fi、fr、he、hr、hu、id、it、ja、kk、ko、lv、nb-NO、nl、pl、pt、pt-BR、ro、ru、sk、sl、sr、sv、ta、te、tr、uk、yue-Hant、zh-Hans、zh-Hant。注意像nb-NO、pt-BR、zh-Hans这类带区域/脚本修饰符的代码目录名必须与语言代码完全一致。每个translation.json是一个纯 JSON 对象键是翻译标识符值是译文字符串。为了可维护性项目使用嵌套对象组织命名空间等价于用点号路径引用叶子节点{ nav: { diary: Diary, checkin: Check-In }, settings: { profileInformation: { title: Profile Information } } }上面这个例子中nav.diary对应 Diarysettings.profileInformation.title对应 Profile Information。在 语言工具模块 的同级源码里可以看到项目还配合date-fns/locale维护了一套「语言代码 → date-fns 区域对象」的映射如zh-Hans映射到zhCN、yue-Hant映射到zhHK、nb-NO映射到nb用于让日期格式化输出同样跟随用户语言这属于翻译体系之外的本地化配套。3. i18next 实例配置逐参数拆解i18next 实例在 SparkyFitnessFrontend/src/i18n.ts 中集中配置这是整个多语言体系的心脏。以下是仓库中实际生效的完整配置import i18n from i18next; import { initReactI18next } from react-i18next; import LanguageDetector from i18next-browser-languagedetector; import HttpApi from i18next-http-backend; import { getSupportedLanguages } from ./utils/languageUtils; i18n .use(HttpApi) .use(LanguageDetector) .use(initReactI18next) .init({ supportedLngs: getSupportedLanguages(), fallbackLng: en, detection: { order: [ localStorage, querystring, cookie, sessionStorage, navigator, htmlTag, ], caches: [localStorage, cookie], }, backend: { loadPath: /locales/{{lng}}/{{ns}}.json, }, interpolation: { escapeValue: false, }, react: { useSuspense: false, }, }); export default i18n;各配置项的实际影响如下supportedLngs应用向用户开放的语言白名单来自 languageUtils.ts 的getSupportedLanguages()。该函数返回languageDisplayNames对象的所有键。源码注释特别说明该列表必须与public/locales下非空的语言目录保持一致——一个空目录如果被列入白名单用户选择后只会看到全英文界面因此「目录里真正有翻译内容」才是准入条件。fallbackLng: en当前语言缺少某个 key 时的回退语言。也就是说某条文案没翻译时界面会退回英文而不是报错或显示 key 名。detection.order语言探测顺序localStorage排在第一位保证「用户手动保存过的语言偏好」优先于浏览器环境推断其后依次为 URL query 参数、cookie、sessionStorage、浏览器navigator、html标签的lang属性。detection.caches探测到的语言会写入localStorage与cookie便于后续会话快速恢复。backend.loadPath语言包加载的 URL 模板/locales/{{lng}}/{{ns}}.json。{{lng}}会被替换为当前语言代码如de{{ns}}会被替换为命名空间名未指定时默认translation最终请求如/locales/de/translation.json与第 2 节的目录结构一一对应。interpolation.escapeValue: falseReact 默认已对输出做 XSS 转义因此这里关闭 i18next 的二次转义避免译文中的 HTML 实体被双重转义。react.useSuspense: false关闭 React Suspense 挂起模式简化首屏加载逻辑第 4 节详述其行为。需要留意一个容易踩坑的点supportedLngs白名单在语言包目录之外生效。源码注释明确说明未列入白名单的 locale 目录即使存在于public/locales也无法被用户选择——这是「新增语言」时最容易遗漏的一步见第 8 节。4. 注入 React 应用main.tsx 的副效应导入React 应用入口 SparkyFitnessFrontend/src/main.tsx 通过副效应导入side-effect import把 i18n 实例接入应用import { createRoot } from react-dom/client; import App from ./App.tsx; import ./index.css; import ./i18n; // side-effect import: configures the shared i18next instance import { Suspense } from react; // ... createRoot(document.getElementById(root)!).render( Suspense fallbackloading QueryClientProvider client{queryClient} App / /QueryClientProvider /Suspense, );注意import ./i18n没有任何具名导出被使用它的作用是执行模块顶层的i18n.init()让全局共享的 i18next 单例完成初始化。此后任何组件里useTranslation()拿到的都是同一个实例。关于useSuspense: false的行为要理解透彻配置为false时即使某个语言包尚未通过 HTTP 加载完成组件渲染也不会挂起suspend而是先用 fallback 语言即英文渲染待翻译文件到达后自动更新。因此入口处的Suspense fallbackloading并不是为翻译加载服务的如果你希望翻译未就绪时组件真正挂起并显示 fallback需要把useSuspense改为true。项目之所以关闭它是为了简化初始化、避免首屏不必要的等待。5. 语言偏好同步LanguageHandler 组件多语言体系中「用户选择的语言」和「i18next 当前语言」需要保持同步。项目用了一个专用组件 SparkyFitnessFrontend/src/components/LanguageHandler.tsx 来实现它订阅PreferencesContext中的language偏好一旦变化就调用i18n.changeLanguage()。import { useEffect } from react; import { useTranslation } from react-i18next; import { usePreferences } from /contexts/PreferencesContext; const LanguageHandler (): null { const { i18n } useTranslation(); const { language } usePreferences(); useEffect(() { if (language) { i18n.changeLanguage(language); } }, [language, i18n]); return null; }; export default LanguageHandler;几个值得注意的实现细节组件return null不渲染任何 UI纯粹是副作用容器类似一个监听器。在 App.tsx 中它被挂载在PreferencesProvider内部LanguageHandler /位于WaterContainerProvider之后、AppSetup之前保证它能通过usePreferences()读到上下文且在任何业务页面渲染前完成语言对齐。PreferencesContext见 PreferencesContext.tsx中language状态的默认值是en用户已登录时从后端偏好接口加载setLanguageState(data.language || en)未登录时则会从localStorage恢复localStorage.setItem(language, updates.language)/savedLanguage读取并继续写入前端状态。6. 在组件中使用翻译任何 React 组件内只需引入useTranslationHook 即可取到t函数import { useTranslation } from react-i18next; const MyComponent () { const { t } useTranslation(); return ( div h1{t(nav.diary)}/h1 p{t(settings.profileInformation.description)}/p /div ); };t函数接收形如nav.diary的点号路径 key返回当前激活语言下对应的译文字符串若该 key 缺失则按第 3 节所述回退到英文。这套调用方式在仓库里被大量使用例如设置页语言选择器的标签就是t(settings.preferences.language, Language)——注意这里第二个参数是默认值key 不存在时直接显示 Language这是项目中常见的兜底写法。7. 设置页语言切换器永不硬编码的语言列表语言切换器位于设置页的 Preferences 区块实现在 SparkyFitnessFrontend/src/pages/Settings/PreferenceSettings.tsx。它基于 Radix UI 的Select组件核心逻辑是从languageUtils.ts动态拉取语言列表import { getLanguageDisplayName, getSupportedLanguages } from /utils/languageUtils; // ... Select value{language} onValueChange{setLanguage} SelectTrigger SelectValue / /SelectTrigger SelectContent {getSupportedLanguages().map((langCode) ( SelectItem key{langCode} value{langCode} {getLanguageDisplayName(langCode)} /SelectItem ))} /SelectContent /Select两个关键设计列表永不硬编码下拉项完全由getSupportedLanguages()驱动。因此只要在languageUtils.ts的白名单里加入一门新语言切换器会自动出现对应选项无需改任何 JSX。端名展示endonymgetLanguageDisplayName(langCode)返回每种语言以自身语言书写的名称——Deutsch、Español、日本語、简体中文。无论界面当前语言是什么用户看到的都是自己母语的名字避免选语言界面本身就是外语的尴尬。onValueChange{setLanguage}直接更新PreferencesContext中的language状态由于第 5 节的LanguageHandler在监听这个状态语言切换会立即传导到 i18next 并触发整站翻译刷新。8. 新增语言Webleate 协作 白名单启用的完整流程新增一门语言绝不手工创建语言包文件而是遵循以下协作流程翻译发起在 Weblate 平台上申请新语言由翻译者在 Weblate 界面完成翻译全程不触碰本仓库文件。同步回仓库维护者运行Sync TranslationsGitHub Actions 工作流workflow_dispatch手动触发该工作流会把翻译仓库中的非英文语言包复制进public/locales/并自动打开一个 Pull Request供代码评审后合入。白名单启用容易被遗漏的最后一步语言文件同步进来后还需要单独在 SparkyFitnessFrontend/src/utils/languageUtils.ts 中把语言代码加入getSupportedLanguages()和getLanguageDisplayName()两张表。前者让 i18next 接受该语言、让设置页下拉框出现选项后者提供端名显示。如果漏掉这一步public/locales里即使有了目录用户也永远无法选到该语言见第 3 节supportedLngs白名单约束。同理语言包目录languageDisplayNames中只应登记「真正包含翻译内容」的语言——源码注释明确警告把空目录列入白名单只会让用户获得一个全英文界面。所以步骤 2 与步骤 3 必须按顺序完成先有内容、再开放入口。9. 一次完整的语言切换数据流把前面各节串起来用户在设置页切换语言时系统内部经历了这样一条链路PreferenceSettings.tsx的下拉框onValueChange{setLanguage}触发 → 更新PreferencesContext的language状态。LanguageHandler的useEffect依赖[language, i18n]触发 → 调用i18n.changeLanguage(language)。i18next 更新当前语言通过i18next-http-backend按/locales/{{lng}}/{{ns}}.json加载目标语言包首次切换时并由于useSuspense: false先以英文渲染、翻译到达后自动刷新。全站所有调用t(...)的组件重新渲染为对应译文同时PreferencesContext中的formatDateInUserTimezone等日期格式化逻辑通过getDateLocale(language)切换到对应的 date-fns 区域实现日期本地化。10. 实战检查清单修改任何非en语言包前先确认是否应该改为在 Weblate 上翻译新增文案时在public/locales/en/translation.json中按嵌套结构添加 key并在组件中通过t(path.to.key, Fallback)使用。新增语言时依次完成Weblate 翻译 → Sync Translations 工作流同步 → 在languageUtils.ts的getSupportedLanguages()与getLanguageDisplayName()中登记。调试语言问题时优先检查浏览器 DevTools 中/locales/{{lng}}/translation.json的请求是否 200、localStorage/cookie 中缓存的i18nextLng值是否为预期语言。赞分享后端前端移动开发【免费下载链接】SparkyFitnessSparkyFitness: Built for Families. Powered by AI. Track food, fitness, water, and health — together.项目地址https://gitcode.com/gh_mirrors/sp/SparkyFitness点击查看免费下载相关推荐Karakeep国际化Weblate多语言翻译的协作流程Karakeep国际化Weblate多语言翻译的协作流程 Karakeep是一款强大的自托管书签管理应用支持链接、笔记和图片的全方位收藏并具备AI自动标签后端前端移动开发AI 应用知识管理全文检索MCP 服务Pinpoint Web 前端 i18n 国际化开发规范i18next 架构、翻译键管理与多语言实现指南Pinpoint Web 前端 i18n 国际化开发规范i18next 架构、翻译键管理与多语言实现指南 导读 本文基于 Pinpoint 仓库中 Web 前后端可观测性APM链路追踪微服务Woodpecker 前端国际化指南基于 Vue I18n 与 Weblate 的多语言翻译机制Woodpecker 前端国际化指南基于 Vue I18n 与 Weblate 的多语言翻译机制 Woodpecker 的 Web 界面通过社区驱动的翻译平台CI/CDDevOps上一篇Mac Mouse Fix重新定义macOS鼠标体验的智能增强方案下一篇推荐开源项目Plasticity - 重塑你的数字艺术体验创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
)
