Novu CLI 翻译管理实战指南用 translations pull/push 命令同步多语言资源【免费下载链接】novuThe open-source communication infrastructure for agents and products项目地址: https://gitcode.com/GitHub_Trending/no/novu导读本文聚焦 Novu 官方 CLI 提供的novu translations pull与novu translations push两个命令讲解如何将 Novu Cloud 工作区中的多语言翻译资源下载到本地、以及如何将本地维护的翻译文件批量上传回云端。读完本文你将掌握完整的参数用法、文件命名与 JSON 格式规范、环境变量配置方式并理解 CLI 底层的 API 调用链与错误处理机制可直接用于实际项目的翻译资产版本化管理。命令概览translations 子命令的定位在 Novu CLI 中translations是一个顶层子命令内部又挂载了pull与push两个子命令。其命令注册位于 packages/novu/src/index.tsconst translationsCommand program.command(translations).description(Manage Novu translations); translationsCommand .command(pull) .description(Pull all translation files from Novu Cloud) .option(-s, --secret-key secret-key, The Novu Secret Key, NOVU_SECRET_KEY || ) .option(-a, --api-url url, The Novu Cloud API URL, NOVU_API_URL || https://api.novu.co) .option(-d, --directory path, Directory to save translation files, ./translations) .action(async (options) { /* ... */ }); translationsCommand .command(push) .description(Push translation files to Novu Cloud) .option(-s, --secret-key secret-key, The Novu Secret Key, NOVU_SECRET_KEY || ) .option(-a, --api-url url, The Novu Cloud API URL, NOVU_API_URL || https://api.novu.co) .option(-d, --directory path, Directory containing translation files, ./translations) .action(async (options) { /* ... */ });三个选项与文档中的说明完全对应其默认值均由 CLI 入口处定义-s, --secret-key必填用于身份认证-a, --api-url默认https://api.novu.co可通过环境变量NOVU_API_URL覆盖详见下文-d, --directory默认./translations。从 packages/novu/src/commands/index.ts 可以看到translations模块与dev、wizard一起从命令层导出而 packages/novu/src/index.ts 中通过import { pullTranslations, pushTranslations } from ./commands/translations接入 CLI 主入口最终由 Commander 框架统一解析执行。命令一novu translations pull下载翻译文件pull命令用于将 Novu Cloud 中已配置的所有语言翻译文件下载到本地目录是了解云端翻译资产结构、以及将翻译纳入版本控制的第一步。基础用法# 拉取翻译到默认目录./translations npx novu pull -s YOUR_SECRET_KEY # 拉取到自定义目录 npx novu pull -s YOUR_SECRET_KEY -d ./my-translations # 使用 EU API 端点 npx novu pull -s YOUR_SECRET_KEY -a https://eu.api.novu.co注与 README 一致完整命令形式为npx novu translations pullnpx novu pull仅是便于口述的简写实际执行请使用下文完整形式。# 完整形式拉取到默认目录 npx novu translations pull -s YOUR_SECRET_KEY # 拉取到自定义目录 npx novu translations pull -s YOUR_SECRET_KEY -d ./my-translations # 使用 EU API 端点 npx novu translations pull -s YOUR_SECRET_KEY -a https://eu.api.novu.co参数说明参数说明默认值-s, --secret-key keyNovu Secret Key必填无-a, --api-url urlNovu API 地址https://api.novu.co-d, --directory path保存文件的目录./translations底层执行流程pull命令的实现位于 packages/novu/src/commands/translations/pull.ts其完整流程为校验 Secret Key若未通过-s或环境变量提供密钥直接抛出错误Secret key is required. Use -s flag or set NOVU_SECRET_KEY environment variable.校验连接调用client.validateConnection()实际请求GET {apiUrl}/v1/users/me见 client.ts用于提前发现 API Key 无效或网络不通等问题获取组织语言设置调用GET {apiUrl}/v1/organizations/settings从响应中读取defaultLocale与targetLocales见 types.ts合并去重后得到需要拉取的语言列表逐个语言下载对每个 locale 调用GET {apiUrl}/v2/translations/master-json?locale{locale}见 client.ts将返回的 JSON 内容以{locale}.json文件名写入目标目录输出汇总打印成功拉取的语言数量、各文件大小通过formatFileSize格式化见 utils.ts以及错误详情。其中值得注意的两个细节默认语言也会被拉取defaultLocale会被加入目标语言列表且会通过[...new Set(targetLocales)]去重避免默认语言与目标语言重复时产生重复下载见 pull.ts空翻译的处理若某个 locale 返回空对象Object.keys(response.data).length 0CLI 会提示No translations available并跳过写文件不会创建空文件见 pull.ts。常见异常场景的输出若组织尚未在 Dashboard 中开启翻译功能拉取会失败CLI 会明确给出引导 Unable to fetch organization locale settings. To use translations, you need to: 1. Go to your Novu Dashboard 2. Navigate to the Translations page 3. Enable translations and configure your target locales 4. Set your default locale同时抛出Translations not configured. Please enable translations in your dashboard first.见 pull.ts。命令二novu translations push上传翻译文件push命令用于将本地目录中的翻译文件上传到 Novu Cloud实现本地编辑、云端生效的迭代闭环。基础用法# 从默认目录./translations上传 npx novu translations push -s YOUR_SECRET_KEY # 从自定义目录上传 npx novu translations push -s YOUR_SECRET_KEY -d ./my-translations # 使用 EU API 端点 npx novu translations push -s YOUR_SECRET_KEY -a https://eu.api.novu.co参数说明参数说明默认值-s, --secret-key keyNovu Secret Key必填无-a, --api-url urlNovu API 地址https://api.novu.co-d, --directory path包含翻译文件的目录./translations底层执行流程push的实现位于 packages/novu/src/commands/translations/push.ts流程为校验 Secret Key 与连接与pull一致获取组织语言设置同样读取defaultLocale与targetLocales得到“已配置语言”白名单加载本地文件调用loadTranslationFiles扫描目录见 utils.ts——仅接受符合^([a-z]{2}(?:_[A-Z]{2})?)\.json$命名模式的文件非法的文件名与无法解析的 JSON 文件会被跳过并给出警告过滤未配置语言本地文件中不在组织设置白名单内的 locale 会被跳过并提示not in organization settings见 push.ts避免上传错误语言逐个上传对每个文件调用POST {apiUrl}/v2/translations/master-json/upload以multipart/form-data方式将文件作为file字段上传见 client.ts请求头携带Authorization: ApiKey {secretKey}输出汇总打印成功上传的文件数、每个文件导入的资源数successful数组长度以及错误详情。关于“资源数”的含义上传响应的数据结构定义在 types.tsexport interface UploadResponseData { success: boolean; message: string; successful?: string[]; failed?: string[]; }successful数组中的每一项对应一条成功导入的翻译资源如某个 workflow 步骤的subject、body等CLI 用其长度作为“imported resources”计数展示。当success为false时会回显服务端返回的message作为失败原因。文件格式与目录规范命名规范翻译文件必须以locale.json命名locale 采用语言_地区形式如en_US.json。CLI 通过正则^([a-z]{2}(?:_[A-Z]{2})?)\.json$校验文件名见 utils.ts这意味着语言代码必须为两位小写字母如en、fr地区代码可选若有则必须为两位大写字母并用下划线连接如_US、_FR不匹配该模式的文件会被直接跳过并在终端输出警告。一个标准的翻译目录结构translations/ ├── en_US.json ├── fr_FR.json ├── es_ES.json └── de_DE.jsonJSON 内容格式翻译文件内容为嵌套 JSON 对象顶层键通常是工作流名称下一层是步骤再下一层是具体的文案字段。以en_US.json为例{ workflows: { welcome: { subject: Welcome to our platform!, body: Thank you for joining us. } } }pull写入文件时使用JSON.stringify(content, null, 2)进行美化输出见 utils.ts因此下载下来的文件始终是 2 空格缩进的易读格式方便直接纳入 git 做 diff 审查。push一侧对文件内容的要求是“可被JSON.parse解析”解析失败的 JSON 文件会被跳过。环境变量免去重复传参为避免在每条命令中重复传入-s与-aCLI 支持通过环境变量注入export NOVU_SECRET_KEYyour_secret_key_here export NOVU_API_URLhttps://api.novu.co # 或 EU 区域使用 https://eu.api.novu.co # 之后可以省略 -s 与 -a 直接执行 npx novu translations pull npx novu translations push其实现机制为CLI 启动时通过dotenv依次加载.env.local与默认.env见 packages/novu/src/constants/constants.ts并将NOVU_API_URL、NOVU_SECRET_KEY注入进程环境。随后在命令注册处packages/novu/src/index.ts-s与-a的默认值会读取这两个环境变量因此设置了环境变量后即可省略对应 flag。可以推断的优先级规则为命令行 flag 显式传入 环境变量 硬编码默认值https://api.novu.co。这符合 Commanderoption(..., defaultValue)的常规行为——-s的默认值是NOVU_SECRET_KEY || 若两者皆无则为空字符串此时会在pull/push的实现中触发“Secret key is required”错误。支持的语言LocaleCLI 侧对 locale 并无硬编码白名单理论上任何符合xx或xx_XX命名的语言都可被处理。组织实际可用的语言由 Dashboard「Translations」页面配置的targetLocales决定文档中列出的常用 locale 包括en_US、en_GB英语es_ES西班牙语fr_FR法语de_DE德语it_IT意大利语pt_BR葡萄牙语ja_JP日语ko_KR韩语zh_CN、zh_TW中文ru_RU俄语ar_SA阿拉伯语hi_IN印地语以及更多标准 locale 代码。错误处理机制CLI 对常见错误提供了分层、可读的提示主要分布在 client.ts 与两个命令实现中错误场景处理方式Secret Key 缺失命令启动时抛错Secret key is required. Use -s flag or set NOVU_SECRET_KEY environment variable.API Key 无效401所有 API 调用统一转为Invalid API key. Please check your secret key.网络连接问题validateConnection失败时输出Connection failed并终止拉取时某语言无翻译404转为No translations found for locale: {locale}在汇总中以No translations available提示而非报错上传时请求格式错误400回显服务端message或error字段上传时接口不存在404提示Upload endpoint not found. Please check your API URL.服务端异常5xx输出状态码与错误详情本地 JSON 解析失败跳过该文件并警告Skipping invalid JSON file: {file} - {reason}目录不存在push抛错Directory not found: {directory}此外pull在全部语言拉取失败successCount 0时会给出排查建议包括尚未上传任何翻译、API Key 无翻译权限、或 API URL 指向错误建议 EU 区域使用-a https://eu.api.novu.co。文件写入权限问题则由 Node.jsfs层抛出可通过检查目标目录权限解决。实战建议与最佳实践推送前先备份push是覆盖式上传建议先pull一份最新副本或确保云端已有历史版本再执行推送推送前校验 JSON所有待推送文件必须能被JSON.parse解析文件名必须符合locale.json规范否则会被静默跳过善用版本控制将translations/目录纳入 git 管理利用pull生成的文件差异2 空格缩进、稳定排序进行 Code Review翻译变更可追溯先用 pull 验证目录结构在执行push前先pull一次可确认预期的文件结构与命名避免上传后才发现 locale 不在组织白名单中而被跳过CI 中注入密钥在 CI 流水线中优先使用NOVU_SECRET_KEY环境变量而非在命令中明文书写密钥配合-a指定正确的区域端点US 默认https://api.novu.coEU 使用https://eu.api.novu.co。参考实现路径命令注册与参数默认值packages/novu/src/index.tspull 实现packages/novu/src/commands/translations/pull.tspush 实现packages/novu/src/commands/translations/push.tsAPI 客户端含端点与鉴权头packages/novu/src/commands/translations/client.ts类型定义packages/novu/src/commands/translations/types.ts文件读写与命名工具packages/novu/src/commands/translations/utils.ts环境变量加载packages/novu/src/constants/constants.ts【免费下载链接】novuThe open-source communication infrastructure for agents and products项目地址: https://gitcode.com/GitHub_Trending/no/novu创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考