globalize-now-cli-use

Globalize CLI 用法

本技能将指导你使用 CLI（globalise-now-cli）在 Globalize 平台上管理翻译资源。

以编程方式运行命令时，始终使用 --json。解析 JSON 输出，提取供后续命令使用的 ID。许多操作都需要使用先前步骤返回的 UUID。

所有示例均使用 npx @globalize-now/cli-client。如果全局安装了 CLI，请替换为 globalise-now-cli。

---

步骤 1：先决条件检查

验证是否已配置身份验证：

npx @globalize-now/cli-client auth status --json

如果失败或提示没有凭据，请先运行 globalize-now-account-setup 技能。

---

步骤 2：常见工作流——创建项目并连接代码仓库

这是最常见的端到端工作流。请按顺序完成以下子步骤：

2a. 获取并匹配可用语言

创建项目时必须使用语言 API 返回的语言 ID。创建项目之前，请先获取语言目录，并将用户所需的语言与之匹配。

1. 获取语言目录：

npx @globalize-now/cli-client languages list --json

这会返回一个语言对象数组，每个对象都包含 id（UUID）、name 和 locale（BCP 47 代码）。

2. 将所需语言与目录进行匹配。 将用户的源语言和目标语言区域代码（例如 en、fr、de、ja）与返回列表中的 locale 字段进行比较。提取每个匹配项对应的 id。

3. 报告不受支持的语言。 如果用户所需的语言未出现在目录中，请告知用户哪些语言不受支持，无法添加到项目中。不要默默跳过这些语言——用户必须确认存在此缺漏后才能继续。仅继续使用目录中有匹配项的语言。

2b. 创建项目

使用步骤 2a 中匹配到的语言 ID（UUID），而非单独的语言区域代码：

npx @globalize-now/cli-client projects create \
  --name "My App" \
  --source-language <SOURCE_LANGUAGE_ID> \
  --target-languages <TARGET_LANGUAGE_ID_1> <TARGET_LANGUAGE_ID_2> \
  --json

--target-languages 接受以空格或逗号分隔的值。

解析返回的 JSON，提取项目 ID。

2c. 连接代码仓库

Globalize 使用 GitHub App 或 GitLab OAuth 连接来访问代码仓库内容。请按顺序完成以下子步骤。

1. 获取 git 远程 URL：

git remote get-url origin

如果命令失败（未找到名为 origin 的远程），停止。告知用户：“未找到 git 远程 origin。请添加远程（git remote add origin <URL>）后重试，或手动提供 git URL。”如果用户手动提供 URL，请使用该 URL 并继续。

2. 解析 URL——提取 owner 和 repo/project：

• GitHub HTTPS：https://github.com/<OWNER>/<REPO>.git
• GitHub SSH：[email protected]:<OWNER>/<REPO>.git
• GitLab HTTPS：https://gitlab.com/<OWNER>/<PROJECT>.git
• GitLab SSH：[email protected]:<OWNER>/<PROJECT>.git

将 URL 保存为 <GIT_URL>。重要： CLI 的 --git-url 仅接受 HTTPS URL。如果远程 URL 是 SSH 格式，请将其转换为 HTTPS 格式。

• 如果 URL 包含 github.com：请使用 GitHub 流程（从子步骤 3 开始）。
• 如果 URL 包含 gitlab.com：请使用 GitLab 流程（见下文）。
• 否则：停止。告知用户：“Globalize 支持 GitHub 和 GitLab 代码仓库。检测到的远程 URL（<URL>）似乎不属于这两者。”请勿继续。

3. 同意确认——向用户确认代码仓库详情。继续之前必须完成此步骤。

展示检测结果并请用户确认：

检测到以下代码仓库：

• Git URL： <GIT_URL>
• Owner： <OWNER>
• Repo： <REPO>

我将使用 GitHub App（或 GitLab OAuth）将此代码仓库连接到你的 Globalize 项目。这可能会打开浏览器窗口，供你批准安装。这些信息正确吗？

等待用户回复后再继续。

