Skip to content

翻译须知

Jump to bottom
Jinjiang edited this page Dec 6, 2024 · 32 revisions

1. 术语翻译约定

迁移自 vuejs/docs-next-zh-cn repo

英文 建议翻译
attribute 不翻译
breaking “非兼容”或“不兼容” vuejs/docs-next-zh-cn#62
build (n.) 构建版本 vuejs/docs-next-zh-cn#628
build (v.) 构建
caveats 注意事项 vuejs/docs-next-zh-cn#793
class JS 中翻译成“类”，CSS 中不翻译 #149
computed 计算属性
computed property 计算属性
convention 约定
declarative 声明式
directive 指令
drilling 逐级透传 vuejs/docs-next-zh-cn#613
effect scope effect 作用域 vuejs/docs-next-zh-cn#657
emit (a value) 抛出
emit/fire/trigger (an event) 触发
feature/functionality 功能
fetch 获取 #403
first-class 一等公民 #487
getter 不翻译
guard 守卫
handler 处理函数
hoist/hoisting 提升/变量提升 #748
hook 钩子
hydrate 激活 vuejs/docs-next-zh-cn#786
immutable 不可变
imperative 命令式
in-DOM DOM 内 vuejs/docs-next-zh-cn#464
local 如果和 global 对应用“局部”，和 remote 对应用“本地” #748
listen/listener 监听/监听器
mixin 不翻译 vuejs/docs-next-zh-cn#350、vuejs/docs-next-zh-cn#382
mutable 可变
mutate/mutation 变更
normalize (HTML code, ...) 规范化
observe/observer 侦听/侦听器
parse 解析
playground 演练场
prop 不翻译
property 指代 DOM property 强调和 attribute 的区分时不翻译，其他情况下翻译为“属性” #487
queue (v.) 把……加入队列
render 渲染 #487
reactive 响应式 vuejs/docs-next-zh-cn#53
reactivity 响应性 vuejs/docs-next-zh-cn#53
ref 不翻译
selector 选择器
setter 不翻译
shadow (DOM/root) 影子 (影子 DOM/影子根) #1016
side effect 副作用
slot 插槽 vuejs/docs-next-zh-cn#429
slot outlet 出口 #487
standardize 标准化
stringify 字符串化
strong identity comparisons 严格比对
teleport 不翻译 vuejs/docs-next-zh-cn#217
truthy, falsy, truthiness 不翻译，保留精准的英文，但要加 MDN 的解释作为译注
type (v.) 标注类型 #59
watch/watcher 侦听/侦听器
workaround (n.) 变通办法
workaround (v.) 绕过
wrap/unwrap 包装/解包 #133
you 你 (而不用“您”)
hydration 激活 #2
dist file 构建文件
template ref 模版引用
nullable 可为 null 的 #958

1.1 特指 API 名词或产品/品牌名称

