NocoBase 翻译贡献指南系统界面、2.0 文档与官网的三层本地化实战【免费下载链接】nocobaseNocoBase is an open-source AI no-code platform for building business systems fast. Instead of generating everything from scratch, AI works on top of production-proven infrastructure and a WYSIWYG no-code interface, so you get both speed and reliability.项目地址: https://gitcode.com/GitHub_Trending/no/nocobaseNocoBase 以英语为默认语言主应用目前支持英语、意大利语、荷兰语、简体中文和日语同时通过一套结构化的多语言贡献体系欢迎社区为更多语言提供翻译。本文以当前仓库为基准系统讲解 NocoBase 本地化的三大层面——系统界面与插件locales目录、2.0 文档docs/docs/lang/目录与官网website 仓库覆盖 JSON 语言包结构、文档翻译工作流、官网混合内容管理方法、新语言接入配置与质量校验脚本帮助读者完整掌握从翻译到提交 Pull Request 的全过程。一、本地化体系总览NocoBase 的多语言内容分散在三个独立层面翻译目标、文件格式与协作方式各不相同层面载体格式内容性质系统界面与插件主仓库locales/目录JSON 键值对运行时的 UI 文案按插件模块组织2.0 文档主仓库docs/docs/lang/目录Markdown / MDX面向用户的文档每种语言一个目录树官网独立的 website 仓库Markdown / JSON / Astro官网页面、博客、教程等营销与内容页面三者的共同原则是以英文为源语言其他语言的翻译严格镜像英文的结构与命名从而保证内容不缺失、链接不失效、格式不破坏。二、系统界面与插件本地化2.1 翻译范围界定系统本地化仅适用于 NocoBase 系统界面和插件的本地化不包括其他自定义内容例如用户自行创建的数据表名称或 Markdown 区块中的正文。也就是说翻译的是产品框架本身暴露的文案而不是用户在平台上录入的业务数据。2.2 locales 目录与 JSON 语言包结构NocoBase 使用 Git 管理本地化内容语言包集中存放在主仓库的locales目录。每种语言由一个以语言代码命名的 JSON 文件表示例如de-DE.json、fr-FR.json。当前仓库中实际维护了包括en-US.json、zh-CN.json、ja-JP.json、ko-KR.json、pt-BR.json、ru-RU.json、vi-VN.json、zh-TW.json、it-IT.json、nl-NL.json、tr-TR.json、uk-UA.json、id-ID.json、hu-HU.json、es-ES.json、fr-FR.json等在内的多份语言文件完整语言代码清单见 locales/README.md。语言文件按插件模块组织为嵌套对象使用键值对存储翻译。原始结构示例如下{ // 客户端插件 nocobase/client: { (Fields only): (Fields only), 12 hour: 12 hour, 24 hour: 24 hour // ...其他键值对 }, nocobase/plugin-acl: { // 此插件的键值对 } // ...其他插件模块 }翻译时将其逐步转换为目标语言例如{ // 客户端插件 nocobase/client: { (Fields only): (仅字段 - 已翻译), 12 hour: 12 小时, 24 hour: 24 小时 // ...其他键值对 }, nocobase/plugin-acl: { // 此插件的键值对 } // ...其他插件模块 }从仓库实现看locales/en-US.json 正是这一结构的真实样本它包含近六千行键值对顶层即nocobase/client与各插件命名空间键名保持英文原文如Add record、Action permissions值在非英语文件中替换为对应译文。2.3 插件的独立 locale 目录除了顶层locales/汇总目录每个插件在自身源码内也维护语言文件。例如 packages/plugins/nocobase/plugin-acl/src/locale 下就存在en-US.json、zh-CN.json、de-DE.json、fr-FR.json、ja-JP.json、ko-KR.json、pt-BR.json、ru-RU.json、vi-VN.json、zh-TW.json等十余份语言文件。这种插件内 locale 目录 顶层汇总的双层结构便于插件开发者就近维护自己的文案再由汇总流程归并到locales/顶层文件。2.4 翻译测试与同步完成翻译后需要测试并验证所有文本是否正确显示。官方提供了一款翻译验证插件——在插件市场中搜索Locale tester。用法为从 Git 仓库中的对应本地化文件复制 JSON 内容粘贴到插件输入框中点击确定即可验证翻译内容是否生效。翻译提交后系统脚本会自动将本地化内容同步到代码仓库。仓库中的 scripts/addEnKeysFromZh.js 展示了这类同步脚本的实现思路它读取zh-CN.json的键集合若英文文件en-US.json缺少相应键则将键键名即英文原文合并回en-US.json从而保证英文语言包始终覆盖全部键该脚本还支持diff与all两种模式——diff模式只处理暂存区中src/**/locale/baseLang.json的增量改动all模式则按./packages/**/src/**/locale/baseLang.json的 glob 模式全量扫描插件内语言文件。2.5 NocoBase 2.0 本地化插件注意此部分正在开发中。NocoBase 2.0 的本地化插件与 1.x 版本存在一些差异详细信息将在后续版本更新中提供。三、文档本地化NocoBase 2.0NocoBase 2.0 的文档采用全新结构管理文档源文件位于主仓库的docs/目录。3.1 文档结构与静态站点生成器文档使用Rspress作为静态站点生成器对应配置文件为 docs/rspress.config.ts其中通过DOCS_LANG环境变量选择构建语言、通过DOCS_BASE设置站点基础路径并声明了cn→zh的 i18n 别名映射当前支持 8 种语言。目录结构组织如下docs/ ├── docs/ │ ├── en/ # 英语源语言 │ ├── cn/ # 简体中文 │ ├── ja/ # 日语 │ ├── de/ # 德语 │ ├── fr/ # 法语 │ ├── es/ # 西班牙语 │ ├── pt/ # 葡萄牙语 │ ├── ru/ # 俄语 │ └── public/ # 共享资源图片等 ├── theme/ # 自定义主题 ├── rspress.config.ts # Rspress 配置 └── package.json在 docs/docs 下可以同时看到en、cn、ja、de、fr、es、pt、ru等语言目录以及id印尼语、vi越南语等额外语言目录印证了该多语言目录树结构。3.2 翻译工作流与英文源同步所有翻译应基于英文文档docs/en/。当英文文档更新时翻译应相应更新。分支策略使用develop或next分支作为最新英文内容的参考从目标分支创建自己的翻译分支。文件结构镜像每个语言目录应完整镜像英文目录结构。例如docs/en/get-started/index.md → docs/ja/get-started/index.md docs/en/api/acl/acl.md → docs/ja/api/acl/acl.md3.3 贡献翻译的实操步骤Fork 主仓库克隆自己的 fork 并检出develop或next分支导航到docs/docs/目录找到目标语言目录例如日语为ja/翻译 markdown 文件保持与英文版本相同的文件结构在本地测试更改cd docs yarn install yarn dev向主仓库提交 Pull Request。3.4 翻译指南保持格式一致保持与源文件相同的 markdown 结构、标题、代码块和链接保留 frontmatter保持文件顶部的 YAML frontmatter 不变除非其中包含可翻译的内容。当前文档如 docs/docs/cn/get-started/translations.md顶部即带有title、description、keywords等 frontmatter 字段图片引用使用来自docs/public/的相同图片路径图片在所有语言之间共享内部链接更新内部链接以指向正确的语言路径代码示例通常代码示例不应翻译但代码中的注释可以翻译。3.5 导航配置每种语言的导航结构由该语言目录下的_nav.json与_meta.json文件定义。添加新页面或章节时必须同步更新这些配置文件。仓库中的实际示例docs/docs/cn/_nav.json定义顶部导航条目开始、AI、教程、手册、开发、插件、API、首页每项包含text与link字段docs/docs/cn/get-started/_meta.json定义侧边栏结构支持type: custom-link自定义链接条目、type: file对应实际文档文件以及带items的分组结构。3.6 质量保障结构对齐与 i18n 覆盖校验仓库为多语言文档提供了自动化质量检查脚本集中封装在 docs/check.sh 中支持--langcode、--filespath、--with-i18n-coverage等参数运行时会依次执行Tree alignment checkcheck-tree-alignment.mjs校验各语言目录树结构是否对齐Meta alignment checkcheck-meta-alignment.mjs校验_meta.json链接是否与文件对应Navigation alignment checkcheck-nav-alignment.mjs校验_nav.json导航配置Home alignment checkcheck-home-alignment.mjs校验首页内容Bloated files check、Deprecated document reference check分别检查膨胀文件与废弃文档引用。其中 check-i18n-coverage.mjs 负责 i18n 覆盖校对它单向检查简体中文改动是否同步到了其他 9 种语言en / ja / es / pt / de / fr / id / vi / ru若某次 PR 中 cn 的.md/.mdx文件被修改而目标语言的同名文件未在本次改动中则标记为STALE并以退出码 1 提示。注意该脚本不会因单独修正其他语言的错别字而报错阿拉伯语ar则不在维护校对范围内。典型用法gh pr view pr --json files --jq .files[].path | node check-i18n-coverage.mjs node check-i18n-coverage.mjs --fileschanged.txt四、官网本地化官网页面与全部内容存储于独立的 website 仓库不在本仓库内其本地化方法与系统界面、文档均不相同。4.1 混合内容管理方法官网采用混合内容管理英语、中文和日语的内容与资源会定期从 CMS 系统同步并覆盖其他语言则可以直接在本地文件中编辑。本地内容存储在content目录中组织如下/content /articles # 博客文章 /article-slug index.md # 英语内容默认 index.cn.md # 中文内容 index.ja.md # 日语内容 metadata.json # 元数据和其他本地化属性 /tutorials # 教程 /releases # 发布信息 /pages # 一些静态页面 /categories # 分类信息 /article-categories.json # 文章分类列表 /category-slug # 单个分类详情 /category.json /tags # 标签信息 /article-tags.json # 文章标签列表 /release-tags.json # 发布标签列表 /tag-slug # 单个标签详情 /tag.json /help-center # 帮助中心内容 /help-center-tree.json # 帮助中心导航结构 ....4.2 内容翻译指南Markdown 内容翻译基于默认文件创建新的语言文件例如index.md→index.fr.md在 JSON 文件的相应字段中添加本地化属性保持文件结构、链接和图片引用的一致性。JSON 内容翻译许多内容元数据存储在 JSON 文件中通常包含多语言字段{ id: 123, title: English Title, // 英语标题默认 title_cn: 中文标题, // 中文标题 title_ja: 日本語タイトル, // 日语标题 description: English description, description_cn: 中文描述, description_ja: 日本語の説明, slug: article-slug, // URL 路径通常不翻译 status: published, publishedAt: 2025-03-19T12:00:00Z }翻译注意事项字段命名约定翻译字段通常使用{原字段}_{语言代码}格式例如title_fr法语标题、description_de德语描述添加新语言时为每个需要翻译的字段添加相应的语言后缀版本且不要修改原字段值如title、description等因为它们作为默认语言英语内容CMS 同步机制CMS 系统定期更新英语、中文和日语内容且只更新/覆盖这三种语言的内容JSON 中的某些属性不会删除其他贡献者添加的语言字段。例如若您添加了法语翻译title_frCMS 同步不会影响此字段。4.3 配置新语言支持要添加对新语言的支持需要修改官网源码src/utils/index.ts中的SUPPORTED_LANGUAGES配置export const SUPPORTED_LANGUAGES { en: { code: en, locale: en-US, name: English, default: true }, cn: { code: cn, locale: zh-CN, name: Chinese }, ja: { code: ja, locale: ja-JP, name: Japanese }, // 添加新语言示例 fr: { code: fr, locale: fr-FR, name: French } };每个语言对象至少包含code语言代码、locale区域标识如zh-CN、name语言名称default: true用于标记默认语言英语。4.4 布局文件与语言页面目录布局文件每种语言需要相应的布局文件例如法语为src/layouts/BaseFR.astro。可以复制现有布局文件如BaseEN.astro并翻译其中的全局元素导航菜单、页脚等同时确保更新语言切换器配置以正确切换到新添加的语言。语言页面目录在src目录中创建以语言代码命名的文件夹例如src/fr/从其他语言目录复制页面结构例如src/en/更新页面内容将标题、描述和文本翻译成目标语言确保页面使用正确的布局组件例如.layout: /layouts/BaseFR.astro。组件本地化检查src/components/目录中的组件特别注意带有固定文本的组件如导航栏、页脚。组件可能使用条件渲染来显示不同语言的内容{Astro.url.pathname.startsWith(/en) pEnglish content/p} {Astro.url.pathname.startsWith(/cn) p中文内容/p} {Astro.url.pathname.startsWith(/fr) pContenu français/p}4.5 测试和验证完成官网翻译后进行全面测试在本地运行网站通常使用yarn dev检查所有页面在新语言中的显示效果验证语言切换功能是否正常工作确保所有链接指向正确的语言版本页面检查响应式布局确保翻译文本不会破坏页面设计。五、如何开始翻译组件、仓库与分支对照组件仓库分支备注系统界面NocoBase 主仓库locales/目录mainJSON 本地化文件文档2.0NocoBase 主仓库develop/nextdocs/docs/lang/目录官网website 仓库main参见第四节完成翻译后请向 NocoBase 提交 Pull Request。新语言将出现在系统配置中允许用户选择要显示的语言。六、NocoBase 1.x 文档本指南对应 NocoBase 2.0 的本地化体系。关于 NocoBase 1.x 的翻译指南请查阅仓库中 1.x 时期遗留的社区文档docs-cn.nocobase.com/welcome/community/translations对应的历史内容其结构与 2.0 的docs/docs/lang/目录体系有所不同。核心要点回顾系统界面翻译关注locales/下按插件模块组织的 JSON 语言包并通过Locale tester插件验证2.0 文档翻译以docs/en/为源、逐语言镜像目录树受_nav.json/_meta.json导航配置与 check.sh 质量脚本约束官网翻译则遵循字段后缀 不覆盖他语言字段的混合内容管理约定。三者共同构成了 NocoBase 完整、可自动校验的多语言贡献链路。【免费下载链接】nocobaseNocoBase is an open-source AI no-code platform for building business systems fast. Instead of generating everything from scratch, AI works on top of production-proven infrastructure and a WYSIWYG no-code interface, so you get both speed and reliability.项目地址: https://gitcode.com/GitHub_Trending/no/nocobase创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考