• 用户确认 → 继续执行子步骤 4（GitHub）或 GitLab 流程。
• 用户更正 URL → 从子步骤 2 开始重新解析更正后的 URL。

---

GitHub 工作流

4. 设置 GitHub App 并连接仓库：

4a. 检查是否已安装 GitHub App：

npx @globalize-now/cli-client github installations --json

此命令会返回一个安装项数组。每个安装项都包含 id（一个 UUID，即 Globalize 内部的安装记录）、installationId（GitHub 安装项的数字 ID，例如 122432012）、accountLogin（GitHub 组织或用户名）和 accountType。

4b. 将安装项与仓库所有者匹配：

查找 accountLogin 与 <OWNER> 匹配的安装项（不区分大小写）。记录两个 ID：将数字 installationId 记为 <GITHUB_INSTALLATION_ID>（供 github repos/branches/detect --installation-id 使用），将 UUID id 记为 <INSTALLATION_UUID>（供 repositories create --github-installation-id 使用）。

• 找到匹配项 → 记录两个 ID，跳到子步骤 4d。
• 未找到匹配项 → 继续执行子步骤 4c。

4c. 安装 GitHub App（需要用户交互）：

npx @globalize-now/cli-client github install --no-wait --json

此命令会立即返回 { "installUrl": "...", "nonce": "..." }。将 installUrl 提供给用户，并请他们在浏览器中打开链接，选择正确的 GitHub 账户或组织，然后批准安装。

用户确认已完成浏览器操作后，检查状态：

npx @globalize-now/cli-client github install-status --nonce <NONCE> --json

完成后，此命令会返回 { "status": "completed", "installationId": "...", "accountLogin": "..." }；如果用户尚未完成，则返回 { "status": "pending" }；如果 nonce 已过期，则返回 { "status": "expired" }。检查 status === "completed"。如果尚未完成，请用户确认是否已完成操作，然后重试。

完成后，再次运行 github installations --json，查找目标所有者对应的 <GITHUB_INSTALLATION_ID>（数字 installationId）和 <INSTALLATION_UUID>（UUID id）。

4d. 验证仓库访问权限：

npx @globalize-now/cli-client github repos --installation-id <GITHUB_INSTALLATION_ID> --json

确认返回列表中包含 <OWNER>/<REPO>。如果没有，GitHub App 可能无权访问此特定仓库 — 告知用户需要在 GitHub 上调整安装项的仓库访问设置。

4e. 连接仓库：

npx @globalize-now/cli-client repositories create \
  --project-id <PROJECT_ID> \
  --git-url <GIT_URL> \
  --provider github \
  --github-installation-id <INSTALLATION_UUID> \
  --json

可选标志：--branches <branches...>、--patterns '<JSON array>'、--import-mode <ignore|reviewed|translated>、--import-scope <new_keys_only|all_keys>。

解析返回的 JSON，提取仓库 ID。

---

GitLab 工作流

对于 GitLab 仓库：

4a. 检查是否已有 GitLab 连接：

npx @globalize-now/cli-client gitlab connections --json

此命令会返回一个连接项数组。每个连接项都包含 id（UUID）、username、gitlabUserId、status 和 createdAt。

4b. 将连接与仓库所有者匹配：

查找 username 与 GitLab 所有者匹配的连接（不区分大小写）。如果找到，将其 id 记为 <CONNECTION_ID>。

• 找到匹配项 → 将其 id 用作 <CONNECTION_ID>，跳到子步骤 4d。
• 未找到匹配项 → 继续执行子步骤 4c。

4c. 安装 GitLab OAuth 连接（需要用户交互）：

npx @globalize-now/cli-client gitlab install --no-wait --json

此命令会立即返回 { "installUrl": "...", "nonce": "..." }。将 installUrl 提供给用户，并请他们在浏览器中打开链接，以授权 GitLab 连接。

用户确认已完成浏览器操作后，检查状态：

npx @globalize-now/cli-client gitlab install-status --nonce <NONCE> --json

