推荐词汇表

为确保文档的一致性，技术写作团队推荐使用以下词汇选择。此外：

• GitLab 手册包含一份常见误用术语列表。
• 文档样式指南包含关于语言和大小写的详细信息。
• GitLab 手册提供了关于第三方商标使用的指导。

对于本页未涵盖的指导，我们参考以下样式指南：

• 微软样式指南
• 谷歌开发者文档样式指南

.gitlab-ci.yml 文件

对 the .gitlab-ci.yml file 使用反引号和小写字母。

尽可能使用完整短语：the .gitlab-ci.yml file

尽管用户可以为他们的 CI/CD 配置文件指定另一个名称，但在大多数情况下，应使用 the .gitlab-ci.yml file。

&（与符号）

不要使用拉丁缩写。改用 and，除非您正在记录使用 & 的 UI 元素。

@mention

尽量避免使用 @mention。改说 mention，并考虑链接到提及主题。不要使用反引号。

2FA，双因素认证

首次使用及主题标题中，以句首字母大写形式拼写 two-factor authentication，之后使用 2FA。如果作为句子开头，不要大写 factor 或 authentication。例如：

• 双因素认证（2FA）有助于保护您的账户。首次登录时设置 2FA。

ability，able

尽量避免使用 ability 或 able，因为它们可能存在歧义。这些词的用法类似于allow 和 enable。不要谈论用户的“能力”或产品的“功能”，而是直接具体地描述。不过，在讨论安全或防止某人能够完成 UI 中的任务时，可以使用这些术语。不要将 ability 或 able 与权限或角色混淆。

使用：

• 您无法更改此设置。
• 要更改此设置，您必须拥有 Maintainer 角色。
• 确认您可以登录。
• 外部负载均衡器无法连接。
• GitLab 17.1 中引入的删除分支选项。

而非：

• 您无法更改此设置。（注：此处原文 “You are not able to…” 翻译为更自然的“您无法…”）
• 您必须具备更改此设置的权限。
• 验证您可以登录。
• 外部负载均衡器将无法连接。
• GitLab 17.1 中引入的删除分支功能。

above

在文档页面中引用示例或表格时，尽量避免使用 above。如需使用，改用 previous。例如：

• 在前面的示例中，狗有跳蚤。

引用产品版本时，不要使用 above。改用later。

使用：

• In GitLab 14.4 及更高版本…

而非：

• In GitLab 14.4 及以上版本…
• In GitLab 14.4 及更高版本…
• In GitLab 14.4 及更新版本…

访问级别

访问级别不同于角色或权限。创建用户时，您会选择一个访问级别：Regular、Auditor 或 Administrator。引用 UI 时大写这些词。否则使用小写。

add

当对象已存在时使用 add。如果对象尚不存在，则使用create。Add 是remove的反义词。例如：

• 向列表添加用户。
• 将问题添加到史诗中。

不要将 add 与create混淆。不要使用 Add new。

Admin 区域

使用：

• Admin 区域，用于描述 UI 中的这个区域。
• Admin 用于 UI 按钮。

而非：

• Admin area（两个词都加粗）
• Admin Area（Area 大写）
• Admin Area（Area 大写）
• administrator area
• 或其他变体

Admin 模式

对 Admin Mode 使用标题大小写。UI 使用标题大小写。

好的，这是按照您的要求翻译后的内容：

## administrator

在讨论用户访问级别时，使用 **administrator access** 而不是 **admin**。

![admin access level](img/admin_access_level_v15_9.png)

