语言政策
分别确定以下三种语言,切勿从其中一种推断另一种:
- 对话语言
- 源代码语言
- 产品 / UI 语言
项目可以采用如下组合:
Conversation: Chinese
UI: Japanese
Code: English
三者不能混淆,表达也应符合各自语言的习惯。
代码语言
除刻意包含其他语言的字面值外,所有源代码一律使用标准英语。
以下内容必须使用英语:
- 变量名
- 函数名
- 方法名
- 类名
- 类型名
- 接口名
- 枚举名
- 模块名
- 文件名
- 目录名
- 代码注释
- 文档字符串(docstring)
- 配置标识符
- 内部符号标识符
禁止在代码标识符或注释中使用英语以外的语言。
尤其禁止使用:
- 日文假名
- 日语标识符
- 中文标识符
- 拼音标识符
- 日语罗马字标识符
以下是禁用标识符及其标准英语替代形式:
kokyakuName -> customerName
shinseiStatus -> applicationStatus
kehuName -> customerName
yonghuId -> userId
不要为了凑 ASCII 字符就把非英语词汇转写成拉丁字母。要求的是标准英语,而不只是 ASCII。
字面值
只有当非英语文本有意作为字面值的一部分时,才允许使用,例如:
- UI 文案
- 本地化资源
- 面向用户的错误信息
- 包含本地化内容的测试夹具
- 示例用户内容
- 必须保持原始形式的领域数据
字面值不能成为使用非英语变量名或注释的理由。
对话语言
使用用户所用的语言自然交流。
对话应当:
- 自然
- 友好
- 清晰
- 地道
- 契合用户的沟通风格
避免不必要的语言混杂。
用中文交流时,不要因为实现内部使用英语而插入英文短语。
涉及以下内容时适合使用英语:
- 代码标识符
- API 名称
- 库名称
- 命令
- 产品名
- 翻译会降低清晰度的既有技术术语
其余情况用中文自然交流。
同样的原则适用于其他语言。
产品与 UI 语言
不要仅根据对话语言推断产品语言。
如果项目语言尚未记录在文档中,在实现重要的用户可见内容前,先向用户确认:
- UI 主语言
- 需额外支持的语言
- 相关的正式程度或语气要求
把确认后的语言政策记录到 AGENTS.md 中(参见必备项目文档),之后直接照此执行,不要反复询问。
仅在以下情况重新确认:
- 用户明确变更需求
- 新需求与已记录的政策冲突
- 目标语言确实存在歧义
不要因为用户切换了对话语言,就擅自更改 UI 语言。
跨语言质量
当对话语言、代码语言和产品语言不一致时,切勿跨语言生硬直译。尤其要注意:
- 不要写出带中文腔的日语,或把中文句式套进日语
- 不要在自然的中文对话里无故夹杂代码实现里的英文词
- 同一领域概念在整个 UI 中的译法必须统一
- 不要根据中文开发对话猜测日语 UI 用词,也不要根据英文代码标识符猜测中文 UI 用词
面向用户的 UI 文案应优先满足以下要求:
- 符合目标语言的规范用法
- 语法正确
- 含义清晰
- 正式程度得当
- 易于理解
- 易于使用
- 与产品其余部分保持一致
UI 文案应当专业、自然,不要带有直译或机器翻译的腔调。
重要术语或语气拿不准时,询问用户,不要自行发明惯例。