完成后，此命令会返回 { "status": "completed", "connectionId": "...", "username": "..." }；如果用户尚未完成，则返回 { "status": "pending" }；如果 nonce 已过期，则返回 { "status": "expired" }。检查 status === "completed"。如果尚未完成，请用户确认是否已完成操作，然后重试。

完成后，将 connectionId 用作 <CONNECTION_ID>。

4d. 列出 GitLab 项目并验证访问权限：

npx @globalize-now/cli-client gitlab projects --connection-id <CONNECTION_ID> --json

将 pathWithNamespace 与 <OWNER>/<PROJECT> 进行匹配。如果未找到，GitLab 连接可能无权访问此项目 — 请告知用户。

4e. 连接仓库：

npx @globalize-now/cli-client repositories create \
  --project-id <PROJECT_ID> \
  --git-url <GIT_URL> \
  --provider gitlab \
  --gitlab-connection-id <CONNECTION_ID> \
  --json

可选标志：--branches <branches...>、--patterns '<JSON array>'、--import-mode <ignore|reviewed|translated>、--import-scope <new_keys_only|all_keys>。

解析返回的 JSON，提取仓库 ID。

---

2d. 检测仓库配置

对于 GitHub 仓库，可以通过 GitHub App 检测 i18n 结构：

npx @globalize-now/cli-client github detect \
  --installation-id <GITHUB_INSTALLATION_ID> \
  --owner <OWNER> \
  --repo <REPO> \
  --json

对于 GitLab 仓库，可以通过 GitLab 连接检测 i18n 结构：

npx @globalize-now/cli-client gitlab detect \
  --connection-id <CONNECTION_ID> \
  --project-id <GITLAB_PROJECT_ID> \
  --json

或者（也可以同时）从已连接的仓库自动发现：

npx @globalize-now/cli-client repositories detect \
  --id <REPO_ID> \
  --json

注意： 所有检测命令都会针对远程代码运行，而非本地工作副本。如果用户有影响语言区域文件的未提交或未推送更改，检测结果不会反映这些更改。若有此情况，请告知用户。

---

第 2.5 步：项目配置

项目有一个用于 QA、提供方、VCS 和通知设置的类型化 config 对象。使用 projects update 和 --config 设置或更改配置。

读取当前配置

npx @globalize-now/cli-client projects get --id <PROJECT_ID> --json

返回的 JSON 包含一个 config 对象，其中包含当前设置。

更新配置

通过 --config 传入 JSON 对象。该对象会进行合并——只需包含要更改的键：

npx @globalize-now/cli-client projects update \
  --id <PROJECT_ID> \
  --config '{"qa": {"enabledChecks": ["placeholder", "terminology"]}}' \
  --json

也可以在同一次调用中更新 --name、--source-language 和 --target-languages。

配置部分

部分	字段	描述
qa	enabledChecks（"placeholder"、"length"、"terminology"、"formatting"）、lengthRatioBounds（按语言区域键控的对象，每项为 {min, max}）、aiReviewScope（"enabled"、"disabled"）	质量保证检查和阈值
defaultProvider	字符串	默认翻译提供方
providerOverrides	按语言区域键控的对象 → 提供方字符串	按语言指定的提供方覆盖设置
deeplFormality	按语言区域键控的对象 → 正式程度字符串	按语言设置 DeepL 正式程度
github	prTranslations（布尔值）、ignoreDraftPrs（布尔值）	GitHub 集成行为
gitlab	mrTranslations（布尔值）、ignoreDraftMrs（布尔值）	GitLab 集成行为
notifications	webhookUrl（字符串）、webhookSecret（字符串）、emailRecipients（字符串数组）、enabledEvents（"job_failed"、"qa_issues"、"delivery_failed"、"job_completed"）	Webhook 和电子邮件通知设置

示例

启用 QA 检查：

npx @globalize-now/cli-client projects update \
  --id <PROJECT_ID> \
  --config '{"qa": {"enabledChecks": ["placeholder", "length", "terminology", "formatting"], "aiReviewScope": "enabled"}}' \
  --json

