Vendure Admin UI 全面解析Angular 管理后台的架构、构建与国际化【免费下载链接】vendureOpen-source headless commerce platform built with TypeScript, NestJS, React, and GraphQL项目地址: https://gitcode.com/GitHub_Trending/ve/vendure本指南以 Vendure 开源仓库中的 Admin UI 包说明文档 为核心系统讲解 Vendure 管理后台的代码结构、构建发布流程与多语言本地化机制。读者将掌握vendure/admin-ui库的模块划分与 npm 发布方式、如何用bun run build产出可分发的package目录、如何通过bun run extract-translations自动抽取并统计翻译词条以及如何为 Admin UI 添加一门全新的界面语言。一、什么是 Vendure Admin UIVendure 是一个基于 TypeScript、NestJS、React 与 GraphQL 构建的开源无头headless电商平台而Admin UI 是它的管理后台界面用于让商店运营人员完成从库存管理到订单跟踪的日常管理工作。从仓库结构看Admin UI 具备两大身份见 packages/admin-ui/README.md一个 Angular 应用使用 Angular CLI 构建整个 UI 由 Clarity Design System 中可以确认其技术栈Angular 19、Apollo Client/Apollo AngularGraphQL 客户端、ngx-translate国际化、ProseMirror富文本编辑器、React 与 React DOM作为 Angular 内的 React 渲染容器使用等。一个可发布的 Angular 库Library遵循 ng-packagr 格式组织作为vendure/admin-ui发布到 npm供消费方应用以子包sub-package形式按需导入。二、项目结构Library 与 Application 双轨并存2.1 Library可复用库Admin UI 的核心代码被组织为符合 ng-packagr 格式 的 Angular 库这部分正是发布到 npm 的vendure/admin-ui。库由一组模块构成消费方应用可以按子包方式分别引入vendure/admin-ui/corevendure/admin-ui/catalogvendure/admin-ui/orders等等如customer、dashboard、login、marketing、order、settings、system、react这些子包源码位于 packages/admin-ui/src/lib从目录列表可以直观看到catalog/、core/、customer/、dashboard/、login/、marketing/、order/、react/、settings/、system/等与业务域一一对应的模块目录。关于库的打包方式packages/admin-ui/src/lib/ng-package.json 给出了关键配置dest: ../../package库构建产物输出到package/目录assets将static/favicon.ico、static/index.html、static/polyfills.ts、static/vendure-ui-config.json、static/assets/*.*、static/styles/**/*.scss、static/fonts/*.woff2、static/i18n-messages/*.json等静态资源一并打包进发布物entryFile: ./public_api.ts库的入口文件。需要注意的是packages/admin-ui/src/lib/public_api.ts 中的入口只是一个占位符并明确提示请从子包导入例如vendure/admin-ui/core。在 packages/admin-ui/angular.json 中Angular 工作区同时定义了vendure-admin应用与vendure-admin-lib库两个 project库的构建使用angular-devkit/build-angular:ng-packagrbuilder并支持production配置对应tsconfig.lib.prod.json。2.2 构建与发布执行构建命令bun run build构建完成后产物位于./package子目录即 packages/admin-ui/package 在构建后生成。该目录同时就是发布到 npm 的包根目录——这一点在 packages/admin-ui/package.json 的publishConfig.directory: package中得到了印证。从 packages/admin-ui/package.json 的scripts可以看到构建链路的完整组成build: node scripts/copy-package-json.js node scripts/set-version.js node scripts/build-public-api.js ng build vendure-admin-lib --configuration production node scripts/compile-styles.js即依次执行复制 package.json → 设置版本号 → 生成公共 API 文件 → 以生产模式用 ng-packagr 构建库 → 编译样式。其他常用脚本还包括devnode scripts/set-version.js ng serve启动 Angular 开发服务器watch增量构建test基于 Karma 的单元测试ChromeHeadlessCIlintESLint 自动修复。2.3 Application完整应用除了库之外还存在一个完整的应用位于 packages/admin-ui/src/app。这个应用有两个用途Admin UI 开发阶段使用作为本地开发调试的宿主应用作为默认的 Admin UI即不带任何 UI 扩展UI extensions的默认版本由 admin-ui-plugin 默认提供。从 packages/admin-ui/angular.json 看该应用的关键构建选项包括baseHref: /admin/与 AdminUiPlugin 默认路由/admin/对应、入口src/lib/static/index.html、polyfills、SCSS 样式体系含stylePreprocessorOptions.includePaths等。三、AdminUiPluginAdmin UI 如何被挂载到服务器作为背景补充详见 packages/admin-ui-plugin/src/plugin.tsAdmin UI 应用本身并不直接对外服务而是由AdminUiPlugin启动一个静态文件服务器并通过 Vendure 主服务器的/admin/路径进行代理。插件初始化示例import { AdminUiPlugin } from vendure/admin-ui-plugin; const config: VendureConfig { plugins: [ AdminUiPlugin.init({ port: 3002 }), ], };插件在启动时会做两件关键事情覆写vendure-ui-config.json把插件选项中或服务端推断出的API 地址、认证方式、可用语言等配置写入 Admin UI 应用目录下的配置文件覆写index.html的base href将 baseHref 调整为与插件route选项匹配的值默认/admin/。这两步在源码中分别由overwriteAdminUiConfig()与overwriteBaseHref()实现并且由于编译尤其 watch 模式可能尚未把文件复制到位插件使用了轮询机制pollForFile()最多重试 10 次、每次间隔 200ms等待文件就绪。重要提醒来自源码注释从 Vendure v3.5.0 起基于 Angular 的 Admin UI 已被新的 React Admin Dashboard 取代Angular Admin UI 将在2026 年 7 月之后不再维护仅在此前继续修复关键 bug 与安全问题。因此新项目应优先考虑 React Admin Dashboard本文内容适用于仍在维护期内的 Angular Admin UI 版本。四、本地化Localization机制4.1 技术选型与消息格式Admin UI 的界面字符串本地化由 ngx-translate 负责。翻译字符串使用 ICU MessageFormat 语法这意味着翻译词条可以表达复数、选择gender/plural等复杂语义。在 packages/admin-ui/package.json 的依赖中可以看到配套的ngx-translate-messageformat-compiler与messageformat/core它们负责在 ngx-translate 中解析 ICU 格式。4.2 自动抽取翻译词条翻译 key 通过运行以下命令自动抽取bun run extract-translations该命令对应 packages/admin-ui/scripts/extract-translations.jspackage.json 中脚本为extract-translations: node scripts/extract-translations.js。其工作流程为扫描./src目录下所有源码文件中的翻译 key将新 key 合并进 packages/admin-ui/src/lib/static/i18n-messages 目录下的各语言 JSON 文件底层实际调用ngx-translate-extract工具参数包括--clean清理失效词条、--sort排序、--format namespaced-json命名空间 JSON 格式即按模块分组的嵌套结构、-m _标记函数为_。每处理一种语言脚本都会打印一行覆盖情况报告格式如下Extracting translation tokens for src\lib\static\i18n-messages\de.json de: 592 of 650 tokens translated (91%)这些统计数据同时被写入 packages/admin-ui/i18n-coverage.json。该报告文件包含generatedOn生成时间、lastCommit生成时的 Git 提交哈希以及每种语言的tokenCount词条总数、translatedCount已翻译数与percentage百分比。以仓库当前快照为例ar、cs、de、en、es、fa、fr、he等语言的覆盖率均为 797/797100%。关于覆盖率统计口径extract-translations.js 中的getStatsForLocale()展示了计算逻辑遍历 JSON 中每个 section把所有词条值收集起来tokenCount记总数translatedCount仅统计值非空字符串val ! 的词条百分比即两者之比四舍五入。4.3 为 Admin UI 添加一门新语言按照 README 给出的官方流程添加新语言分三步第一步创建语言文件。在i18n-messages目录中新建一个内容为{}的空 JSON 文件命名为languageCode.json。其中languageCode必须是受支持的枚举值之一枚举定义在 packages/core/src/api/schema/common/language-code.graphql 的LanguageCode类型中。该枚举采用ISO 639-1 语言代码 可选地区/文字修饰符的格式例如de_AT取值范围基于 Unicode CLDR summary list覆盖世界主要语言及常见变体。从枚举源码可见示例af南非荷兰语、ar阿拉伯语、zh中文、zh_Hans简体中文、zh_Hant繁体中文等。第二步运行抽取命令。执行bun run extract-translations脚本会读取i18n-messages目录下的所有语言文件见 extract-translations.js 中fs.readdirSync(MESSAGES_DIR)的遍历逻辑为每种语言分别运行 ngx-translate-extract把源码中的翻译 key 合并进对应的 JSON随后输出覆盖率报告并刷新i18n-coverage.json。第三步在开发模式中启用该语言。将languageCode.json追加到 packages/admin-ui/src/lib/static/vendure-ui-config.json 的availableLanguages数组中。这样该语言就会在 Admin UI 开发模式下bun run dev出现在语言切换列表中。4.4 vendure-ui-config.json运行期 UI 配置packages/admin-ui/src/lib/static/vendure-ui-config.json 是 Admin UI 运行期读取的核心配置文件生产环境中由 AdminUiPlugin 在启动时按需覆写其关键字段包括字段默认值仓库当前快照说明apiHosthttp://localhostVendure GraphQL API 主机地址apiPort3000API 端口adminApiPathadmin-apiAdmin API 路径tokenMethodbearer认证令牌传递方式bearer 或 cookieauthTokenHeaderKeyvendure-auth-token认证令牌请求头名称channelTokenKeyvendure-token渠道Channel令牌键defaultLanguageen默认界面语言defaultLocaleUS默认地区如USavailableLanguages23 种语言见下可切换的界面语言列表availableLocales数百个地区代码可选择的地区列表brand品牌名称留空使用默认hideVendureBrandingfalse是否隐藏 Vendure 品牌标识hideVersionfalse是否隐藏版本号cancellationReasons两条默认取消原因订单取消原因选项availableLanguages数组当前包含he、ar、de、en、es、pl、zh_Hans、zh_Hant、pt_BR、pt_PT、cs、fr、ru、uk、it、fa、ne、hr、nb、sv、tr、ja、sw与i18n-messages目录中的 23 个语言文件一一对应。这些语言代码全部可以在 language-code.graphql 的LanguageCode枚举中找到定义如zh_Hans、zh_Hant、pt_BR、pt_PT均为带地区修饰符的合法枚举值这也印证了 README 中languageCode 必须来自 LanguageCode 枚举的要求。五、开发工作流小结将以上内容串起来Admin UI 的日常开发与发布流程可以概括为开发调试运行bun run dev通过 Angular dev server 预览vendure-admin应用配合vendure-ui-config.json中的apiHost/apiPort连接本地 Vendure 服务新增/修改界面文案直接在源码中使用翻译标记_函数然后运行bun run extract-translations自动同步所有语言文件并查看覆盖率报告新增语言按 4.3 节的三步流程操作发布库运行bun run build产物输出到package/目录该目录即 npm 包的发布根目录publishConfig.directory集成进服务器通过AdminUiPlugin挂载让最终用户通过/admin/访问管理后台。六、延伸阅读Admin UI 源码结构各业务域子包源码按 ng-packagr 库格式组织admin-ui-plugin 插件实现Admin UI 静态服务与代理、配置覆写的完整逻辑i18n 抽取脚本翻译词条抽取、覆盖率统计与报告生成的实现LanguageCode 枚举全部受支持语言代码的权威定义i18n 覆盖率报告各语言翻译进度的机器可读快照构建配置应用与库两个 project 的完整 Angular 构建配置。【免费下载链接】vendureOpen-source headless commerce platform built with TypeScript, NestJS, React, and GraphQL项目地址: https://gitcode.com/GitHub_Trending/ve/vendure创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考