【免费下载链接】blumeThe open-source docs framework for humans and agents.项目地址https://gitcode.com/gh_mirrors/blum/blume点击查看免费下载Blume 是面向人类和 AI Agent 的开源文档框架其国际化i18n能力让一个文档项目可以同时以多种语言发布把翻译文件放进对应目录Blume 会自动完成多语言路由、语言切换器、分语言导航、本地化搜索和 hreflang SEO无需维护任何独立的路由层。本指南面向新手带你从零配置多语言文档并用 AI 自动完成文档翻译。一、为什么用 Blume 做多语言文档很简单大多数文档框架做国际化要自己写路由、语言切换、hreflang 逻辑而 Blume 的设计是约定优先convention-first✅ 它是可选功能——不配置i18n时站点保持单语言原有 URL 完全不变✅ 翻译文件放对位置即自动生效目录即路由✅ 未翻译页面自动回退fallback到默认语言不会出现死链✅ 内置 30 语言的界面翻译包搜索、在 GitHub 上编辑等 UI 文案开箱即译✅ 配套blume translate命令用 AI Agent 自动补齐缺失和过期的翻译Blume 官方文档站本身就是多语言文档的活例子它同时发布了en默认、de、hi、ja、pt五种语言配置可见 blume.config.ts。二、3 步启用多语言路由配置 i18n 块只需在blume.config.ts中加一个i18n块列出语言和支持的语言i18n: { defaultLocale: en, locales: [ { code: en, label: English }, { code: fr, label: Français }, { code: ar, label: العربية, dir: rtl }, ], }每个语言有三个关键属性属性作用code语言代码直接成为 URL 前缀如/fr/…label显示在语言切换器里的名字dir可选设为rtl支持阿拉伯语、希伯来语等从右到左的文字还有两个实用开关hideDefaultLocalePrefix: false—— 默认情况下英文等默认语言没有前缀/guides/quickstart其他语言带前缀/fr/guides/quickstart。设为false可让所有语言都带前缀/en/…、/fr/…URL 风格统一。routeByBrowserLanguage: true—— 访客从站外进入首页时按浏览器首选语言自动跳转到对应语言的首页fr-CA也能匹配到fr。该重定向在浏览器端运行静态托管也生效读者一旦手动切换过语言就不再自动跳转。完整的国际化路由逻辑集中在 packages/blume/src/core/i18n.ts 中所有路由规则只写在这一处。三、多语言内容目录规范locale 文件夹与文件后缀方式一按语言建顶层文件夹推荐。默认语言放在内容根目录其余每种语言一个与code同名的顶层文件夹结构镜像默认语言docs/ index.mdx → / guides/quickstart.mdx → /guides/quickstart fr/ guides/quickstart.mdx → /fr/guides/quickstart ar/ index.mdx → /ar注意默认语言不要单独建文件夹如docs/en/否则它会被当成普通内容发布到/en/…Blume 会给出警告。方式二文件后缀。如果只翻译了少数几个页面可设置parser: dot让翻译文件和原文放在一起docs/guides/quickstart.mdx → /guides/quickstart docs/guides/quickstart.fr.mdx → /fr/guides/quickstart共享文件某些内容所有语言都一样比如 changelog、状态页在文件名里加$标记一个文件服务所有语言docs/changelog.$.mdx会同时发布到/changelog和/fr/changelog。官方文档站就是标准示范德语翻译位于 apps/docs/content/de/docs/目录结构与英文原文完全镜像。四、本地化导航每个语言独立的侧边栏每个语言的侧边栏由该语言自己的文件生成因此各语言的导航可以独立变化结构、顺序和标题。文件夹的 meta.ts 文件同样按语言解析在fr/guides/下放一个meta.ts就能独立调整法语分组的排序和标题。头部标签页、页头链接和页脚是配置出来的而非从内容推导所以它们的文案用按语言映射的方式本地化任何标签都支持字符串或映射两种写法navigation: { cta: { href: https://acme.dev/signup, label: { en: Start free, fr: Essai gratuit }, }, }, footer: { links: [ { label: { en: Pricing, fr: Tarifs }, href: https://acme.dev/pricing }, ], },未填写的语言会自动回退到默认语言。此外标签页路径、页头页脚链接也会自动跟随读者的语言进入对应 locale让整页待在同一种语言里。Blume 官方文档站的页脚就用了这种映射{ href: https://github.com/sponsors/haydenbleasel, label: { de: Sponsern, en: Sponsor, hi: प्रायोजक बनें, ja: スポンサー, pt: Patrocinar, }, }摘自 apps/docs/blume.config.ts五、自动回退机制翻译不全也不会出现坏链接这是 Blume 国际化对新手最友好的一点。某页还没翻译时Blume 会在该语言的 URL 下渲染回退语言的内容默认回退到defaultLocale设为fallbackLocale: null则改为 404链接永远可点页面完全预渲染搜索引擎不会走进死胡同回退页的 canonical 指向被复制的源页不会和真实翻译互相竞争排名回退页不进入搜索索引、llms.txt和 JSON API 页面列表也不会在hreflang里冒充已翻译但它仍出现在该语言的侧边栏里导航保持完整 建议策略先翻译最重要的页面——首页、快速上手和核心指南——其余的回退兜底之后慢慢补齐即可任何时刻都不会断链。跨语言链接也是自动的在法语页面里照常用Setup写法Blume 渲染时会把它移到/fr/guides/setup已带语言前缀的链接保持原样方便显式跨语言引用。六、用 AI 自动完成文档翻译blume translate翻译不用全靠手打。blume translate会找出每个语言中缺失或过期的页面用本地 AI Agent CLICodex 或 Claude Code无头翻译blume translate --codexblume translate 3 item(s) · 2 locale(s) · Codex ✔ docs/guides/install.mdx → fr 24.2s ✔ docs/guides/install.mdx → de 22.8s ✔ meta titles (2) → de 4.1s Translated 3 files into 2 locales · 51.1s几个保障质量的关键设计结构由 Blume 掌控Agent 只翻译文本标题、代码块数量、frontmatter 由 Blume 校验并基于源文件重建校验失败的内容不会写入。标题锚点自动对齐每个译文标题会被钉住源标题的#id保证#fragment链接在所有语言中都能解析。翻译台账每次翻译记录源文件哈希到 blume.translations.json提交这个文件后重跑只翻译有变化的页面——增量、幂等。手写翻译会被采纳而非覆盖。CI 门禁blume translate --check只报告漂移不写文件翻译过期时以非零码退出可直接加入流水线拦截原文改了、译文没跟上。在 locale 配置里加style如Brazilian Portuguese, informal você可钉住语域和术语从第一篇翻译起风格就统一。相关实现见 packages/blume/src/translate/。七、已翻译的界面30 语言 UI 翻译包开箱即用本页面、搜索、上/下一页这类界面文案Blume 自带 30 多种语言的翻译包阿拉伯语、简体中文、繁体中文、日语、韩语、德语、法语、西语、葡语、俄语、泰语……存放在 packages/blume/src/core/ui-packs/。你只需要翻译自己的内容。缺失或未内置的字符串会回退到默认语言再到英语要覆盖某条文案用i18n.ui按语言设置即可i18n: { ui: { fr: { search: { button: Rechercher, placeholder: Rechercher… }, page: { previous: Précédent, next: Suivant }, }, }, }八、分语言搜索、RTL 布局与本地化 SEO搜索按语言隔离在/fr/…页面打开搜索框默认只返回法语结果并可切换All languages跨语言搜索。中日韩文档的分词与搜索场景可参考官方指南 cjk-documentation-search。RTL 从右到左给某个语言设dir: rtlBlume 会镜像整个界面侧边栏、页头、目录、分页、搜索、菜单并设置html dir。代码块刻意保持左到右代码永远 LTR 阅读回退内容也保持其原文方向避免英文内容出现在 RTL 布局里读起来别扭。本地化 SEO 全自动无需逐页写元数据html lang与dir按当前语言设置hreflang标注每个页面的所有真实翻译外加指向默认语言的x-defaultcanonical URL 按语言修正JSON-LD 携带inLanguage建议同时设置deployment.site让以上链接以绝对 URL 输出。上线后可用blume audit审计这些 SEO 细节。九、上手清单从单语言到多语言文档站点⚙️ 在blume.config.ts添加i18n块defaultLocalelocales 按语言建顶层文件夹或parser: dot后缀放入翻译文件 需要独立导航时在语言文件夹下放各自的meta.ts️ 页头/页脚/CTA 标签改用{ en: …, fr: … }映射 跑blume translate --codex批量补齐翻译提交台账文件 CI 中加blume translate --check防止翻译漂移 上线后验证 hreflang、语言切换器和分语言搜索核心资料索引国际化官方文档content/i18n.mdx翻译命令参考cli/translate.mdx路由核心实现core/i18n.tsUI 翻译包目录core/ui-packs/官方站多语言配置实例apps/docs/blume.config.tsBlume 的国际化和版本管理也能组合使用——冻结的旧版本快照保留各自的翻译回退逻辑在每个版本内部独立工作。对新手来说最实用的路径就是配置i18n→ 放几个翻译文件 → 让回退兜底 → 用blume translate逐步把全站翻完。赞分享【免费下载链接】blumeThe open-source docs framework for humans and agents.项目地址https://gitcode.com/gh_mirrors/blum/blume点击查看免费下载相关推荐OmniRoute 多语言国际化i18n实战指南42 语言 UI、LLM 增量文档翻译与 CLI 本地化全链路解析OmniRoute 多语言国际化i18n实战指南42 语言 UI、LLM 增量文档翻译与 CLI 本地化全链路解析 本文以 OmniRoute 仓库的 d后端API网关LLM 网关人工智能大模型MCP 服务桌面应用kepler.gl 国际化与本地化翻译指南新增语言、更新翻译与多语言接入实战kepler.gl 国际化与本地化翻译指南新增语言、更新翻译与多语言接入实战 导读 kepler.gl 是面向大规模地理空间数据集的开源可视化分析工具其完数据可视化前端GISFinRL-Library文档本地化多语言翻译完整指南FinRL Library文档本地化多语言翻译完整指南 FinRL Library作为金融强化学习领域的重要开源项目其文档本地化对于扩大全球用户群体至关重要金融科技强化学习人工智能创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