配置 GitHub PR 翻译：

npx @globalize-now/cli-client projects update \
  --id <PROJECT_ID> \
  --config '{"github": {"prTranslations": true, "ignoreDraftPrs": true}}' \
  --json

设置 Webhook 通知：

npx @globalize-now/cli-client projects update \
  --id <PROJECT_ID> \
  --config '{"notifications": {"webhookUrl": "https://example.com/webhook", "enabledEvents": ["job_failed", "job_completed"]}}' \
  --json

---

第 3 步：管理项目语言

创建项目后，可根据需要添加或移除目标语言。

列出当前项目语言：

npx @globalize-now/cli-client project-languages list \
  --project-id <PROJECT_ID> \
  --json

此操作会返回一个项目语言数组，每种语言都有自己的项目语言 ID（与全局语言 ID 不同）。进行术语表和风格指南操作时需要这些 ID。

添加语言：

npx @globalize-now/cli-client project-languages add \
  --project-id <PROJECT_ID> \
  --name "Spanish" \
  --locale es \
  --json

必填项：--name 和 --locale（BCP 47 代码）。可选项：--language-id，用于关联到特定的全局语言。

移除语言：

npx @globalize-now/cli-client project-languages remove \
  --project-id <PROJECT_ID> \
  --language-id <PROJECT_LANGUAGE_ID> \
  --json

---

第 3.5 步：模式管理

语言环境路径模式定义了翻译文件在仓库中的存放位置。每种模式都包含路径模板和文件格式。模式与仓库的创建／更新分开管理。

列出模式：

npx @globalize-now/cli-client patterns list --repository-id <REPO_ID> --json

创建模式：

npx @globalize-now/cli-client patterns create \
  --repository-id <REPO_ID> \
  --pattern "locales/{locale}/*.json" \
  --file-format json-nested \
  --json

支持的文件格式：json-flat、json-nested、po、xliff-1、xliff-2、yaml-rails、arb、xcstrings、android-strings、chrome-messages、wxt-i18n。

单文件格式（不含 {locale} 段）。 大多数格式每种语言环境使用一个文件，因此模式中包含 {locale} 占位符（locales/{locale}/*.json）。xcstrings 格式（Apple 字符串目录）则有所不同：一个多语言文件包含所有语言环境，因此模式就是目录路径本身，不含 {locale} 段，例如：

npx @globalize-now/cli-client patterns create \
  --repository-id <REPO_ID> \
  --pattern "Localizable.xcstrings" \
  --file-format xcstrings \
  --json

如果项目有多个目录表／目录，请改用 "**/*.xcstrings"。

路径语言环境覆盖（目录拼写与语言代码不同时）。 {locale} 是字面替换标记，不会进行转换。浏览器扩展将目录保存在 _locales/pt_BR/messages.json（使用下划线），而平台语言代码是 pt-BR，因此必须按语言记录这种差异：

npx @globalize-now/cli-client patterns path-locale \
  --repository-id <REPO_ID> \
  --pattern-id <PATTERN_ID> \
  --language-id <PROJECT_LANGUAGE_ID> \
  --path-locale pt_BR \
  --json

--language-id 是来自 project-languages list 的项目语言 UUID，而不是全局语言 ID。传入 --clear 而非 --path-locale，即可移除覆盖并回退到该语言自身的代码。拼写已匹配的语言（de、fr、ja）无需添加条目。创建仓库时，也可以通过 repositories create --path-locales '[{"pattern": …, "locale": "pt-BR", "pathLocale": "pt_BR"}]' 一次性传入相同信息。

更新模式：

npx @globalize-now/cli-client patterns update \
  --repository-id <REPO_ID> \
  --pattern-id <PATTERN_ID> \
  --pattern "locales/{locale}/{namespace}.json" \
  --json

删除模式：

npx @globalize-now/cli-client patterns delete \
  --repository-id <REPO_ID> \
  --pattern-id <PATTERN_ID> \
  --json