**administrator** 不是一种 [角色](#roles) 或 [权限](#permissions)。

使用：

- 要执行此操作，您必须是管理员。
- 要执行此操作，您必须拥有管理员访问权限。

而不是：

- 要执行此操作，您必须拥有 Admin 角色。

## advanced search

使用小写字母表示 **advanced search**，指代在整个 GitLab 实例中更快、更高效的搜索。

## agent for Kubernetes

使用小写字母来指代 [GitLab agent for Kubernetes](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent)。
例如：

- 要将您的集群连接到 GitLab，请使用 GitLab agent for Kubernetes。
- 在您的集群中安装代理。
- 从列表中选择一个代理。

不要对 **GitLab Agent** 或 **GitLab Agent for Kubernetes** 使用标题大小写。

在技术上下文中提及特定组件时，请使用反引号中的 `agentk`。

## agent for workspace

当指代在工作区中运行并用于访问工作区的组件时，使用小写的 **agent for workspace**。不要对 **Workspace** 使用标题大小写。例如：

- agent for workspace 处理工作区中的 GitLab 集成任务。
- 配置 agent for workspace 以连接您的开发环境。

在技术上下文中提及特定组件时，请使用反引号中的 `agentw`。

不要与 [agent for Kubernetes](#agent-for-kubernetes) 混淆。

## agent access token

创建 Kubernetes 代理时生成的令牌。使用 **agent access token**，而非：

- registration token
- secret token
- authentication token

## Agentic Chat, GitLab Duo Agentic Chat

GitLab Duo Agentic Chat 是 [GitLab Duo Chat](#chat-gitlab-duo-chat) 的实验性增强版本。

对于 **Agentic Chat** 或 **GitLab Duo Agentic Chat**，使用大写字母 `A` 和 `C` 表示 **Agentic Chat**。

在页面首次使用时，使用 **GitLab Duo Agentic Chat**。
此后，单独使用 **Agentic Chat**。

不要使用 **Duo Agentic Chat**。

## agnostic

不要使用 **agnostic**，而是使用 **platform-independent** 或 **vendor-neutral**。
（[Vale](../testing/vale.md) 规则：[`SubstitutionWarning.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab_base/SubstitutionWarning.yml)）

## AI, artificial intelligence

使用 **AI**。不要拼写为 **artificial intelligence**。

## AI agent

在撰写关于 AI 的内容时，**AI agent** 是代表用户执行操作的实体。

首次使用后，您可以仅使用 **agent** 而不用 **AI**。

当您与 AI agent 交互时，会运行一个 [**session**](#session)。
用户可以停止会话。

一个或多个 AI agent 可以是 [**flow**](#flows) 的一部分，它们被编排在一起协同解决问题。

## AI gateway

使用小写字母表示 **ai gateway**，并且不要连字符。

## AI Impact Dashboard

对 **AI Impact Dashboard** 使用标题大小写。

在页面上首次提及此词时，使用 **GitLab Duo AI Impact Dashboard**。
此后，单独使用 **AI Impact Dashboard**。

## AI-powered, AI-native

使用 **AI-native** 而不是 **AI-powered**。例如，**Code Suggestions 是一个 AI-native 功能**。

## air gap, air-gapped

使用 **offline environment** 来描述具有物理屏障或安全策略以防止或限制互联网访问的安装。不要使用 **air gap**、**air gapped** 或 **air-gapped**。例如：

- 离线环境中的防火墙策略阻止计算机访问互联网。

## allow, enable

尽量避免使用 **allow** 和 **enable**，除非您在谈论与安全相关的功能或功能标志的状态。

使用：

- 您可以向仓库添加文件。

而不是：

- 此功能允许您向仓库添加文件。
- 此功能允许用户向其仓库添加文件。

这种表述更加主动，是从用户的角度出发，而不是从实现该功能的人的角度。

有关更多信息，请参阅 [Microsoft Style Guide](https://learn.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/a/allow-allows)。

## analytics

对 **analytics** 及其变体（如 **contribution analytics** 和 **issue analytics**）使用小写字母。
但是，如果 UI 有不同的大小写，请使文档与 UI 匹配。

例如：

- 您可以查看项目的合并请求分析。它们显示在“Merge Request Analytics”仪表板上。

## ancestor

要指代层次结构中比父项高一级或更多级的 [parent item](#parent)，请使用 **ancestor**。

不要使用 **grandparent**。

示例：

- 一个祖先组，项目层次结构中的一个组。
- 一个祖先史诗，问题层次结构中的一个史诗。
- 一个组和它的所有祖先。

另见：[child](#child)、[descendant](#descendant) 和 [subgroup](#subgroup)。

and/or

不要使用 and/or，改用 or 或重写句子以明确两种选项。

and so on

不要使用 and so on。相反，应更具体。更多信息请参阅 Microsoft 风格指南。

area

使用 section 而非 area。唯一例外是 Admin 区域。

as

不要用 as 表示 because。

使用：

• 因为所有端点都不返回 ID…

而非：

• 由于所有端点都不返回 ID…

as well as

不要使用 as well as，改用 and。

associate

描述将问题添加到史诗、用户添加到问题、合并请求或史诗时，不要使用 associate。

改用 assign。例如：

• 将问题分配给史诗。
• 为问题分配用户。

authenticated user

使用 authenticated user 而非其他变体，如 signed in user 或 logged in user。

authenticate

使用 authenticate 作为动词时，尽量选用合适的介词。

当涉及执行身份验证的系统或提供者（如令牌或 OAuth 这类服务）时，使用 authenticate with。

例如：

• 使用部署令牌进行身份验证。
• 使用您的凭据进行身份验证。
• 通过 OAuth 进行身份验证。
• 运行者使用身份验证令牌与 GitLab 进行身份验证。

当涉及包含需验证凭据的资源时，使用 authenticate against。

例如：

• 客户端对 LDAP 目录进行身份验证。
• 脚本针对本地用户数据库进行身份验证。

before you begin

记录用户完成教程前必须完成的任务或满足的条件时，使用 before you begin。不要使用 requirements 或 prerequisites。

更多信息请参阅 教程页面类型。

对于任务主题类型，改用 prerequisites。

below

提及文档页面的示例或表格时，尽量避免使用 below。若必须使用，改用 following。例如：

• 在以下示例中，狗有跳蚤。

beta

beta 用小写。例如：

• 该功能处于 beta 阶段。
• 这是 beta 功能。
• 此 beta 版本已准备好测试。

撰写关于 beta 功能的内容时，你可能还想链接到 此主题。

blacklist

不要使用 blacklist。另一种选择是 denylist。（Vale 规则：InclusiveLanguage.yml）

board

boards、issue boards 和 epic boards 均用小写。

box

指代 UI 字段时使用 text box。不要使用 field 或 box。例如：

• 在 变量名 文本框中输入一个值。

branch

单独使用 branch 描述分支。特定分支仅使用以下术语：

• default branch：仓库的主分支。用户可通过 UI 设置默认分支。使用示例时，用 main 替代 master。
• source branch：你正在合并的源分支。
• target branch：你正在合并的目标分支。
• current branch：你已检出的分支。该分支可能是主分支、你创建的分支、源分支或其他分支。

不要使用 feature branch 或 merge request branch。尽可能具体。例如：

• 你已检出的分支…
• 你添加了提交的分支…

bullet

不要将有序或无序列表中的单个项目称为 bullets。改用 list item。为减少歧义，可使用：

• 有序列表项：用于有序列表中的项目。
• 无序列表项：用于无序列表中的项目。

button

不要为 button 添加描述符。

使用：

• 选择 运行管道。

而非：

• 选择 运行管道 按钮。

cannot, can not

使用 cannot 而非 can not。

另见 缩略语。

card

尽管 UI 术语可能是 card，但在文档中不要使用它。若能避免，请不要添加描述符。

使用：

• 通过 座位利用率，选择 分配座位。

而非：

• 在 座位利用率 卡片上，选择 分配座位。

Chat, GitLab Duo Chat

GitLab Duo Chat 是一款 AI 原生助手，帮助开发者获取上下文化的对话式代码解释、故障排除和指导。

它与 GitLab Duo Agentic Chat 不同。

使用大写 C 的 Chat 指代 Chat 或 GitLab Duo Chat。

在页面首次使用时，使用 GitLab Duo Chat。 此后，单独使用 Chat。

不要使用 Duo Chat。

复选框

对 复选框 使用一个单词。不要使用 check box。

你 选择（而非 check 或 enable），并 清除（而非 deselect 或 disable）复选框。例如：

• 选择 保护环境 复选框。
• 清除 保护环境 复选框。

如果必须提及复选框，可以说它被选中或已清除。例如：

• 确保 保护环境 复选框已被清除。
• 确保 保护环境 复选框已被选中。

（对于 deselect，Vale 规则：SubstitutionWarning.yml）

检出、check out

将 check out 用作动词。对于 Git 命令，使用 checkout。

• 使用 git checkout 在本地检出分支。
• 检出你要编辑的文件。

cherry-pick

使用带连字符的 cherry-pick。不要使用 cherry pick。

CI、CD

讨论 GitLab 功能时，使用 CI/CD。不要单独使用 CI 或 CD。

CI/CD

CI/CD 始终为大写。首次使用时不要求拼写全称。

上下文清晰时可省略 CI/CD，尤其是首次使用后。例如：

• 在 CI/CD 管道 中测试你的代码。配置 管道 以运行合并请求。
• 将值存储在 CI/CD 变量 中。将 变量 设为掩码。

CI/CD 分钟

不要使用 CI/CD 分钟。该术语已重命名为 计算分钟。

子项

始终用作复合名词。

示例：

• 子问题
• 子史诗
• 子目标
• 子关键结果
• 子流水线

另见：后代、父项 和 子组。

点击

不要使用 点击。而是对按钮、链接、菜单项和列表使用 选择。 选择 适用于更多设备，而 点击 更具体于鼠标操作。

但是，你可以对 右键单击 和 点击演示 破例。

云许可

避免使用 云许可，除非你必须描述通过互联网同步激活码的过程。

如果可以，最好关注此订阅与 GitLab 同步的事实。

例如：

• 你的实例必须能够与 GitLab 同步你的订阅数据。

云原生

当你谈论使用 Kubernetes 集群托管 GitLab 时，你指的是 GitLab 的云原生版本。 此版本不同于用于部署 GitLab 的更大、更 monolithic 的 Linux 包。

你也可以简称为 云原生 GitLab。它应带有连字符且为小写。

代码补全

代码建议已演变为包含两个主要功能：

• 代码补全
• 代码生成

对 代码补全 使用小写。不要使用 GitLab Duo 代码补全。 GitLab Duo 仅保留给代码建议使用。

代码补全 必须始终为单数。

示例：

• 使用代码补全填充文件。

代码解释

对 代码解释 使用首字母大写。

在页面上首次提及，使用 GitLab Duo 代码解释。 此后，仅使用 代码解释 本身。

代码生成

代码建议已演变为包含两个主要功能：

• 代码补全
• 代码生成

对 代码生成 使用小写。不要使用 GitLab Duo 代码生成。 GitLab Duo 仅保留给代码建议使用。

代码生成 必须始终为单数。

示例：

• 使用代码生成基于你的评论创建代码。
• 通过向文件添加代码注释来调整你的代码生成结果。

代码所有者、code owner、CODEOWNERS

使用 代码所有者 指代功能名称或概念。例如：

• 使用代码所有者审批规则保护你的代码。

使用 code owner 或 code owners（小写）指代人或具有代码所有权职责的组。 例如：

• 为项目分配代码所有者。
• 联系代码所有者进行审核。

不要使用 codeowner、CodeOwner 或 code-owner。

使用 CODEOWNERS（大写且带反引号）指代文件名。例如：

• 编辑 CODEOWNERS 文件以定义代码所有权规则。

代码审查摘要

对 代码审查摘要 使用首字母大写。

在页面上首次提及，使用 GitLab Duo 代码审查摘要。 此后，仅使用 代码审查摘要 本身。

代码建议（Code Suggestions）

对 Code Suggestions 使用首字母大写。在页面的首次提及处，使用 GitLab Duo 代码建议。

Code Suggestions（该功能）应始终以 s 结尾。不过，写作时要像单数一样。例如：

• 实例已开启代码建议。

当泛指该功能输出的建议时，使用小写。

示例：

• 使用代码建议在你输入时显示建议。（此短语描述功能。）
• 输入时，会显示建议。（此短语是泛指。）

Code Suggestions 已演变为包含两个主要功能：

• 代码补全
• 代码生成

折叠（collapse）

当你谈论 UI 中展开或折叠某个部分时，使用 collapse 而不是 close。

命令行（command line）

使用 从命令行 来引入命令。

用作形容词时连字符连接。例如，命令行工具。

计算（compute）

使用 compute 指代运行器用于运行 CI/CD 作业的资源。

相关术语：

• 计算分钟数：如何计算计算使用量。例如，400 计算分钟。
• 计算配额：命名空间每月可使用的计算分钟数上限。
• 计算使用量：命名空间从月度配额中使用的计算分钟数。

计算分钟数（compute minutes）

使用 计算分钟数 替代这些（或类似）术语：

• CI/CD 分钟
• CI 分钟
• 流水线分钟
• CI 流水线分钟
• 流水线分钟

更多信息，请参见 epic 2150。

配置（configuration）

当你编辑一组设置时，称之为 配置。

配置（configure）

在功能或产品完成 设置 后，使用 配置。

例如：

1. 设置你的安装。
2. 配置你的安装。

确认对话框（confirmation dialog）

使用 确认对话框 描述要求你确认操作的对话框。例如：

• 在确认对话框上，选择 确定。

不要使用 确认框 或 确认对话框框。另见 对话框。

容器注册表（container registry）

在记录 GitLab 容器注册表功能和特性时，使用小写。

使用：

• GitLab 容器注册表支持 A、B 和 C。
• 你可以将 Docker 镜像推送到项目的容器注册表中。

创建（create）

当对象不存在且你首次创建它时，使用 创建。创建 是 删除 的反义词。

例如：

• 创建一个问题。

不要将 创建 与 添加 混淆。

不要使用 创建新的。单词 创建 已暗示对象是新对象，额外词汇没有必要。

当前（currently）

谈论产品或其功能时，不要使用 currently。文档描述的是产品当前的模样。

（Vale 规则：CurrentStatus.yml）

自定义角色（custom role）

当指代具有特定自定义权限的角色时，使用 自定义角色。

当指代非自定义角色时，使用 默认角色。

数据（data）

将 data 用作单数名词。

使用：

• 数据被收集。
• 数据显示性能提升。

而非：

• 数据被收集。（错误，应为单数）
• 数据显示性能提升。（错误，应为单数）

截止日期（deadline）

不要使用 deadline。改用 截止日期。

默认角色（default role）

当指代以下无自定义权限的预定义角色时，使用 默认角色：

• Guest
• Planner
• Reporter
• Developer
• Maintainer
• Owner
• Minimal Access

不要使用 静态角色、内置角色 或 预定义角色。

删除（delete）

当对象被完全删除时，使用 删除。删除 是 创建 的反义词。

当对象继续存在时，改用 移除。例如，你可以从史诗中移除一个问题，但问题仍存在。

依赖代理（Dependency Proxy）

对 GitLab 依赖代理使用首字母大写。

部署看板（deploy board）

对 deploy board 使用小写。

后代（descendant）

若要指代层级中下一级或更下级的 子项，使用 后代。

不要使用 孙项。

示例：

• 一个后代项目，即群组层级结构中的项目。
• 一个后代问题，即史诗层级结构中的问题。
• 一个群组及其所有后代。

另见：祖先、子项 和 子群组。

开发者

在撰写关于开发者角色时：

• 使用大写字母 D。
• 写全称。
  • 使用：如果你被分配了开发者角色
  • 而不是：如果你是一名开发者

当开发者角色是最低要求的角色时：

• 使用：至少开发者角色
• 而不是：开发者角色或更高

不要使用粗体。

不要使用 开发者权限。被分配开发者角色的用户拥有一组关联的权限。

dialog

使用 dialog 而非以下任何替代项：

• dialog box
• modal
• modal dialog
• modal window
• pop-up
• pop-up window
• window

另见 确认对话框。更多信息，请参阅 Microsoft 风格指南。

在使用此术语前，请确认 dialog 或 drawer 是否适用于你的用例。

当对话框是操作的位置时，使用 on 作为介词。例如：

• 在 Grant permission 对话框上，选择 Group。

另见 on。

disable

不要使用 disable 来描述使设置或功能不可用。改用 turn off、hide、make unavailable 或 remove 等替代项。

若要描述状态，使用 off、inactive 或 unavailable。

此指导依据 Microsoft 风格指南。

disallow

使用 prevent 替代 disallow。（Vale 规则：Substitutions.yml）

Discussion Summary

对 Discussion Summary 使用标题大小写。

在页面首次提及处，使用 GitLab Duo Discussion Summary。此后，单独使用 Discussion Summary。

Docker-in-Docker, dind

当你描述通过 Docker 执行器运行 Docker 容器时，使用 Docker-in-Docker。

使用反引号中的 dind 描述容器名称：docker:dind。否则，拼出全称。

downgrade

为了更积极且准确，不要使用 downgrade。转而关注用户正在执行的操作。

• 对于切换到更早的 GitLab 版本，使用 回滚。
• 对于切换到更低的 GitLab 层级，使用 更改订阅层级。

download

使用 download 描述将数据保存到用户的设备上。详情请参阅 Microsoft 风格指南。

不要将下载与 导出 混淆。

drawer

使用 drawer 描述一个 抽屉式 UI 组件，该组件：

• 从屏幕右侧弹出。
• 显示上下文相关的信息或操作，无需用户离开当前页面。

要查看抽屉的示例：

• 前往 技术写作管道编辑器 并选择 帮助 ( )。
• 打开 GitLab Duo Chat。

在使用此术语前，请确认 drawer 或 dialog 是否适用于你的用例。

dropdown list

使用 dropdown list 指代 UI 元素。不要在没有 list 的情况下使用 dropdown。不要使用带连字符的 drop-down、dropdown menu 或其他变体。

例如：

• 从 Visibility 下拉列表中选择 Public。

earlier

讨论版本号时使用 earlier。

使用：

• 在 GitLab 14.1 及更早版本中。

而非：

• 在 GitLab 14.1 及更低版本中。
• 在 GitLab 14.1 及更旧版本中。

easily

不要使用 easily。如果用户觉得流程并不容易，我们会失去他们的信任。

edit

对于 UI 文档和用户操作，使用 edit。

例如：

• 要编辑个人资料设置，选择 Edit。

对于 API 文档和程序化变更，使用 更新。

e.g.

不要使用拉丁缩写。改用 for example、such as、for instance 或 like。（Vale 规则：LatinTerms.yml）

ellipsis, ellipses

尽可能避免省略号。如果必须包含它们，例如作为代码块或其他 CLI 响应的一部分，使用无空格的三点（...），而不是 … HTML 实体或 … HTML 代码。

更多信息，请参阅 代码块。

记录 UI 文本时不要包含任何省略号。例如，使用：

• 搜索或前往

而非：

• 搜索或前往…

更多信息，请参阅 Microsoft 风格指南。

email

不要使用带连字符的 e-mail。复数形式时，使用 emails 或 email messages。(Vale 规则：SubstitutionWarning.yml)

email address

当指代电子邮件中使用的地址时，使用 email address。不要缩写为 email（表示消息）。

emoji

使用 emoji 来指代 emoji 的复数形式。

enable

不要用 enable 来描述使设置或功能可用。改用 turn on。

要描述状态，使用 on 或 active。

此指导基于 Microsoft Style Guide。

enter

在大多数情况下，使用 enter 而不是 type。

• Enter 涵盖了多种输入信息的方式，包括语音和键盘。
• Enter 假设用户在字段中输入值，然后将光标移到字段外（或按下 Enter）。Enter 包括内容的输入和验证内容的操作。

例如：

• 在 Variable name 文本框中，输入一个值。
• 在 Variable name 文本框中，输入 my text。

当你使用 Enter 指代键盘上的按键时，使用 HTML <kbd> 标签：

• 要查看结果列表，按 Enter。

另见 type。

epic

对 epic 使用小写。

另见 associate。

epic board

对 epic board 使用小写。

etc.

尽量避免使用 etc.。尽可能具体。不要用 and so on 作为替代。

使用：

• 你可以编辑对象，如合并请求和问题。

而不是：

• 你可以编辑对象，如合并请求、问题等。

expand

当你在谈论 UI 中展开或折叠某个部分时，使用 expand 而不是 open。

experiment

对 experiment 使用小写。例如：

• 此功能是一个实验。
• 这些功能是实验。
• 此实验已准备好测试。

如果必须，你可以使用 experimental。

在编写关于实验性功能的文章时，你可能还想链接到 此主题。

export

使用 export 表示将原始数据转换为标准文件格式，这些原始数据在 GitLab 中没有对应的文件。

你可以将 export 与 download 区分开来，因为：

• 通常，你可以使用导出选项来更改输出。
• 导出的数据不一定下载到用户的设备上。

例如：

• 将报告内容导出为 CSV 格式。

不要与 download 混淆。

FAQ

我们希望用户能快速找到信息，但他们很少搜索 FAQ 这个词。

FAQ 中的信息应与其他类似信息放在一起，并在可搜索的主题标题下。

feature

你应该很少使用 feature 这个词。相反，解释 GitLab 所做的事情。

例如，使用：

• 使用合并请求将更改合并到目标分支。

而不是：

• 使用合并请求功能将更改合并到目标分支。

feature branch

不要使用 feature branch。参见 branch。

field

使用 text box 而不是 field 或 box。

使用：

• 在 Variable name 文本框中，输入 my text。

而不是：

• 在 Variable name 字段中，输入 my text。

但是，当你编写任务并想一次引用所有字段时，可以例外。例如：

1. 在左侧边栏中，选择 Search or go to 并找到你的项目。
2. 选择 Settings > CI/CD。
3. 展开 General pipelines。
4. 完成各个字段。

了解更多关于 同时记录多个字段 的信息。

filename

对 filename 使用一个单词。当将 filename 用作变量时，使用 <filename>。

(Vale 规则：SubstitutionWarning.yml)

filter

当你查看项目列表（如问题或合并请求）时，你可以通过可用属性过滤列表。例如，你可以按分配人或审阅人过滤。

过滤不同于 searching。

flows

GitLab 提供由 AI agents 运行的多个 flows。

flow 和 agent flow 都是可以接受的。

你选择一个流程。你启动一个 session。

foo

不要在产品文档中使用 foo。你可以在我们的 API 和贡献者文档中使用它，但尽量使用更清晰、更有意义的示例代替。

fork

fork 是指通过分叉流程从上游项目（也称为源项目）创建的项目。

上游项目和分支项目存在分支关系且相互关联。

如果移除分支关系，则分支项目与上游项目****解除关联。

Free

使用大写的Free表示免费订阅层级。当在其他订阅层级的语境下提及Free时，请遵循订阅层级指南。

全屏

全屏使用两个词。（Vale 规则：SubstitutionWarning.yml）

将来时态

尽可能使用现在时态而非将来时态。例如，使用执行此命令后，GitLab 显示结果 而非 执行此命令后，GitLab 将显示结果。（Vale 规则：FutureTense.yml）

GB, 千兆字节

对于GB和MB，遵循微软指南。

Geo

对Geo使用标题大小写。

一般可用性

对generally available和general availability使用小写。 例如：

• 此功能一般可用。

更常使用generally available。例如， 不要说：

• 此功能已达到通用可用性。

不要使用GA缩写通用可用性。

GitLab

不要将GitLab变为所有格（如 GitLab’s）。此指导遵循GitLab 商标指南。

不要将GitLab放在其他第三方工具或品牌的名称旁边。 例如，不要使用：

• GitLab Chrome 扩展
• GitLab Kubernetes 代理

而是使用：

• GitLab 适用于 Chrome 的扩展
• GitLab 适用于 Kubernetes 的代理

将品牌名称并列放置可能暗示所有权或合作关系，而我们不想这样做， 除非我们已完成法律审查并被要求推广该合作。

此指导遵循第三方商标的使用。

GitLab AI 供应商模型

使用GitLab AI 供应商模型指代由第三方提供商托管并通过 GitLab AI 网关 通过 云连接器 由客户访问的大语言模型。

当语言模型由客户自行托管，或客户使用 GitLab Duo 自托管 功能时，不要使用此术语。

GitLab Dedicated

使用GitLab Dedicated 指代产品方案。它指的是由 GitLab 为客户托管和管理的 GitLab 实例。

GitLab Dedicated 可被称为单租户 SaaS 服务。

不要单独使用Dedicated。始终使用GitLab Dedicated。

GitLab Duo

不要单独使用Duo。始终使用GitLab Duo。

在页面首次使用时，使用GitLab Duo <featurename>。截至 2024 年 8 月， 以下为 GitLab Duo 功能的名称：

• GitLab Duo AI 影响仪表板
• GitLab Duo 聊天
• GitLab Duo 代码解释
• GitLab Duo 代码评审
• GitLab Duo 代码评审摘要
• GitLab Duo 代码建议
• GitLab Duo 适用于 CLI
• GitLab Duo 问题描述生成
• GitLab Duo 问题讨论摘要
• GitLab Duo 合并提交消息生成
• GitLab Duo 合并请求摘要
• GitLab Duo 产品分析
• GitLab Duo 根因分析
• GitLab Duo 自托管
• GitLab Duo 测试生成
• GitLab Duo 漏洞解释
• GitLab Duo 漏洞解决

除 GitLab Duo 自托管外，首次使用后，使用不带GitLab Duo的功能名称。

GitLab Duo 代理平台

使用GitLab Duo 代理平台。首次使用后，使用代理平台。

不要单独使用Duo 代理平台。

GitLab Duo Core

使用 GitLab Duo Core 作为附加组件。不要单独使用 Duo Core。

你也可以使用 GitLab Duo Core 附加组件，但在能省略时去掉 add-on。

在营销材料（如发布帖或博客）中，使用 Premium 和 Ultimate with GitLab Duo 而非 GitLab Duo Core。例如：

• 博客：为每位 GitLab Premium 和 Ultimate 客户解锁 AI
• 发布帖：Premium 和 Ultimate 的群组和项目控制（含 GitLab Duo）

GitLab Duo Enterprise

始终使用 GitLab Duo Enterprise 作为附加组件。除非法律部门批准，否则不要使用 Duo Enterprise。

你可以使用 GitLab Duo Enterprise 附加组件（保持此大写形式），但不强制要求使用 add-on，且在能省略时应去掉它。

GitLab Duo Pro

始终使用 GitLab Duo Pro 作为附加组件。除非法律部门批准，否则不要使用 Duo Pro。

你可以使用 GitLab Duo Pro 附加组件（保持此大写形式），但不强制要求使用 add-on，且在能省略时应去掉它。

GitLab Duo Self-Hosted

提及该功能时，始终完整书写并使用首字母大写形式 GitLab Duo Self-Hosted，除非你是在指代由客户而非 GitLab 托管的模型。

不要单独使用 Self-Hosted。

GitLab Flavored Markdown

尽可能拼写全称 GitLab Flavored Markdown。

若必须缩写，不要使用 GFM，改用 GLFM。

GitLab for Eclipse plugin, Eclipse

使用 GitLab for Eclipse plugin 指代编辑器扩展。

使用 Eclipse 指代集成开发环境（IDE）。

GitLab Helm chart, GitLab chart

要部署云原生版本的 GitLab，请使用：

• GitLab Helm chart（长版本）
• GitLab chart（短版本）

不要使用 the gitlab chart、the GitLab Chart 或 the cloud-native chart。

你使用 GitLab Helm chart 将 cloud-native GitLab 部署到 Kubernetes 集群中。

若在描述不同安装方法的上下文中使用，则使用 Helm chart (Kubernetes)。

GitLab Pages

为保持一致性和品牌形象，使用 GitLab Pages 而非 Pages。

然而，如果在页面或 UI 中首次提及 GitLab Pages，之后可以使用 Pages。

GitLab Runner

对 GitLab Runner 使用首字母大写形式。这是你要安装的产品。有关此用法决策的更多信息，请参阅 此问题。

另见：

• runners
• runner managers
• runner workers

GitLab SaaS

GitLab SaaS 指的是 GitLab.com（多租户 SaaS）和 GitLab Dedicated（单租户 SaaS）。

尽量避免使用 GitLab SaaS，而是引用具体产品。

GitLab Self-Managed

使用 GitLab Self-Managed 指代客户管理的 GitLab 安装。

使用所需的 instance 描述符。不要使用 installation。使用：

• GitLab Self-Managed
• 一个 GitLab Self-Managed 实例

代替：

• 一个 GitLab Self-Managed 安装
• 一个 Self-Managed GitLab 安装
• 一个自管理的 GitLab 安装
• 一个 GitLab Self-Managed 的 GitLab 实例

你可以单独使用 instance 来描述 GitLab Self-Managed。例如：

• 在你的实例上，确保端口开放。
• 验证实例是否公开可访问。

另见 self-managed。

GitLab.com

使用 GitLab.com 指代 URL 或产品服务。GitLab.com 是由 GitLab 管理的实例。

GitLab Workflow extension for VS Code

使用 GitLab Workflow extension for VS Code 指代该扩展。你也可以使用 GitLab Workflow for VS Code 或 GitLab Workflow。

有关 VS Code 中的术语，请参见 VS Code 用户界面

GraphiQL

使用 GraphiQL 或 GraphQL explorer 指代此工具。

大多数情况下，应单独使用 GraphiQL 且不加描述符。

不要使用：

• GraphiQL explorer 工具
• GraphiQL explorer

group access token

对 group access token 使用句子大小写。

引用 UI 时首字母大写。

guide

我们希望直接与用户对话。在 docs.gitlab.com 上，不要将 guide 用作页面标题的一部分。例如，Snowplow Guide。相反，谈论功能本身及其使用方式。例如，使用 Snowplow 做 xyz。

Guest

当撰写关于访客角色（Guest）的内容时：

• 使用大写字母 G。

• 完整写出：

  • 使用：如果你被分配了访客角色
  • 而不是：如果你是一个访客

• 当访客角色是最小必需角色时：

  • 使用：至少访客角色
  • 而不是：访客角色或更高

不要使用粗体。

不要使用 访客权限。被分配访客角色的用户有一组关联的权限。

handy

不要使用 handy。如果用户觉得功能或流程不够顺手，我们会失去他们的信任。（Vale 规则：Simplicity.yml）

高可用性，HA

不要使用 高可用性 或 HA，除非在 GitLab 参考架构 中。相反，引导读者查看参考架构以获取有关配置 GitLab 以处理更多用户的更多信息。

不要使用像 高可用性设置 这样的短语来表示多节点环境。而是使用 多节点设置 或类似表述。

更高

讨论版本号时不要使用 higher。

使用：

• 在 GitLab 14.4 及以后版本中…

而不是：

• 在 GitLab 14.4 及更高版本中…
• 在 GitLab 14.4 及以上版本中…

按下

不要用 hit 来表示 press。

使用：

• 按下 ENTER 键。

而不是：

• 按 ENTER 按钮。

我

不要使用第一人称单数。使用 你 或改写短语。

即

不要使用拉丁缩写。使用 即 代替。（Vale 规则：LatinTerms.yml）

为了

不要使用 in order to。使用 to 代替。（Vale 规则：Wordy.yml）

索引，indices

对于 index 的复数形式，使用 indexes。

但是，对于 Elasticsearch，使用 indices。

从源代码安装

若指代使用自行编译代码的安装方法，使用 自编译。

使用：

• 对于自编译安装…

而不是：

• 对于从源代码安装…

有关更多信息，请参阅 不同的安装方法。

-ing 形式单词

尽可能移除 -ing 形式的单词。它们可能难以翻译，且通常有更精确的术语。例如：

• 而不是 使用存储的文件被删除，使用 使用存储的文件被删除
• 而不是 使用编辑按钮删除文件，使用 使用编辑按钮删除文件
• 而不是 复制服务器是必需的，使用 你必须复制服务器

问题

对 issue 使用小写。

问题板

对 issue board 使用小写。

问题描述生成

对 Issue Description Generation 使用首字母大写。

在页面首次提及处，使用 GitLab Duo 问题描述生成。 此后，单独使用 问题描述生成。

问题讨论摘要

对 Issue Discussion Summary 使用首字母大写。

在页面首次提及处，使用 GitLab Duo 问题讨论摘要。 此后，单独使用 问题讨论摘要。

问题权重

对 issue weights 使用小写。

IP 地址

指代与互联网协议（IP）一起使用的地址时，使用 IP 地址。不要将 IP 地址简称为 IP。

它

当你使用 it 这个词时，确保它所指代的词很明显。 如果不明显，重复该词而非使用 it。

使用：

• 该字段返回一个连接。该字段接受四个参数。

而不是：

• 该字段返回一个连接。它接受四个参数。

另见 这个、这些、那个、那些。

任务

不要用 build 作为 job 的同义词。任务是在 .gitlab-ci.yml 文件中定义并作为流水线一部分运行的。

如果你想将 CI 与 job 一起使用，使用 CI/CD 任务 而非 CI 任务。

Kubernetes 执行器

GitLab Runner 可以在 Kubernetes 集群上运行任务。为此，GitLab Runner 使用 Kubernetes 执行器。

指代此功能时，使用：

• GitLab Runner 的 Kubernetes 执行器
• Kubernetes 执行器

不要使用：

• GitLab Runner Kubernetes 执行器，因为这可能侵犯 Kubernetes 商标。

语言模型，大型语言模型

指代语言模型时要精确。并非所有语言模型都是大型的，也并非所有模型都是语言模型。如有疑问，向开发人员或产品经理确认。

如果首次使用时拼写出全称，你可以用 LLM 指代大型语言模型。

later

讨论版本号时使用 later。

使用：

• 在 GitLab 14.1 及更高版本中…

而非：

• 在 GitLab 14.1 及更高版本中…
• 在 GitLab 14.1 及以上版本中…
• 在 GitLab 14.1 及更新版本中…

level

如果可以，避免在实例、项目或组的上下文中使用 level。

使用：

• 此设置在实例上开启。
• 此设置在组和其子组上开启。
• 此设置在项目上开启。

而非：

• 此设置在实例级别开启。
• 此设置在组级别开启。
• 这是一个项目级别的设置。

lifecycle, life cycle, life-cycle

对 lifecycle 使用一个单词。不要使用 life cycle 或 life-cycle。

（Vale 规则：SubstitutionWarning.yml）

list

提及 dropdown list 时不要使用 list。请改用完整的短语 dropdown list。

此外，提及页面时也不要使用 list。例如，Issues 页面包含一系列问题，但应称之为 Issues 页面，而非 Issues 列表。

license

许可证与订阅不同。

• 许可证授予用户访问其所购订阅的权限。许可证包含的信息如座位数量和订阅日期。
• 订阅是用户购买的订阅层级。

尽可能避免使用术语 cloud license 或 cloud licensing。

以下术语显示在 UI 和邮件中。必要时可以使用：

• Online license - 与 GitLab 同步的许可证
• Offline license - 未与 GitLab 同步的许可证
• Legacy license - 在同步成为可能之前创建的许可证

描述客户通过电子邮件收到的文件（作为整体许可和同步过程的一部分）时，也可以使用 legacy license file 和 offline license file。

不过，如果能的话，与其依赖该术语，不如使用更具体的描述。

使用：

• 向您的实例添加许可证。
• 购买订阅。

而非：

• 购买许可证。
• 购买许可证。

limitations

不要将 Limitations 用作主题标题。更多信息，请参阅 参考主题标题。

如果必须使用，可以用标题 Known issues。

log in, log on

不要使用：

• log in。
• log on。
• login

改用 sign in。

但是，如果用户界面有 Log in，则应匹配 UI。

limited availability

对 limited availability 使用小写。例如：

• 该功能具有有限可用性。
• 托管运行器处于有限可用状态。

不要使用：

• 该功能已达到有限可用性。

不要用 LA 缩写 limited availability。

logged-in user, logged in user

使用 authenticated user 代替 logged-in user 或 logged in user。

lower

讨论版本号时不要使用 lower。

使用：

• 在 GitLab 14.1 及更早版本中。

而非：

• 在 GitLab 14.1 及更低版本中。
• 在 GitLab 14.1 及更旧版本中。

machine learning

对 machine learning 使用小写。

当机器学习用作形容词时，如 a machine learning model，不要连字符。虽然连字符可能在语法上更正确，但我们若尝试更精确，可能会变得不一致。

Maintainer

撰写关于 Maintainer 角色时：

• 使用大写的 M。

• 完整写出。

  • 使用：如果您被分配了 Maintainer 角色
  • 而非：如果您是维护者

• 当 Maintainer 角色是最低要求的角色时：

  • 使用：至少 Maintainer 角色
  • 而非：Maintainer 角色或更高

不要使用粗体。

不要使用 Maintainer permissions。被分配了 Maintainer 角色的用户拥有一组关联的权限。

mankind

不要使用 mankind。改用 people 或 humanity。（Vale 规则：InclusiveLanguage.yml）

manpower

不要使用 manpower。改用 workforce 或 GitLab 团队成员。（Vale 规则：InclusiveLanguage.yml）

master

不要使用 master。需要示例 默认分支名称 时，改用 main。（Vale 规则：InclusiveLanguage.yml）

may, might

Might 表示某事有发生的概率。Might 常用于故障排查文档中。

May 表示允许做某事。考虑使用 can 代替 may。

考虑改写使用这些术语的短语。这些术语常表示可能性和疑虑，而技术写作力求精确。

另见 you can。

使用：

• committed_date 和 authored_date 字段由不同来源生成，可能不完全一致。
• 典型流水线包含四个阶段，按以下顺序执行：

而非：

• committed_date 和 authored_date 字段由不同来源生成，可能不完全一致。
• 典型流水线可能包含四个阶段，按以下顺序执行：

MB, megabytes

对于 MB 和 GB，遵循 微软指南。

member

当你将 用户账户 添加到组或项目中， 该用户账户将成为一名 成员。

Merge Commit Message Generation

对 Merge Commit Message Generation 使用首字母大写。

在页面首次提及处，使用 GitLab Duo Merge Commit Message Generation。 此后，单独使用 Merge Commit Message Generation。

merge request branch

不要使用 merge request branch。参见 branch。

merge requests

对 merge requests 使用小写。如果你使用 MR 作为缩写，首次使用时需完整写出。

Merge Request Summary

对 Merge Request Summary 使用首字母大写。

在页面首次提及处，使用 GitLab Duo Merge Request Summary。 此后，单独使用 Merge Request Summary。

milestones

对 milestones 使用小写。

Minimal Access

撰写关于 Minimal Access 角色时：

• 使用大写 M 和大写 A。

• 写出全称：

  • 使用：如果你被分配了 Minimal Access 角色
  • 而非：如果你是一名 Minimal Access 用户

• 当 Minimal Access 角色是最小必需角色时：

  • 使用：至少 Minimal Access 角色
  • 而非：Minimal Access 角色或更高

不要使用粗体。

不要使用 Minimal Access 权限。被分配 Minimal Access 角色的用户拥有一组关联权限。

model registry

在记录 GitLab 模型注册表功能和特性时，使用小写。

使用：

• GitLab 模型注册表支持 A、B 和 C。
• 你可以将模型发布到你项目的模型注册表中。

models

用法请参阅 语言模型。

n/a, N/A, not applicable

尽可能使用 not applicable。拼写出该短语有助于非英语用户，并避免大小写不一致问题。

navigate

不要使用 navigate。使用 go 代替。例如：

• 进入此网页。
• 打开终端并进入 runner 目录。

（Vale 规则：SubstitutionWarning.yml）

need to

尽量避免 need to，因为它冗长。

例如，当变量 必需 时， 不要使用 你需要设置该变量，而是使用：

• 设置该变量。
• 你必须设置该变量。

当变量 推荐 时：

• 你应该设置该变量。

当变量 可选 时：

• 你可以设置该变量。

new

通常，你可以避免使用 new。当你创建一个对象时，它已经是新的， 因此你不需要这个额外的词。

另见 create 和 add。

newer

讨论版本号时不要使用 newer。

使用：

• 在 GitLab 14.4 及以后版本…

而非：

• 在 GitLab 14.4 及更高版本…
• 在 GitLab 14.4 及以上版本…
• 在 GitLab 14.4 及更新版本…

normal, normally

不要用 normal 来表示通常、典型或标准的方式。 改用这些术语。

使用：

• 通常，你指定证书。
• 一般而言，你指定证书。
• 遵循标准的 Git 工作流。

而非：

• 正常情况下，你指定证书。
• 遵循正常的 Git 工作流。

（Vale 规则：Normal.yml）

note that

不要使用 note that，因为它冗长。

使用：

• 你可以更改设置。

而非：

• 请注意你可以更改设置。

offerings

当前产品包括：

• GitLab.com
• GitLab 自托管
• GitLab 专用版

可用性详情 反映了这些产品。

older

讨论版本号时不要使用 older。

使用：

• 在 GitLab 14.1 及更早版本。

而非：

• 在 GitLab 14.1 及更低版本。
• 在 GitLab 14.1 及更旧版本。

Omnibus GitLab

当提及使用 Linux 包的安装方式时，将其称为 Linux 包。

使用：

• 对于使用 Linux 包的安装……

而非：

• 对于使用 Omnibus GitLab 的安装……

更多信息请参见不同的安装方法。

on

在描述高级 UI 元素时，将 on 用作介词。例如：

• 在左侧边栏上，选择 设置 > CI/CD。
• 在 授权权限 对话框中，选择 群组。

不要使用 from 或 in。更多信息请参见 Microsoft 风格指南。

once

单词 once 表示 一次。不要用它来表示 之后 或 当……时候。

使用：

• 当流程完成后……

而非：

• 一旦流程完成后……

only

将单词 only 放在被修饰的词旁边。

在以下示例中，only 修饰名词 projects。意思是你可以创建一种类型的项目——私有项目。

• 你只能创建私有项目。

在以下示例中，only 修饰动词 create。意思是你不能执行其他操作，比如删除私有项目或向其添加用户。

• 你只能创建私有项目。

optional

如果某事物是可选的，例如命令参数、参数值或文件，使用 Optional.（句号）。对于可选主题，在主题标题后附加 (optional)。

例如：

### 这是一个主题（可选）

- `value`：可选。用于做某事。

对可选任务步骤也遵循相同指引。

override

使用 override 表示临时替换。

例如，作业运行时值可能会被覆盖。原始值不会改变。

overwrite

使用 overwrite 表示永久替换。

例如，日志文件可能会覆盖同名的日志文件。

Owner

撰写关于 Owner 角色内容时：

• 使用大写的 O。
• 写出全称。
  • 使用：如果你被分配了 Owner 角色
  • 而非：如果你是所有者

不要使用粗体。

不要使用 Owner 权限。被分配 Owner 角色的用户拥有一组关联权限。Owner 是用户可拥有的最高角色。

package registry

在编写 GitLab 包注册表功能和特性文档时，使用小写。

使用：

• GitLab 包注册表支持 A、B 和 C。
• 你可以将包发布到项目的包注册表中。

page

如果你写了类似“在 Issues 页面”这样的短语，需确保附近有如何到达该页面的步骤。否则，人们可能不知道什么是 Issues 页面。

页面名称应在页面顶部 UI 中可见，或包含在面包屑导航中。

文档应与 UI 中的大小写保持一致，且页面名称应加粗。例如：

• 在 测试用例 页面上，……

parent

始终用作复合名词。

不要使用 直接祖先 或 后代。

示例：

• 父目录
• 父组
• 父项目
• 父提交
• 父问题
• 父项
• 父史诗
• 父目标
• 父流水线

另见：子项 和 子组。

per

不要使用 per，因为它可能有多种不同含义。

改用具体的介词短语：

• 每个
• 通过
• 按
• 每
• 根据

permissions

不要互换使用 roles 和 permissions。每个用户被分配一个角色。每个角色包含一组权限。

权限与 访问级别 不同。

personal access token

对 personal access token 使用句子大小写。

在引用 UI 时首字母大写。

Planner

撰写关于 Planner 角色内容时：

• 使用大写的 P。

• 写出全称。

  • 使用：如果你被分配了 Planner 角色
  • 而非：如果你是 Planner

• 当 Planner 角色是最低要求角色时：

  • 使用：至少 Planner 角色
  • 而非：Planner 角色或更高

不要使用粗体。

不要使用 Planner 权限。被分配 Planner 角色的用户拥有一组关联权限。

please

产品文档中不要使用 please。

在 UI 文本中，当我们给用户带来不便时使用 please。更多信息请参见 Microsoft 风格指南。

Premium

对订阅层级使用大写的 Premium。当你在其他订阅层级的上下文中提及 Premium 时，遵循订阅层级 指引。

preferences

使用 preferences 描述用户特定的系统级设置，如主题和布局。

## 先决条件

在记录用户完成某项任务前必须完成的任务或满足的条件时，使用**先决条件**。请勿使用**要求**。

**先决条件**必须始终为复数形式，即使列表中仅包含一项。

更多信息，请参阅[任务主题类型](../topic_types/task.md)。

对于教程页面类型，请使用[**开始前准备**](#before-you-begin)代替。

## 按键

在提及键盘按键时使用**按**。例如：

- 要停止命令，按<kbd>Control</kbd>+<kbd>C</kbd>。

## 脏话

请勿使用脏话。这样做可能会对其他用户和贡献者产生负面影响，这与GitLab的[Diversity, Inclusion, and Belonging（多样性、包容性与归属感）](https://handbook.gitlab.com/handbook/values/#diversity-inclusion)价值观相悖。

## 项目

参见[仓库、项目](#repository-project)。

## 项目访问令牌

对**项目访问令牌**使用句子大小写。

引用UI时首字母大写。

## 配置

在提及配置云基础设施时使用**配置**一词。您配置基础设施，然后将应用程序部署到其上。

例如，您可以这样写：

- 配置一个AWS EKS集群并将您的应用程序部署到其中。

## 推送规则

对**推送规则**使用小写。

## 相当地

请勿使用**相当**，因为它过于冗长。

## `README` 文件

对**the `README` file**或**the `README.md` file**使用反引号和小写。

尽可能使用完整短语：**the `README` file**

复数形式使用**`README` files**。

## 推荐、我们推荐

不要使用**我们推荐**，而是使用**您应该**。我们希望像与同事交谈一样与用户对话，并避免区分“我们”和“他们”。

- 您应该设置该变量。（这是推荐的。）
- 设置该变量。（这是必需的。）
- 您可以设置该变量。（这是可选的。）

另见[推荐步骤](_index.md#recommended-steps)。

## 注册

在谈论创建账户时，使用**注册**而非**sign up**。

## 重建索引

在谈论搜索时，使用**重建索引**而非**re-index**。

## 移除

当对象继续存在时使用**移除**。例如，您可以从史诗中移除一个问题，但该问题仍然存在。

当对象被完全删除时，请改用[**删除**](#delete)。

## Reporter

在撰写关于Reporter角色时：

- 使用大写的**R**。
- 写出全称。
  - 使用：如果您被分配了Reporter角色
  - 不要使用：如果您是一名reporter

- 当Reporter角色是最低要求角色时：
  - 使用：至少Reporter角色
  - 不要使用：Reporter角色或更高

请不要使用加粗。

请不要使用**Reporter权限**。被分配Reporter角色的用户拥有一组关联的权限。

## 仓库、项目

GitLab项目中包含一个Git仓库以及其他内容。在提及Git仓库时使用**仓库**；在提及用于管理和配置Git仓库、Wiki及其他功能的GitLab用户界面时使用**项目**。

## 仓库镜像

对**Repository Mirroring**使用标题大小写。

## 解决方案、解决

当故障排除解决方案永久解决问题时使用**解决方案**。解决方案通常涉及文件和代码更改以纠正问题。例如：

- 要解决这个问题，请编辑`.gitlab-ci.yml`文件。
- 一个解决方案是编辑`.gitlab-ci.yml`文件。

另见[临时解决办法](#workaround)。

## 要求

在记录用户完成步骤前必须完成的任务或满足的条件时：

- 对任务使用**先决条件**。更多信息，请参阅[任务主题类型](../topic_types/task.md)。
- 对教程使用**开始前准备**。更多信息，请参阅[教程页面类型](../topic_types/tutorial.md)。

请不要使用**要求**。

## 重置

使用**重置**来描述将某项重置为新状态的操作。

## 分别地

避免使用**分别地**，而应更精确地表述。

使用：

- 要创建用户，选择**创建用户**。对于现有用户，选择**保存更改**。

不要使用：

- 如果您创建了新用户或编辑了现有用户，则分别选择**创建用户**或**保存更改**。

## 恢复

有关**恢复**的指导，请参阅[微软风格指南](https://learn.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/r/restore)。

## 审查应用

对**review app**使用小写。

## 角色

用户拥有某个项目或组的**角色**。

使用：

- 您必须拥有该组的Owner角色。

不要使用：

- 您必须拥有该组的Owner角色。

请不要将**角色**与[**权限**](#permissions)互换使用。每个用户都被分配了一个角色。每个角色包含一组权限。

存在两种类型的角色：[自定义](#custom-role)和[默认](#default-role)。

角色不同于[**访问级别**](#access-level)。

根本原因分析

对 根本原因分析 使用首字母大写。

在页面的首次提及中，使用 GitLab Duo 根本原因分析。 此后，单独使用 根本原因分析。

回滚

使用 回滚 来表示将 GitLab 版本更改为较早的版本。

不要将 回滚 用于许可或订阅。请改用 更改订阅层级。

runner, runners

对 runners 使用小写。这些是运行 CI/CD 作业的代理。另见 GitLab Runner 和 此问题。

当提及 runners 时，如果必须指定这些 runners 安装在客户的 GitLab 实例上， 使用 自管理 而不是 自托管。

当提及 runners 的范围时，使用：

• 项目 runner：与特定项目关联。
• 组 runner：可供组内的所有项目和子组使用。
• 实例 runner：可供 GitLab 实例中的所有组和项目使用。

runner manager, runner managers

对 runner managers 使用小写。这是一种可以创建多个 runner 以实现自动扩展的 runner 类型。另见 GitLab Runner。

runner worker, runner workers

对 runner workers 使用小写。这是 runner 在主机计算平台上创建的用于运行作业的进程。另见 GitLab Runner。

runner 认证令牌

使用 runner 认证令牌 而非类似 runner 令牌、认证令牌 或 令牌 的变体。 当 runner 创建时会被分配 runner 认证令牌，并在执行作业时用它向 GitLab 进行身份验证。

GitLab 托管 runner

不要使用 Runner SaaS 或 SaaS runners。

使用 GitLab 托管 runner 作为描述托管在 GitLab.com 和 GitLab Dedicated 上的 runners 的主要功能名称。

若需指定产品和服务及操作系统，请使用：

• GitLab.com 的托管 runner
• GitLab Dedicated 的托管 runner
• GitLab.com 的 Linux 托管 runner
• GitLab.com 的 Windows 托管 runner

不要在没有 GitLab- 前缀、没有产品或操作系统的情况下使用 托管 runner。

(s)

不要使用 (s) 使单词成为可选复数形式。这可能会减慢理解速度。例如：

使用：

• 选择您想要的作业。

而非：

• 选择您想要的作业(s)。

如果您可以选择多个某物，则将该词写作复数形式。

完整性检查

不要使用 sanity check。请改用 检查完整性。（Vale 规则：InclusiveLanguage.yml）

可扩展性

在讨论为更多用户提高 GitLab 性能时，不要使用 scalability。scale 或 scaling 有时可以使用，但对为更多用户提高 GitLab 性能的引用应引导读者前往 GitLab 参考架构 页面。

搜索

当您搜索时，请在左侧边栏的搜索框中输入一个字符串。 搜索结果显示在搜索页面上。

搜索不同于 过滤。

座位

当提及订阅计费模式时：

• 对于 GitLab.com，使用 座位。客户购买座位。当用户被邀请加入组时（有少数 例外情况），会占用座位。
• 对于 GitLab 自管理，使用 用户。客户为指定数量的 用户 购买订阅。

区域

使用 区域 来描述页面上的某个区域。例如，如果一个页面有线条将界面划分为不同的区域，将这些区域称为区域。

我们通常将可展开/折叠的区域视为 区域。当您提及展开或折叠某个区域时，不要包含 区域 这个词。

使用：

• 展开 Auto DevOps。

而非：

• 不要：展开 Auto DevOps 区域。

选择

使用 选择 与按钮、链接、菜单项和列表搭配。选择 适用于更多设备， 而 点击 更侧重于鼠标操作。

不过，对于 右键点击 和 点击演示 可以例外。

自托管模型

使用 自托管模型（小写）来指代由客户托管的语言模型，而非 GitLab。

该语言模型可能是大型语言模型（LLM），但也可能不是。

GitLab Duo 自托管

为了避免与 GitLab 自管理 混淆， 当提及 GitLab Duo 自托管 功能 时， 不要单独使用 自托管。

始终完整且以首字母大写的形式书写 GitLab Duo 自托管， 除非您正在 指代由客户托管而非 GitLab 的语言模型。

self-managed

使用 GitLab 自托管版 指代客户安装的 GitLab。

• 不要使用 self-hosted。

参见 GitLab 自托管版。

Service Desk

使用标题大小写表示 Service Desk。

session

当 AI 代理（AI agent）在处理流程（flow）时，会运行一个 session。Session 可以启动和停止。

setup, set up

将 setup 用作名词，set up 用作动词。例如：

• 你的远程办公设置很棒。
• 要正确搭建你的远程办公室，请考虑工作区域的工效学。

不要将 set up 与 configure 混淆。 Set up 表示这是你第一次做某事。例如：

1. 搭建你的安装程序。
2. 配置你的安装程序。

settings

Setting 会改变产品的默认行为。Setting 由键值对组成，通常由带有多个选项的标签表示。

sign in, sign-in

描述登录操作时，使用：

• sign in。
• sign in to 作为动词。例如：使用密码登录 GitLab。

你也可以使用：

• sign-in 作为名词或形容词。例如：sign-in 页面 或 sign-in 限制。
• single sign-on。

不要使用：

• sign on。
• sign into。
• log on、log in 或 log into。

如果用户界面使用了不同的词汇，可以使用那些词汇。

sign up

谈论创建账户时，使用 register 而不是 sign up。

signed-in user, signed in user

使用 authenticated user 而不是 signed-in user 或 signed in user。

simply, simple

不要使用 simply 或 simple。如果用户觉得流程不简单，我们会失去他们的信任。（Vale 规则：Simplicity.yml）

since

单词 since 表示时间段。例如，自 1984 年以来，Bon Jovi 就存在了。不要用 since 表示 because。

使用：

• 因为你拥有开发者角色，你可以删除该小部件。

而不是：

• 既然你拥有开发者角色，你可以删除该小部件。

slashes

不要使用 and/or，而是使用 or 或重写句子。此规则也适用于其他斜杠，如 follow/unfollow。某些例外情况（如 CI/CD）允许。

slave

不要使用 slave。另一个选择是 secondary。（Vale 规则：InclusiveLanguage.yml）

storages

在以下上下文中：

• Gitaly 中，存储是物理的，必须称为 storage。
• Gitaly Cluster（Praefect）中，存储可以是：
  • 虚拟的，必须称为 virtual storage。
  • 物理的，必须称为 physical storage。

Gitaly 存储具有物理路径，虚拟存储具有虚拟路径。

subgroup

使用 subgroup（无连字符）代替 sub-group。 同时，避免使用子组的替代术语，如 child group 或 low-level group。（Vale 规则：SubstitutionWarning.yml）

subscription tier

不要混淆 subscription 或 subscription tier 与 license。 用户购买的是 subscription。该订阅有 tier。

描述层级时：

Suggested Reviewers

使用标题大小写表示 Suggested Reviewers。

Suggested Reviewers 应始终使用复数形式，即使泛指时也需大写。

示例：

• Suggested Reviewers 可以为你的合并请求推荐审阅者。（此短语描述功能。）
• 输入时，会显示 Suggested Reviewers。（此短语是泛指但仍使用大写字母。）

tab

使用粗体表示标签页名称。例如：

• Pipelines 标签页
• Overview 标签页

that

描述名词时不要使用 that。例如：

使用：

• 你保存的文件……

而不是：

• 你保存的 that 文件……

参见 this, these, that, those。

terminal

使用小写表示 terminal。例如：

• 打开终端。
• 从终端运行 docker login 命令。

## Terraform 模块注册表

对 GitLab Terraform 模块注册表使用首字母大写，但在谈论非特定模块时使用小写的 `m`。例如：

- 你可以将 Terraform 模块发布到项目的 Terraform 模块注册表中。

## 测试生成

对 **测试生成（Test Generation）** 使用首字母大写。

在页面首次提及处，使用 **GitLab Duo 测试生成（GitLab Duo Test Generation）**。
此后，单独使用 **测试生成（Test Generation）**。

## 文本框

当指代 UI 元素时，使用 **文本框（text box）** 而不是 **字段（field）** 或 **框（box）**。

## 存在、有

尽量避免使用 **存在（there is）** 和 **有（there are）**。这些短语会隐藏主语。

使用：

- 桶有洞。

而非：

- 桶里有很多洞。

## 他们

除非指代特定的人，否则避免使用性别特定的代词。使用单数的 [他们（they）](https://developers.google.com/style/pronouns#gender-neutral-pronouns) 作为中性代词。

## 这、这些、那、那些

这些词后始终跟随名词。例如：

- 使用：**此设置** 提升了性能。
- 而非：**这** 提升了性能。

- 使用：**这些裤子** 是最好的。
- 而非：**这些** 是最好的。

- 使用：**那个机器人** 就是你找的那个。
- 而非：**那个** 就是你要找的。

- 使用：**那些设置** 必须配置。（或者更好的说法是 **配置那些设置**。）
- 而非：**那些** 需要被配置。

## 其中、……的

尽量避免使用 **其中（to which）** 和 **……的（of which）**，而是让介词悬于句子末尾。示例见 [介词（Prepositions）](_index.md#prepositions) 部分。

## 待办事项

使用小写并连字符形式 **to-do 项（to-do item）**。([Vale](../testing/vale.md) 规则：[`ToDo.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab_base/ToDo.yml))

## 待办事项列表

对 **待办事项列表（To-Do List）** 使用首字母大写。([Vale](../testing/vale.md) 规则：[`ToDo.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab_base/ToDo.yml))

## 开关

你 **打开（turn on）** 或 **关闭（turn off）** 一个开关。例如：

- 打开 **blah** 开关。

## 顶级群组

对 **顶级群组（top-level group）** 使用小写（连字符形式）。

不要使用 **根群组（root group）**。

## 双因素认证（2FA）

使用 [**2FA** 和 **双因素认证（two-factor authentication）**](#2fa-two-factor-authentication) 替代。

## 打开、关闭

使用 **打开（turn on）** 和 **关闭（turn off）** 而不是 **启用（enable）** 或 **禁用（disable）**。

详情参见 [微软风格指南](https://learn.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/t/turn-on-turn-off)。

另见 [启用（enable）](#enable) 和 [禁用（disable）](#disable)。

## 键入

当光标停留在输入位置时使用 **键入（type）**。例如，在搜索框中，你开始键入，搜索结果就会出现。你不需要点击离开搜索框。

例如：

- 要查看所有名为 Alex 的用户，键入 `Al`。
- 要查看文档团队的所有标签，键入 `doc`。
- 要查看快速操作列表，键入 `/`。

另见 [**输入（enter）**](#enter)。

## 终极版（Ultimate）

对订阅层级使用大写的 **Ultimate**。当你指代 **Ultimate** 时，需遵循 [订阅层级（subscription tier）](#subscription-tier) 的指导原则。

## 撤销

关于 **撤销（undo）** 的指导，请参阅 [微软风格指南](https://learn.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/u/undo)。

## 计量单位

数字与计量单位之间添加空格。例如，**128 GB**。([Vale](../testing/vale.md) 规则：[`Units.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab_base/Units.yml))

更多信息，请参阅 [微软风格指南](https://learn.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/term-collections/bits-bytes-terms)。

## 更新

使用 **更新（update）** 来安装软件的较新 **补丁（patch）** 版本，或记录 API 和程序化变更。

例如：

- 将 GitLab 从 14.9 升级到 14.9.1。
- 使用此端点更新用户权限。

不要在其他情况下使用 **更新（update）**。相反，使用 **[升级（upgrade）](#upgrade）** 或 **[编辑（edit）](#edit）**。

## 升级

使用 **升级（upgrade）** 用于：

- 选择更高的订阅层级（Premium 或 Ultimate）。
- 安装 GitLab 的较新 **主要（major）**（如 13.0）或 **次要（minor）**（如 13.2）版本。

例如：

- 升级到 GitLab Ultimate。
- 将 GitLab 从 14.0 升级到 14.1。
- 将 GitLab 从 14.0 升级到 15.0。

谨慎使用 “升级 GitLab” 这一表述而不附加其他文字。确保周围文字明确你是讨论产品版本还是订阅层级。

另见 [降级（downgrade）](#downgrade) 和 [回滚（roll back）](#roll-back)。

左上角，右上角

使用左上角和右上角来提供UI方向指引。 如果UI元素不在角落位置，使用左上方和右上方。

不要使用左上和右上。

更多信息请参见微软风格指南。

有用

不要使用有用。如果用户觉得流程没有价值，我们会失去他们的信任。（Vale规则：Simplicity.yml）

用户账户

你创建一个用户账户。该用户账户具有访问级别。 当你将用户账户添加到群组或项目时，该用户账户成为成员。

使用

大多数情况下避免使用使用。它会隐藏主语并使语句更难翻译。 使用通过使用、使用…的，或重写句子。

例如：

• 不用：使用存储的文件…

• 用：使用存储的文件…

• 不用：使用命令行更改目录。

• 用：通过使用命令行更改目录。更好的说法：要更改目录，请使用命令行。

利用

不要使用利用。改用使用。它更简洁，非母语使用者更容易理解。 （[Vale规则](../testing/vale.md）：SubstitutionWarning.yml）

版本，v

描述GitLab版本时，使用GitLab <版本号>。例如：

• 你必须拥有GitLab 16.0或更高版本。

描述其他软件时，使用该软件文档相同的格式。 例如：

• 在Kubernetes 1.4中，你可以…

注意字母v后的空格。在语义化版本控制中，v后没有空格。例如：

• v1.2.3

经由

不要使用拉丁缩写。改用通过、借助或通过使用。（[Vale规则](../testing/vale.md）：LatinTerms.yml）

VS Code用户界面

描述VS Code和Web IDE的用户界面时，遵循VS Code文档的使用方法和大小写规范，例如Command Palette和Primary Side Bar。

漏洞解释

对Vulnerability Explanation使用标题大小写。

在页面首次提及处，使用GitLab Duo 漏洞解释。 此后，单独使用漏洞解释。

漏洞解决

对Vulnerability Resolution使用标题大小写。

在页面首次提及处，使用GitLab Duo 漏洞解决。 此后，单独使用漏洞解决。

我们

尽量避免使用我们，转而关注用户如何在GitLab中完成某事。

使用：

• 当你有想要组织的工作时，请使用小部件。

而非：

• 我们为你创建了一个添加小部件的功能。

Web IDE用户界面

参见VS Code用户界面。

临时方案

当故障排除解决方案是临时修复时，使用workaround。 临时方案通常是即时修复，可能仍存在问题。 例如：

• 临时方案是将模板暂时固定到已弃用的版本。

另见解决。

当…时候

仅当指代时间上的同时发生时使用while。例如： 在进程运行期间保持窗口打开。

不要将while用于比较。例如，使用：

• 任务1可以快速运行。然而，任务2更精确。

而非：

• 虽然任务1可以快速运行，但任务2更精确。

更多信息请参见微软风格指南。

Whilst

不要使用whilst。改用while。While更简洁，非母语使用者更容易理解。

白名单

不要使用whitelist。另一个选项是allowlist。（[Vale规则](../testing/vale.md）：InclusiveLanguage.yml）

在…内

尽可能不要使用within。改用in，除非你指的是时间段、限制或边界。例如：

• 升级发生在四小时的维护窗口内。
• Wi-Fi信号在30英尺半径范围内可访问。

（[Vale规则](../testing/vale.md）：SubstitutionWarning.yml）

yet

讨论产品或其功能时，请勿使用 yet。文档描述的是当前的产品状态。

有时在编写任务时可能会想使用 yet。如果使用了 yet，请确保周围的短语使用现在时、主动语态书写。

查看关于如何撰写未来功能的指导。

you, your, yours

请使用 you 代替 the user、the administrator 或 the customer。文档应直接面向用户讲话，无论该用户是安装产品的人、配置产品的人、管理产品的人还是使用产品的人。

使用：

• 你可以配置一个流水线。
• 你可以重置用户的密码。（针对管理员的内容）

而非：

• 用户可以配置一个流水线。
• 管理员可以重置用户的密码。

you can

尽可能用主动动词开头，而不是 you can。

例如：

• 使用代码审查分析来查看合并请求的数据。
• 创建一个看板来组织团队任务。
• 配置变量以限制向仓库推送。
• 添加你拥有的外部账户链接，如 Discord 和 Twitter。

对于可选操作，请使用 you can。例如：

• 使用代码审查分析来查看每个合并请求的指标。你也可以使用 API。
• 输入名称和值对。你可以为每个流式目标添加最多 20 对。