企业官网建设流程全解析

Langfuse 国际化实录：一个"Traces"按钮上的字是怎么变身的？

【免费下载链接】langfuse🪢 Open source AI engineering platform: LLM evals, observability, metrics, prompt management, playground, datasets. Integrates with OpenTelemetry, LangChain, OpenAI SDK, LiteLLM, and more. 🍊YC W23项目地址: https://gitcode.com/GitHub_Trending/la/langfuse

如果你在用 Langfuse 做 LLM 可观测性——tracing、evals、prompt 管理那套——大概率也琢磨过Langfuse 多语言支持这件事：自托管给日本同事用，满屏英文报错，人家直接关掉了。说白了，i18n 就是让界面跟着用户的语言走。这篇文章不空谈方案，我们从仓库里真实存在的配置和代码出发，追踪一个界面上的词从源码到渲染的完整路径，再给你一份能落地的国际化实施清单和避坑指南。

先泼盆冷水：Langfuse 界面现在是单语言的

很多人看仓库根目录有 README.cn.md、README.ja.md、README.kr.md，就以为界面也能切中文。文档翻译 ≠ 界面翻译，这是两码事。

打开 next.config.mjs，i18n 配置长这样：

i18n: { locales: ["en"], // 只声明了英语一种 defaultLocale: "en", },

再翻一遍 web/package.json 的依赖列表，i18next、react-intl、next-i18next统统没有。这意味着 Langfuse 目前的国际化现状是：

结论很直接：给 Langfuse 界面加日语，是一个你自己要动手的项目。好消息是它的技术栈（Next.js 16 + React 19 + Tailwind）对 i18n 相当友好，下面是完整路径。

追踪一个"Traces"：文案在代码里是怎么活的

在 Langfuse 侧边栏导航里，"Traces"、"Prompts"、"Settings" 这些词是怎么来的？以 AppSidebar 组件为例，导航项长这样：

navItems: { ungrouped: [ { title: "Home", url: "/", icon: Home }, { title: "Traces", url: "/traces", icon: Activity }, { title: "Prompts", url: "/prompts", icon: BookOpen }, ], },

看到了吗？title: "Traces"——字面量直接硬编码在 JSX/props 里。没有 key，没有资源文件，没有翻译中间层。整个数据流退化成了：

你做的事情，本质上是把箭头 A→B 这条"直连"，改造成"先查翻译表再渲染"的 A→D→E→B。这也解释了为什么加语言的第一步是提取文案而不是"建语言文件"——文件建了，但源码里还是硬编码，界面一个字都不会变。

三步给界面装上翻译：提取 → 资源文件 → 切换器

以新增日语为例，路径和 语言资源目录建议结构 src/locales/ 如下（Langfuse 仓库中尚无此目录，以你实际 fork 为准）。

第 1 步：提取文案。全局搜title: "、>后跟大写开头单词，把硬编码字符串换成 key。侧边栏那几行变成：

{ title: t("nav.traces"), url: "/traces", icon: Activity } // 资源文件里定义：ja/traces 对应的日文

第 2 步：建立资源文件。按模块拆 JSON，别塞一个大文件：

src/locales/ ├── en/ nav.json traces.json └── ja/ nav.json traces.json

// ja/nav.json —— 键与英文一一对应 { "nav.traces": "トレース", "nav.prompts": "プロンプト" }

第 3 步：声明 locale 并做切换。在next.config.mjs的 i18n 块把locales扩成["en", "ja"]，切换器用useRouter的 locale 能力：

const { locale, locales, push, asPath } = useRouter(); <select value={locale} onChange={(e) => push(asPath, undefined, { locale: e.target.value })}> {locales.map((l) => <option key={l}>{l}</option>)} </select>

注意：next.config.mjs顶部注释提醒过，若项目启用experimental.appDir，内置 i18n 需注释掉（见 Next.js 官方 issue 41980）。Langfuse 主应用跑在 Pages Router 上，这套配置可用；具体以你的分支版本为准。

四个高频坑：问题 → 原因 → 解法

坑 1：缺翻译时界面直接崩。原因是只查了目标语言文件，没查默认语言。解法是兜底链：先查 ja，查不到回退 en，再查不到回退 key 本身：

const t = (locale, key) => messages[locale]?.[key] ?? messages.en?.[key] ?? key;

坑 2：德语把按钮撑爆。同一句提示，德语经常比英语长 30%。解法是布局上给文字留弹性：按钮用min-width而非固定宽度，表格列用min-w-[100px]+truncate，别写死w-40。

坑 3：日期是死的。Langfuse 源码里大量 date-fns 格式串直接写英文模板，比如 DatasetVersionHistoryPanel 里的format(version, "MMM d, yyyy 'at' h:mm a")——对日本用户输出的是 "Sep 1, 2026 at 9:05 AM"。解法是统一走Intl.DateTimeFormat，按navigator.language取 locale，别手写模板串。

坑 4：切换语言整页刷新，状态全丢。用内置push带 locale 会触发整页导航，用户筛选条件、展开的表格全没了。解法是优先做客户端级切换：翻译资源放 Context/Store 里，切换只重渲染不跳路由；确需路由级 locale 前缀时，切换前把关键状态存 localStorage。

（附）RTL 布局：若未来支持阿拉伯语，Tailwind 里别用left-4这类物理方向类，换start-4/end-4逻辑方向类，省掉整套[dir="rtl"]覆盖。

从 2 种语言到 20 种：规模化工作流

语言一旦超过 3 种，靠人肉 diff 必挂。三件套：

1. 术语表先行。产品核心词先定死：Trace / Observation / Evaluation / Prompt 在中日韩怎么译，写进一份术语表，翻译前分发。否则 20 种语言 20 种译法，客服会疯。
2. CI 完整性检查。加一个脚本遍历所有 locale 目录，校验键集合与en完全一致，缺键、多键、空值直接让流水线红掉。提取 + 校验两条命令挂到 pre-commit 和 CI 各一份。
3. AI 初翻 + 人工审校。让 LLM 批量产出初稿塞进资源文件，人工只审术语一致性和语气。初翻覆盖率能到 90%，人力成本砍掉一大半——注意 AI 翻出来的术语仍要过术语表校对，别省这一步。

快速参考

一句话总结：Langfuse 目前是"文档多语言、界面单语言"，而它的 Next.js + 硬编码文案结构，恰好给了你一条清晰的改造路径。现在就可以去 fork，打开next.config.mjs的那个locales: ["en"]，把"ja"加进去，然后从侧边栏的 "Traces" 开始提第一个 key。

【免费下载链接】langfuse🪢 Open source AI engineering platform: LLM evals, observability, metrics, prompt management, playground, datasets. Integrates with OpenTelemetry, LangChain, OpenAI SDK, LiteLLM, and more. 🍊YC W23项目地址: https://gitcode.com/GitHub_Trending/la/langfuse