重新排序模式：

npx @globalize-now/cli-client patterns reorder \
  --repository-id <REPO_ID> \
  --pattern-id <PATTERN_ID> \
  --position 0 \
  --json

---

第 4 步：术语表管理

术语表可确保特定术语在不同语言中翻译一致。

列出术语表条目：

npx @globalize-now/cli-client glossary list \
  --project-id <PROJECT_ID> \
  --json

创建术语表条目：

npx @globalize-now/cli-client glossary create \
  --project-id <PROJECT_ID> \
  --source-term "Dashboard" \
  --target-term "Tableau de bord" \
  --source-language-id <SOURCE_PROJECT_LANGUAGE_ID> \
  --target-language-id <TARGET_PROJECT_LANGUAGE_ID> \
  --json

--source-language-id 和 --target-language-id 是来自 project-languages list（第 3 步）的项目语言 UUID，而非全局语言 ID。

对于所有语言中必须保持原样的术语（品牌名称、产品名称、代码标识符），请传入 --do-not-translate。仍然必须提供 --target-term，请使用源语言拼写。

删除术语表条目：

npx @globalize-now/cli-client glossary delete \
  --project-id <PROJECT_ID> \
  --entry-id <ENTRY_ID> \
  --json

在一个事务中批量导入整个术语表（最多 10 000 个条目，每个条目都有自己的语言对）。相同键的现有条目会更新，而不会重复创建：

npx @globalize-now/cli-client glossary bulk \
  --project-id <PROJECT_ID> \
  --entries '[{"sourceTerm":"Dashboard","targetTerm":"Tableau de bord","sourceProjectLanguageId":"<SRC_PL_ID>","targetProjectLanguageId":"<TGT_PL_ID>"},{"sourceTerm":"Globalize","targetTerm":"Globalize","sourceProjectLanguageId":"<SRC_PL_ID>","targetProjectLanguageId":"<TGT_PL_ID>","doNotTranslate":true}]' \
  --json

写入前可预览相同的导入操作——它会报告将创建和更新的条目数：

npx @globalize-now/cli-client glossary preview \
  --project-id <PROJECT_ID> \
  --keys '[{"sourceTerm":"Dashboard","sourceProjectLanguageId":"<SRC_PL_ID>","targetProjectLanguageId":"<TGT_PL_ID>"}]' \
  --json

---

第 5 步：风格指南管理

风格指南为每种语言提供翻译说明（例如，“使用正式语体”“优先采用英式英语拼写”）。

列出风格指南：

npx @globalize-now/cli-client style-guides list \
  --project-id <PROJECT_ID> \
  --json

创建或更新风格指南：

npx @globalize-now/cli-client style-guides upsert \
  --project-id <PROJECT_ID> \
  --language-id <PROJECT_LANGUAGE_ID> \
  --instructions "Use formal register. Prefer British English spelling." \
  --json

--language-id 是来自 project-languages list（第 3 步）的项目语言 UUID。

删除风格指南：

npx @globalize-now/cli-client style-guides delete \
  --project-id <PROJECT_ID> \
  --language-id <PROJECT_LANGUAGE_ID> \
  --json

---

第 6 步：组织和团队管理

Agent 较少需要使用这些命令，但根据需要也可以使用。

组织

npx @globalize-now/cli-client orgs list --json
npx @globalize-now/cli-client orgs delete --id <ORG_ID> --json

**注意：**没有 orgs create 命令。创建组织需要交互式（Clerk）会话，并且只能在 Web 应用中完成，无法通过 API 密钥创建。CLI 可以列出和删除组织，并管理组织中的所有内容。

成员

npx @globalize-now/cli-client members list --org-id <ORG_ID> --json
npx @globalize-now/cli-client members invite --org-id <ORG_ID> --email <EMAIL> --json
npx @globalize-now/cli-client members remove --org-id <ORG_ID> --membership-id <ID> --json

成员通过电子邮件地址（--email）受邀。invite 命令可选的 --role 标志：admin 或 member（默认值：member）。

