本页目录

本页目录

语言政策

分别确定以下三种语言,切勿从其中一种推断另一种:

  1. 对话语言
  2. 源代码语言
  3. 产品 / 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 文案应优先满足以下要求:

  1. 符合目标语言的规范用法
  2. 语法正确
  3. 含义清晰
  4. 正式程度得当
  5. 易于理解
  6. 易于使用
  7. 与产品其余部分保持一致

UI 文案应当专业、自然,不要带有直译或机器翻译的腔调。

重要术语或语气拿不准时,询问用户,不要自行发明惯例。