Backstage v1.39.0-next.2 版本解析Gerrit 编辑入口、catalog-import 国际化与翻译 API 的 JSX 插值能力【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage本篇技术指南围绕 Backstage 官方发布文档 v1.39.0-next.2 changelog 展开系统梳理该预发布版本中约 60 个包的变化重点剖析三个具有实战价值的主题backstage/integration为 Gerrit 3.9 新增的 Edit URL 能力及其开关配置、backstage/plugin-catalog-import的国际化i18n支持及随之而来的破坏性变更、以及贯穿core-plugin-api/core-app-api/test-utils的翻译 API JSX 元素插值增强。读完本文你将掌握这些变更的配置方法、迁移要点与底层实现原理。版本概览一个聚焦翻译体系与代码托管集成的预发布版本v1.39.0-next.2是 Backstage 面向 v1.39.0 正式版的第二个预发布next版本。与所有next版本一样它面向早期验证者包含完整的变更记录但可能仍处于迭代之中。本次版本中大多数包仅有依赖更新Patch Changes真正的功能亮点集中在以下几处Minor新增功能backstage/integration1.17.0-next.2新增 Gerrit 3.9 Edit URL 功能提交f134ceabackstage/plugin-catalog-import0.13.0-next.2的generateStepper签名变更提交e2fd549Breaking。Patch修复与增强翻译 API 支持 JSX 元素插值提交73f6cc3、b573341、catalog-import插件新增 i18n 支持提交66a1140、GithubUrlReader改用options中的 token 拉取仓库详情提交0e7a640、AWS STS region 回退逻辑修复提交db4630e等。各包版本号、变更类别与依赖关系的完整清单可直接查阅 v1.39.0-next.2-changelog.md 原文。重点一Gerrit 3.9 Edit URL 功能本次版本最值得关注的功能性新增来自backstage/integration1.17.0-next.2的 Minor Changesf134cea: Implement Edit URL feature for Gerrit 3.9. Its possible to disable the edit url by adding thedisableEditUrl: trueconfig in the Gerrit integration.功能背景与 URL 形态Gerrit 3.9 之后服务端提供了基于 Web 的文件编辑入口Backstage 借此为 Gerrit 集成实现了resolveEditUrl。从实现看该 URL 由 buildGerritEditUrl 生成其结构为{baseUrl}/admin/repos/edit/repo/{project}/branch/refs/heads/{branch}/file/{filePath}例如在 GerritIntegration.test.ts 中验证的用例输入的 Gitiles 浏览地址https://gerrit-review.example.com/gitiles/backstage/backstage//refs/heads/master/catalog-info.yaml会被解析并转换为编辑入口https://gerrit-review.example.com/admin/repos/edit/repo/backstage/backstage/branch/refs/heads/master/file/catalog-info.yaml实现路径为resolveEditUrl先用parseGitilesUrlRef从 Gitiles URL 中解析出project、ref、path三个要素再调用buildGerritEditUrl拼装出编辑页面地址。整个转换逻辑集中在 GerritIntegration.resolveEditUrl。通过disableEditUrl开关控制行为对于 Gerrit 版本低于 3.9、或出于安全与体验考量不希望暴露编辑入口的实例可以在 Gerrit 集成配置中关闭该功能。配置项disableEditUrl是可选布尔值由 readGerritIntegrationConfig 通过config.getOptionalBoolean(disableEditUrl)读取类型定义与注释位于 config.ts 的 GerritIntegrationConfig。启用开关后resolveEditUrl会直接原样返回输入 URL不做任何转换resolveEditUrl(url: string): string { if (this.config.disableEditUrl) { return url; } // ... 解析并构建编辑 URL }对应的行为在 GerritIntegration.test.ts 中有完整覆盖当disableEditUrl: true时输入 URL 被原样返回当disableEditUrl: false时则返回转换后的编辑 URL。配置解析侧的校验与默认值undefined行为则由 config.test.ts 验证。配置示例在app-config.yaml或独立的后端配置的integrations.gerrit节点下完整的 Gerrit 集成配置形如integrations: gerrit: - host: gerrit-review.example.com baseUrl: https://gerrit-review.example.com gitilesBaseUrl: https://gerrit-review.example.com/gitiles # 针对 Gerrit 3.9 或不需要编辑入口的实例关闭 Edit URL 功能 disableEditUrl: true注意host与gitilesBaseUrl为必填项baseUrl缺省时会自动回退为https://{host}见 config.ts 的默认值逻辑。该配置的完整字段baseUrl、cloneUrl、username、password、commitSigningKey等与校验规则均定义在同文件中。重点二catalog-import 插件的 i18n 支持与 Breaking 变更backstage/plugin-catalog-import0.13.0-next.2同时包含一个 Minor破坏性变更与一个 Patch新增能力e2fd549BREAKINGgenerateStepper与defaultGenerateStepper现在要求必须传入 translation 参数以支持翻译。66a1140为catalog-import插件整体添加 i18n 支持。破坏性变更的签名变化此前自定义导入流程的开发者若通过ImportStepperProps.generateStepper注入自定义 stepper 生成函数签名只接收flow与defaults两个参数。升级后该函数必须接收第三个参数——翻译函数tgenerateStepper?: ( flow: ImportFlows, defaults: StepperProvider, t: TranslationFunctiontypeof catalogImportTranslationRef.T, ) StepperProvider;这一新签名定义在 ImportStepper.tsx 的 ImportStepperProps默认实现 defaultGenerateStepper 已同步升级。在 ImportStepper 组件内部翻译函数来自useTranslationRef(catalogImportTranslationRef)并通过useMemo传入generateStepper(state.activeFlow, defaultStepper, t)。翻译引用catalogImportTranslationRef定义于插件的 translation 模块并在 alpha.tsx 中对外导出。迁移指南自定义 stepper 如何适配如果你在应用中覆盖了generateStepper升级到0.13.0-next.2后需要将第三个参数t加入函数签名将原先硬编码的界面文案如importStepper.singleLocation.title替换为t(...)调用使用默认实现中相同的翻译 key 结构。例如 defaults.tsx 中single-location流程的prepare步骤标签即通过t(importStepper.singleLocation.title)与t(importStepper.singleLocation.description)渲染。如果你未覆盖generateStepper使用默认行为则无需改动破坏性变更不影响默认路径。重点三翻译 API 支持 JSX 元素插值本版本围绕国际化另一条主线是翻译插值能力的增强涉及三个包均由提交73f6cc3及b573341引入backstage/core-plugin-api1.10.7-next.0TranslationApi现在支持将 JSX 元素直接作为插值值传给翻译函数。若提供的任一插值值是 JSX 元素翻译函数将返回 JSX 元素而非字符串。backstage/core-app-api1.16.2-next.0I18nextTranslationApi同步支持 JSX 元素的插值。backstage/test-utils1.7.8-next.1MockTranslationApi增加对 JSX 元素插值的支持便于在测试环境中验证此类翻译。这一能力让翻译字符串中嵌入可点击链接、强调文本等富内容成为可能。例如模板中包含Link或strong占位符时应用侧可以这样调用const { t } useTranslationRef(myTranslationRef); // 插值值为 JSX 元素时返回 JSX 而非字符串 const message t(welcome.text, { user: strong{userName}/strong, docsLink: Link to/docsdocumentation/Link, });MockTranslationApi的同步升级意味着基于backstage/test-utils的组件测试可以直接覆盖该行为无需额外 mock。其他值得关注的 Patch 变更除上述三大主题外本版本还包含若干值得注意的修复与增强包变更要点backstage/backend-defaults0.10.0-next.2GithubUrlReader在拉取仓库详情时改用options中传入的 token0e7a640提升通过 url reader 访问私有/受限仓库时的鉴权准确性backstage/integration-aws-node0.1.16-next.0修复DefaultAwsCredentialsManager中aws.mainAccount.region不影响凭据提供者查找时账号 ID 查询所用 STS region、且未回退us-east-1的 bugdb4630ebackstage/plugin-catalog1.29.1-next.2修复在 dialog 上下文中通过core-plugin-api使用时routeRef缺失的问题bf85d37backstage/plugin-catalog-backend-module-ldap0.11.5-next.2改进 LDAP catalog provider 中缺失metadata.name时的错误报告e253d1dbackstage/plugin-notifications-backend-module-slack0.1.1-next.2修复 Slack 通知处理器处理空 description 的告警4f10768backstage/canon0.4.0-next.2TextField新增icon与onClearprops6189bfd并将内部实现切换为 Base UI 的Field组件backstage/plugin-techdocs1.12.6-next.2点击 hash 链接后修正键盘焦点7d445da为代码块复制到剪贴板按钮补充 hover/focus 样式与aria-label2ffd273改善无障碍体验backstage/repo-tools0.13.3-next.2支持向 OpenAPI server generator 传递额外属性b229476backstage/create-app0.6.2-next.2从.gitignore移除lerna-debug.log*模式因该包已自0.5.19起移除 Lerna8448948backstage/plugin-scaffolder-backend-module-notifications0.1.10-next.2通知发送 scaffolder action 改用原生 zod schemasb60253d升级建议与验证方式关注 Breaking 变更若你的应用覆盖了generateStepper升级backstage/plugin-catalog-import前务必按上文迁移指南调整签名其余包均为兼容性变更。验证 Gerrit 编辑入口升级backstage/integration后可在本地起一个 Gerrit 3.9 实例通过catalog-import或 url reader 流程触发resolveEditUrl并结合disableEditUrl: true/false两种配置分别验证仓库测试 GerritIntegration.test.ts 给出了两种模式的期望输出可直接作为断言基准。翻译 API 回归若插件代码依赖TranslationApi的字符串返回值确认插值参数中不混入 JSX 元素测试环境建议同步升级backstage/test-utils以利用MockTranslationApi的 JSX 插值支持。当前仓库中完整的包级变更清单可分别查阅各包 CHANGELOG例如 packages/integration/CHANGELOG.md 与 plugins/catalog-import/CHANGELOG.md它们与 v1.39.0-next.2-changelog.md 相互印证可作为升级与代码评审的对照依据。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考