API 密钥

npx @globalize-now/cli-client api-keys list --org-id <ORG_ID> --json
npx @globalize-now/cli-client api-keys create --org-id <ORG_ID> --name "CI Key" --json
npx @globalize-now/cli-client api-keys revoke --org-id <ORG_ID> --key-id <KEY_ID> --json

GitLab

npx @globalize-now/cli-client gitlab install                    # OAuth flow (opens browser)
npx @globalize-now/cli-client gitlab install --no-wait --json   # Returns URL and nonce
npx @globalize-now/cli-client gitlab install-status --nonce <NONCE> --json
npx @globalize-now/cli-client gitlab connections --json
npx @globalize-now/cli-client gitlab connection-delete --id <ID> --json
npx @globalize-now/cli-client gitlab projects --connection-id <ID> --json
npx @globalize-now/cli-client gitlab branches --connection-id <ID> --project-id <PROJECT_ID> --json
npx @globalize-now/cli-client gitlab detect --connection-id <ID> --project-id <PROJECT_ID> --json

---

命令参考

Command	Required flags	Optional flags
auth login	(interactive)	--no-wait
auth complete	--device-code, --code-verifier	--interval, --expires-in
auth status
auth logout
orgs list
orgs delete	--id
projects list
projects create	--name, --source-language (ID), --target-languages (IDs)	--config (JSON), --translation-memory-id
projects update	--id	--name, --source-language, --target-languages, --config (JSON), --cdn-public (true/false), --auto-discover-locales (true/false), --context
projects get	--id
projects delete	--id
projects refs	--id
projects scorecards		--limit
projects budget	--id
projects rotate-webhook-secret	--id
languages list
languages get	--id
project-languages list	--project-id
project-languages add	--project-id, --name, --locale	--language-id
project-languages remove	--project-id, --language-id
repositories list	--project-id
repositories create	--project-id, --git-url, --provider	--branches, --github-installation-id, --gitlab-connection-id, --patterns, --import-mode, --import-scope
repositories update	--id	--git-url, --branches, --github-installation-id, --gitlab-connection-id, --provider, --detected-framework, --import-mode, --import-scope
repositories delete	--id
repositories detect	--id
repositories branches	--id
repositories discover	--id
repositories translate	--id	--branch, --delivery-mode (push|pr)
patterns list	--repository-id
patterns create	--repository-id, --pattern, --file-format	--position
patterns update	--repository-id, --pattern-id	--pattern, --file-format
patterns delete	--repository-id, --pattern-id
patterns reorder	--repository-id, --pattern-id, --position
patterns bulk	--repository-id, --patterns (JSON)
patterns path-locale	--repository-id, --pattern-id, --language-id	--path-locale, --clear
github install		--no-wait
github install-status	--nonce
github installations
github repos	--installation-id
github branches	--installation-id, --owner, --repo
github detect	--installation-id, --owner, --repo
gitlab install		--no-wait
gitlab install-status	--nonce
gitlab connections
gitlab connection-delete	--id
gitlab projects	--connection-id
gitlab branches	--connection-id, --project-id
gitlab detect	--connection-id, --project-id
glossary list	--project-id
glossary create	--project-id, --source-term, --target-term, --source-language-id, --target-language-id	--do-not-translate
glossary delete	--project-id, --entry-id
glossary bulk	--project-id, --entries (JSON)
glossary preview	--project-id, --keys (JSON)
style-guides list	--project-id
style-guides upsert	--project-id, --language-id, --instructions
style-guides delete	--project-id, --language-id
style-guides generate	--project-id, --language-id
style-guides apply	--project-id, --language-id, --generation-id, --instructions	--context, --invalidate-tm
style-guides quota	--project-id
api-keys list	--org-id
api-keys create	--org-id, --name
api-keys revoke	--org-id, --key-id
members list	--org-id
members invite	--org-id, --email	--role
members remove	--org-id, --membership-id
namespaces list	--project-id
namespaces update	--project-id, --namespace-id, --name
namespaces delete	--project-id, --namespace-id
translation-memories list
translation-memories create	--name
translation-memories get	--id
translation-memories rename	--id, --name
translation-memories delete	--id
translation-memories entries	--id	--query, --source-locale, --target-locale, --limit, --cursor
translation-memories delete-entry	--id, --entry-id
translation-memories clear	--id	--target-locale
translation-memories count	--id	--target-locale
translation-memories fresh-count	--id, --target-locale
translation-memory list (deprecated)	--project-id	--query, --source-language-id, --target-language-id, --limit, --cursor
translation-memory delete (deprecated)	--project-id, --entry-id
translation-memory count (deprecated)	--project-id	--target-language-id
translation-memory fresh-count (deprecated)	--project-id, --target-language-id
jobs list		--project-id, --status, --limit, --offset
jobs get	--id
jobs start	--id
jobs retry	--id
jobs stats	--id
jobs qa-report	--id
jobs qa-dismiss	--id, --unit-id, --check-type	--reason, --note
jobs qa-undismiss	--id, --unit-id, --check-type
jobs export	--id	--target-lang
jobs export-manifest	--id
jobs units	--job-id, --target-project-language-id	--filter, --search, --limit, --cursor
jobs unit-get	--job-id, --unit-id
jobs files	--id	--limit, --cursor
jobs redeliver	--id
billing balance
billing ledger		--type, --grouped, --limit, --cursor

