Back to Details

inclusive-language

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Inclusive Language

包容性语言

Overview

概述

Use respectful, accessible language in all code and documentation.
Core principle: Words matter. Use inclusive terminology.
This applies to: Code, comments, documentation, commit messages, branch names, and all text.
在所有代码和文档中使用尊重、易访问的语言。
核心原则： 语言至关重要。请使用包容性术语。
适用范围： 代码、注释、文档、提交信息、分支名称及所有文本内容。

Terminology Guide

术语指南

Branch Names

分支名称

Instead ofUse
mastermain
slavereplica, secondary, follower
bash
undefined
替代推荐使用
mastermain
slavereplica、secondary、follower
bash
undefined

Correct

正确示例

git checkout main git push origin main
git checkout main git push origin main

Repository default branch should be 'main'

仓库默认分支应设为'main'

undefined
undefined

Access Control

访问控制

Instead ofUse
whitelistallowlist, permitlist
blacklistdenylist, blocklist
typescript
// Correct
const allowlist = ['admin@example.com', 'user@example.com'];
const denylist = ['spam@example.com'];

function isAllowed(email: string): boolean {
  return allowlist.includes(email) && !denylist.includes(email);
}
替代推荐使用
whitelistallowlist、permitlist
blacklistdenylist、blocklist
typescript
// 正确示例
const allowlist = ['admin@example.com', 'user@example.com'];
const denylist = ['spam@example.com'];

function isAllowed(email: string): boolean {
  return allowlist.includes(email) && !denylist.includes(email);
}

Primary/Secondary

主/从替代术语

Instead ofUse
master/slaveprimary/replica, primary/secondary, leader/follower
master (device)primary, controller, host
slave (device)secondary, peripheral, client
typescript
// Correct
interface DatabaseConfig {
  primary: ConnectionString;
  replicas: ConnectionString[];
}

class ReplicationManager {
  private leader: Node;
  private followers: Node[];
}
替代推荐使用
master/slaveprimary/replica、primary/secondary、leader/follower
master（设备）primary、controller、host
slave（设备）secondary、peripheral、client
typescript
// 正确示例
interface DatabaseConfig {
  primary: ConnectionString;
  replicas: ConnectionString[];
}

class ReplicationManager {
  private leader: Node;
  private followers: Node[];
}

Gendered Terms

性别相关术语

Instead ofUse
man hoursperson hours, work hours
manpowerworkforce, staffing
mankindhumanity, people
guyseveryone, folks, team
he/she (generic)they
typescript
// Correct
/**
 * When a user logs in, they receive a session token.
 * The user can then use their token to access resources.
 */
替代推荐使用
man hoursperson hours、work hours
manpowerworkforce、staffing
mankindhumanity、people
guyseveryone、folks、team
he/she（泛指）they
typescript
// 正确示例
/**
 * 当用户登录后，他们会收到一个会话令牌。
 * 随后用户可使用该令牌访问资源。
 */

Ability-Related

能力相关术语

Instead ofUse
sanity checkvalidity check, confidence check
crazy/insaneunexpected, surprising
blind (as negative)unaware, unnoticed
crippledisable, limit
dumbsilent, without output
typescript
// Correct
function validateInput(data: unknown): boolean {
  // Perform validity check on input data
}

// Instead of "sanity check"
function confidenceCheck(result: Result): boolean {
  // Verify result is within expected bounds
}
替代推荐使用
sanity checkvalidity check、confidence check
crazy/insaneunexpected、surprising
blind（含负面含义）unaware、unnoticed
crippledisable、limit
dumbsilent、without output
typescript
// 正确示例
function validateInput(data: unknown): boolean {
  // 对输入数据执行有效性检查
}

// 替代"sanity check"
function confidenceCheck(result: Result): boolean {
  // 验证结果是否在预期范围内
}

Violence-Related

暴力相关术语

Instead ofUse
killstop, terminate, end
abortcancel, stop
hitaccess, call, reach
executerun, perform
nukedelete, remove, clear
typescript
// Correct
function terminateProcess(pid: number): void { }
function stopServer(): void { }
function cancelRequest(id: string): void { }

// Acceptable (industry standard)
function executeQuery(sql: string): Result { }
替代推荐使用
killstop、terminate、end
abortcancel、stop
hitaccess、call、reach
executerun、perform
nukedelete、remove、clear
typescript
// 正确示例
function terminateProcess(pid: number): void { }
function stopServer(): void { }
function cancelRequest(id: string): void { }

// 可接受（行业标准）
function executeQuery(sql: string): Result { }

Other Terms

其他术语

Instead ofUse
dummyplaceholder, sample
nativebuilt-in, core
first-classbuilt-in, fully-supported
grandfather/legacyestablished, existing
grandfathered inexempted, pre-existing
替代推荐使用
dummyplaceholder、sample
nativebuilt-in、core
first-classbuilt-in、fully-supported
grandfather/legacyestablished、existing
grandfathered inexempted、pre-existing

Examples in Context

上下文示例

Configuration

配置

typescript
// Correct
interface FeatureFlags {
  allowlist: string[];
  denylist: string[];
}