保留英文且保留大小写规则。现将常见的争议词汇整理如下：

  • “CSS Modules”属于产品/品牌名称，建议保留英文及其复数形式。在原文用自然语言“a CSS module”描述一个具体的模块时，译为“一个 CSS 模块”。
  • “effect”一词在特指“effect scope”的时候保留英文，即“effect 作用域”，其它一般化自然语言描述的情况下译为“作用”，例如“side effect”译为副作用 (vuejs/docs-next-zh-cn#657)。
  • “proxy”一词只有大写特指 ES6 Proxy 对象时保留英文“Proxy”，其它一般化自然语言描述的情况译为“代理” (vuejs/docs-next-zh-cn#404、vuejs/docs-next-zh-cn#217、vuejs/docs-next-zh-cn#230)。
  • “tree-shaking”及相关语法变换：保留英文，且动词时用“tree-shake”，名词时用“tree-shaking” (vuejs/docs-next-zh-cn#548)。
  • “webpack”、“npm”等产品/品牌名称本身是刻意开头小写的，所以即便是作为自然语言描述的第一个词，也应该保留开头字母小写 (vuejs/docs-next-zh-cn#488)。
  • “web component(s)”作为术语保留英文 #748

1.2 被保留的英文

  • attribute
  • getter
  • mixin
  • prop(s)
  • ref
  • setter
  • teleport

1.3 被保留的英文单复数问题

中文翻译中夹带的英文一律以单数形式呈现。如：

  • children -> child
  • properties -> property

部分约定俗成的特例：

  • props 除非语境下特指单一的 prop，否则统一用复数 props #487
  • 透传 Attributes 同理

1.4 中文术语约定

中文 约定的写法
应用程序 应用
开发人员 开发者
其他/其它 统一到“其他” #24
举个例子 举例来说 #487

1.5 关于 MDN 中可查阅的前端术语

  1. 原则上，我们将前端专业术语的译法约定为优先参考 MDN 中文译法，如果没有中文译法则保留英文。
  2. 原文中出现的 MDN 文档链接，如果在 MDN 存在对应的中文翻译，我们建议转换为 MDN 的中文翻译链接。但鉴于 MDN 的中文文档也并不齐全，所以：
    1. 仅当有 MDN 中文链接时候，译者可手动变更为 MDN 中文链接
    2. 否则保持 MDN 英文原链接

讨论记录：#25 vuejs/docs-next-zh-cn#389

1.6 关于原文中的英文缩写

  1. 如果是大众已经熟悉的平时中文交流会选用的英文缩写，且不是 Vue 本身创造出来的词汇而是行业常用的基础词汇，选择保留。如 HTML、DOM 等。
  2. Vue 本身创造出来的词汇，选择用中文翻译，且可选地在第一次出现的时候或其他较为明显的地方提及英文缩写。如 SFC、VOA、VCA 等。

讨论记录：#940

2. 文本格式

2.1 译注写法

  1. 在原文需要加译者注的位置添加角标：
... <sup>[[1]](#footnote-1)</sup> ... <sup>[[2]](#footnote-2)</sup> ...
  1. 在文章最末尾加入译者注的内容，格式如下：
<small>
__译者注__
<a id="footnote-1"></a>[1] ...
<a id="footnote-2"></a>[2] ...
<a id="footnote-3"></a>[3] ...
</small>

2.2 标点符号

  • 逗号、句号、分号、冒号、叹号、问号、顿号，统一使用全角字符：，。；：！？、
  • 引号统一使用全角字符：“” 和 ‘’
  • 括号统一使用半角字符：()
  • 破折号使用：——
  • 省略号使用：……
  • 间隔号使用：·
  • 书名号使用：《》 和 〈〉
  • 分隔号使用：/
  • 非注释部分的代码除外，保留英文标点符号。

2.3 内联代码或代码关键字

  • 务必用反引号，即英文输入法下按键盘上 Tab 键上方的那个键输出的那个字符，括起来。
  • 包括代码注释中出现代码或代码关键字时，也要括起来。

2.4 空格的使用

首先，无需翻译或因特殊原因保留的纯英文段落遵循原版的用法；其次，中英文及其标点符号之间的空格使用约定部分参考自 W3C 中文排版需求，部分根据浏览器实际的渲染情况和已知问题进行了调整。

  • 两个英文单词之间要有一个空格。如：Hello World
  • 中文和英文单词之间要有一个空格。如：中文 English 中文
  • 全角标点符号两边没有空格。如：中文，中文。“中文”中文。
  • 半角标点符号，目前只有括号，其内侧没有空格，外侧如果是中文或英文，则有一个空格，如果是其他标点符号则没有空格。如：中文 (中文) 中文，(中文) 中文
  • 注意结合加粗、斜体、链接等 Markdown 标记时，应该保证空格的用法和上述规则希望最终呈现的效果相符，且紧挨着 Markdown 标记的空格应该永远出现在其外部。如： 
    遵守 **JavaScript 编码规范**非常重要
遵守 [JavaScript 编码规范](#foo)非常重要
更多信息详见*中文 MDN* 的介绍页面。
更多信息详见[中文 MDN](#bar) 的介绍页面。

2.5 关于加粗和斜体格式的约定

根据 GitHub Flavored Markdown Spec，用成对的星号或下划线都可以用来代表加粗或斜体，但是使用下划线的时候存在更多的特殊条件限制，例如：

5*6*78 → <p>5<em>6</em>78</p>

https://github.github.com/gfm/#example-346

5_6_78 → <p>5_6_78</p>

https://github.github.com/gfm/#example-351

via: https://github.com/vuejs/cn.vuejs.org/pull/727#issuecomment-385399073

经过讨论，考虑到 GFM 的规范以及中文的特殊情况，决定

  1. 中文翻译统一使用星号来标注加粗和斜体，而不是使用下划线，同时尊重英文版自身的用法，不对其做任何反向更新。

  2. 仍然不能正确渲染的地方，可以考虑使用 <strong> 或 <em> 等 HTML 标记替代 Markdown 标记。

  3. 早期翻译的文档中存在一些通过调整 Markdown 标记两侧标点符号的做法来解决渲染不正确问题的做法，可以酌情使用。如：

3. 关于文档中的代码片段

  • 原则上代码片段因为逻辑性较强且通常比较易懂，所以我们选择不翻译
  • 代码片段中的注释我们通常会选择翻译，因为并不影响代码逻辑且通常是自然语言描述
  • 代码注释中如果是为了体现代码运行结果或日志之类的内容，我们同样会保留英文原版，以和代码逻辑保持一致

4. 关于文档中的图片

文档中的所有图片在原文中都以注释形式附有 figma 链接，详情可通过该搜索页面查阅：github.com/search?q=repo%3Avuejs%2Fdocs%20figma&type=code

如果想要翻译文档中的图片，请遵循以下流程：

  1. 基于原文注释的 figma 链接自己 fork 一份设计稿，并给该文件添加 -(zh-CN) 后缀 (fork 后的默认后缀是 -(Copy))
  2. 翻译图片中的文字，之后导出新的图片
  3. 在仓库中添加该图片，图片文件名添加 _zh-CN 的后缀，同时在中文翻译处以注释形式添加这份 fork 的 URL (此处同时保留英文和中文的 URL，英文第一个，中文第二个)，每个人在翻译时都可以随意 fork 自己的版本。

示例：https://github.com/vuejs-translations/docs-zh-cn/pull/858

相关讨论：https://github.com/vuejs-translations/docs-zh-cn/issues/643

5. 翻译建议整理

  1. 调整语序为中文习惯，例如：

So far we've only been binding to simple property keys in our templates. But Vue.js actually supports the full power of JavaScript expressions inside all data bindings.

可以译为“目前我们都是只通过模板语法绑定简单的 property 键值，但实际上，Vue.js 完全支持在所有的数据绑定中使用 JavaScript 表达式”。

  1. 省略部分在外语中仅用于完成句式的词语，例如：

When Vue is updating a list of elements rendered with v-for, by default it uses an "in-place patch" strategy. If the order of the data items has changed, instead of moving the DOM elements to match the order of the items, Vue will patch each element in-place and make sure it reflects what should be rendered at that particular index.

像to match the order of the items这样的短语可以在保证语义不变的条件下简化，译为“Vue 默认按照“就地更新”的策略来更新通过 v-for 渲染的元素列表。当数据项的顺序改变时，Vue 不会随之移动 DOM 元素的顺序，而是就地更新每个元素，确保它们在原本指定的索引位置上渲染”。

  1. 在句子之间补充类似“然而”、“并且”、“即使…也…”这样的关联词，使句子更加连贯，例如：

The mustache tag will be replaced with the value of the msg property from the corresponding component instance. It will also be updated whenever the msg property changes.

后半句可以译为“只要绑定的组件实例上 msg property 发生改变，插值处的内容就会随之更新”。

  1. 在尽可能地尊重原版内容的前提下，使读者理解起来更加容易。即，在修缮的同时，要保证译文所传达的内容（而非句式、语法等）是可信赖的。

(TODO: 示例)

  1. 由于 Vue 文档以 Markdown 书写，每一行成一个自然段。因此在 Markdown 文档中原则上应该保证中英文行号一一对应，以保证后续更新时位置不发生错乱。除非以下情况可以针对实际情况特殊讨论：

    1. 有单行的译者注
    2. 有本地化的调整，比如删掉一些国内无法访问或不推荐访问的 banner 之类的，或中文区特别的赞助商或赞助活动
    3. 代码注释的英文描述会因为超过 80 个字符而折行，翻译成中文之后行数有的时候会不一样

    #16

Clone this wiki locally