---

其他命令：任务、命名空间、翻译记忆与账单

这些命令组用于管理初始设置之外的翻译工作和账户状态。入门时较少用到，但可随时按需使用。

任务

翻译任务会运行项目的工作流。查看、启动、重试和导出任务：

npx @globalize-now/cli-client jobs list --project-id <PROJECT_ID> --json
npx @globalize-now/cli-client jobs get --id <JOB_ID> --json
npx @globalize-now/cli-client jobs start --id <JOB_ID> --json
npx @globalize-now/cli-client jobs stats --id <JOB_ID> --json
npx @globalize-now/cli-client jobs qa-report --id <JOB_ID> --json

可以忽略或恢复任务中的 QA 发现。--check-type 用于标识 QA 检查类型（例如 placeholder、length、terminology、formatting），--unit-id 用于标识受影响的翻译单元：

npx @globalize-now/cli-client jobs qa-dismiss --id <JOB_ID> --unit-id <UNIT_ID> --check-type <CHECK> --json
npx @globalize-now/cli-client jobs qa-undismiss --id <JOB_ID> --unit-id <UNIT_ID> --check-type <CHECK> --json

命名空间

命名空间用于对项目中的键进行分组（例如按功能或页面分组）：

npx @globalize-now/cli-client namespaces list --project-id <PROJECT_ID> --json
npx @globalize-now/cli-client namespaces update --project-id <PROJECT_ID> --namespace-id <NS_ID> --name "common" --json
npx @globalize-now/cli-client namespaces delete --project-id <PROJECT_ID> --namespace-id <NS_ID> --json

没有 namespaces create 命令——导入键时会自动创建命名空间。

翻译记忆

翻译记忆（TM）会存储以供重复使用的以往译文。翻译记忆属于组织级资源，而非项目级资源——多个项目可以关联到同一翻译记忆，共享其中的条目。通过 projects get 获取项目的翻译记忆（translationMemory.id），或列出组织中的所有翻译记忆：

npx @globalize-now/cli-client translation-memories list --json
npx @globalize-now/cli-client translation-memories get --id <TM_ID> --json   # attached projects + locales

条目通过翻译记忆 ID 和区域设置（en、fr-CA）寻址，而不是通过项目语言 UUID：

npx @globalize-now/cli-client translation-memories entries --id <TM_ID> --target-locale fr --json
npx @globalize-now/cli-client translation-memories count --id <TM_ID> --json
npx @globalize-now/cli-client translation-memories fresh-count --id <TM_ID> --target-locale fr --json
npx @globalize-now/cli-client translation-memories delete-entry --id <TM_ID> --entry-id <ENTRY_ID> --json