const replicationConfig = {
  primary: 'db-primary.example.com',
  replicas: [
    'db-replica-1.example.com',
    'db-replica-2.example.com',
  ],
};
typescript
// 正确示例
interface FeatureFlags {
  allowlist: string[];
  denylist: string[];
}

const replicationConfig = {
  primary: 'db-primary.example.com',
  replicas: [
    'db-replica-1.example.com',
    'db-replica-2.example.com',
  ],
};

Documentation

文档

markdown
<!-- Correct -->
markdown
<!-- 正确示例 -->

Getting Started

快速开始

When a user creates an account, they will receive a confirmation email. They can then set up their profile using their preferred settings.
当用户创建账户后，他们会收到一封确认邮件。 随后可使用偏好设置配置个人资料。

Access Control

访问控制

Use the allowlist to specify approved domains. Use the denylist to block specific addresses.
undefined
使用allowlist指定已批准的域名。 使用denylist阻止特定地址。
undefined

Comments

注释

typescript
// Correct
// Validity check: ensure the input meets expected format
if (!isValidFormat(input)) {
  throw new ValidationError('Input format is invalid');
}

// Confidence check: verify result is within expected bounds
if (result > MAX_EXPECTED || result < MIN_EXPECTED) {
  logger.warn('Result outside expected range');
}
typescript
// 正确示例
// 有效性检查：确保输入符合预期格式
if (!isValidFormat(input)) {
  throw new ValidationError('输入格式无效');
}

// 可信度检查：验证结果是否在预期范围内
if (result > MAX_EXPECTED || result < MIN_EXPECTED) {
  logger.warn('结果超出预期范围');
}

Error Messages

错误信息

typescript
// Correct
throw new Error('Email address is on the denylist');
throw new Error('Origin not in allowlist');
throw new Error('Request terminated due to timeout');
typescript
// 正确示例
throw new Error('该邮箱地址在denylist中');
throw new Error('来源不在allowlist中');
throw new Error('请求因超时终止');

Applying to Existing Code

应用到现有代码

When modifying existing code with non-inclusive terms:
当修改包含非包容性术语的现有代码时：

Small Scope (Same File)

小范围（单个文件）

If you're modifying a function that uses non-inclusive language:
  1. Rename the term as part of your change
  2. Update related documentation
  3. Note in commit message: "Renamed to inclusive terminology"
如果你正在修改使用非包容性语言的函数：
  1. 在本次修改中重命名该术语
  2. 更新相关文档
  3. 在提交信息中注明："Renamed to inclusive terminology"（已重命名为包容性术语）

Large Scope (Multiple Files)

大范围（多个文件）

If renaming would touch many files:
  1. Create a separate issue for the terminology update
  2. Complete current work with existing terms
  3. Schedule terminology update as future work
如果重命名会涉及多个文件：
  1. 为术语更新创建单独的议题
  2. 先使用现有术语完成当前工作
  3. 将术语更新安排为后续工作

API/Public Interface

API/公共接口

If the term is in a public API:
  1. Document the plan for deprecation
  2. Add deprecated alias with new term
  3. Migrate users over time
  4. Remove deprecated term in major version
typescript
// Transition approach
/** @deprecated Use allowlist instead */
export const whitelist = allowlist;

export const allowlist: string[] = [];
如果术语存在于公共API中：
  1. 记录弃用计划
  2. 添加新术语的同时保留已弃用的别名
  3. 逐步引导用户迁移
  4. 在大版本更新中移除已弃用的术语
typescript
// 过渡方案
/** @deprecated 请使用allowlist替代 */
export const whitelist = allowlist;

export const allowlist: string[] = [];

Commit Messages and Branch Names

提交信息与分支名称

bash
undefined
bash
undefined

Branch names

分支名称

feature/issue-123-add-denylist-support # Correct fix/issue-456-update-replica-config # Correct
feature/issue-123-add-denylist-support # 正确示例 fix/issue-456-update-replica-config # 正确示例

Commit messages

提交信息

"Add email denylist validation" # Correct "Update replica failover logic" # Correct
undefined
"Add email denylist validation" # 正确示例 "Update replica failover logic" # 正确示例
undefined

Checklist

检查清单

When writing or reviewing code:
  • No master/slave terminology
  • No whitelist/blacklist terminology
  • No gendered language for generic users
  • No ability-related negative terms
  • Documentation uses inclusive language
  • Variable/function names are inclusive
  • Error messages are inclusive
  • Comments are inclusive
编写或评审代码时，请确认：
  • 未使用master/slave术语
  • 未使用whitelist/blacklist术语
  • 未使用性别相关术语泛指用户
  • 未使用含负面含义的能力相关术语
  • 文档使用了包容性语言
  • 变量/函数名称具有包容性
  • 错误信息使用了包容性语言
  • 注释使用了包容性语言

Resources

参考资源

Integration

集成说明

This skill is applied by:
  • issue-driven-development
    - Step 7
  • comprehensive-review
    - Style criterion
This skill ensures:
  • Welcoming codebase
  • Professional standards
  • Accessibility for all contributors
本技能适用于：
  • issue-driven-development
    - 第7步
  • comprehensive-review
    - 风格标准
本技能可确保：
  • 友好的代码库
  • 专业标准
  • 对所有贡献者的包容性