管理翻译记忆本身：

npx @globalize-now/cli-client translation-memories create --name "Marketing site" --json
npx @globalize-now/cli-client translation-memories rename --id <TM_ID> --name "Marketing" --json
npx @globalize-now/cli-client translation-memories clear --id <TM_ID> --target-locale fr --json   # omit the locale to clear everything
npx @globalize-now/cli-client translation-memories delete --id <TM_ID> --json

创建项目时，可使用 projects create --translation-memory-id <TM_ID> 将其关联到现有翻译记忆；此关联不可撤销。

破坏性操作会影响所有关联项目。 clear、delete-entry 和 delete 都会操作共享翻译记忆，因此其他项目贡献的条目也会消失。请检查 attachedProjectCount（来自 translation-memories list/get），并在清空或删除前与用户确认。只有未关联任何项目的翻译记忆才能使用 translation-memories delete 删除。

较早的项目级命令（translation-memory list|count|fresh-count|delete --project-id）仍然可用——它们会代你解析项目的翻译记忆——但这些命令已弃用，会打印警告，并返回包含 translationMemoryId 而非 projectId 的条目。请优先使用上述 translation-memories 命令。

账单

读取组织的额度余额和账本：

npx @globalize-now/cli-client billing balance --json
npx @globalize-now/cli-client billing ledger --json

billing balance 会根据你的 API 密钥解析组织。结账和门户流程仅限网页使用（无法通过 API 密钥访问）。

---

常见注意事项

• 始终使用 --json：CLI 会自动检测非 TTY 环境并输出 JSON，但以编程方式运行时，始终显式传入 --json，以确保可靠性。
• ID 是 UUID（--installation-id 除外）：所有 --id、--project-id、--org-id 等参数都需要使用先前创建或列出命令返回的 UUID 值。有两个不同的安装 ID 标志，它们接受的值类型不同。--installation-id（用于 github repos、github branches、github detect）需要 GitHub 安装的数字 ID（github installations --json 返回的 installationId 字段，例如 122432012）。--github-installation-id（用于 repositories create/update）需要 UUID（github installations --json 返回的 id 字段）。务必从 JSON 响应中同时获取这两个 ID。
• 项目语言 ID 与全局语言 ID：术语表（--source-language-id、--target-language-id）和风格指南（--language-id）命令使用_项目语言_ UUID，即特定项目内某种语言的 ID。请从 project-languages list 获取，而不是从 languages list 获取。translation-memories 命令是个例外：它们使用普通区域设置（--source-locale、--target-locale），因为记忆会在项目之间共享。
• GitHub 仓库需要 GitHub App：连接 GitHub 仓库时，请使用 GitHub App 流程（github installations / github install）获取安装 ID，并在 repositories create 中通过 --github-installation-id 传入。否则，Globalize 将无法访问仓库内容。使用 github install --no-wait --json 获取安装 URL，而不必等待；将其提供给用户，然后使用 github install-status --nonce <NONCE> --json 检查是否完成。
• 模式需单独管理：创建仓库后，使用 patterns list/create/update/delete/reorder 管理区域设置路径模式。repositories create 中的 --patterns 标志仅用于初始设置。创建后更改模式，需要使用模式 CRUD 命令。
• GitLab 使用连接，而非安装：对于 GitLab 仓库，请使用 gitlab connections（而不是 github installations），并在 repositories create 中传入 --gitlab-connection-id（而不是 --github-installation-id）。GitLab 项目 ID 是数字（不是 UUID）。
• 创建项目前验证语言：始终获取 languages list --json，并将用户所需的区域设置与目录匹配。使用返回的 UUID 作为 --source-language 和 --target-languages 的值，不要传入原始区域设置代码。对于目录中找不到匹配项的不受支持语言，请告知用户。
• 非交互环境中的身份验证：没有 TTY 时，CLI 不会回退到交互式登录。请确保已设置 GLOBALIZE_API_KEY 或存在 ~/.globalize/config.json。