Skip to content

翻译须知

Jump to bottom
Jinjiang edited this page Jun 7, 2022 · 29 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 指令
effect scope effect 作用域 vuejs/docs-next-zh-cn#657
emit (a value) 抛出
emit/fire/trigger (an event) 触发
feature/functionality 功能
fetch 获取 #403
getter 不翻译
guard 守卫
handler 处理函数
hook 钩子
hydrate 激活 vuejs/docs-next-zh-cn#786
immutable 不可变
imperative 命令式
in-Dom DOM 内 vuejs/docs-next-zh-cn#464
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 不翻译
queue (v.) 把……加入队列
reactive 响应式 vuejs/docs-next-zh-cn#53
reactivity 响应性 vuejs/docs-next-zh-cn#53
ref 不翻译
selector 选择器
setter 不翻译
side effect 副作用
slot 插槽 vuejs/docs-next-zh-cn#429
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

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)。

1.2 被保留的英文

  • attribute
  • getter
  • mixin
  • prop
  • property
  • ref
  • setter
  • teleport

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

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

  • children -> child
  • properties -> property
  • props -> prop

1.4 中文术语约定

中文 建议简写
应用程序 应用
开发人员 开发者
其他/其它 统一到“其他” #24

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

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

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

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 空格的使用

  • 英文单词和英文单词之间要有一个空格
  • 中文和英文单词之间要有一个空格
  • 英文单词和标点符号之间没有空格
  • 注意有加粗、斜体、链接等特殊情况时空格的准确运用 
    遵守 **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. 仍然不能正确渲染的地方，允许适当调整包含或不包含加粗或斜体部分两侧的标点符号。如 https://github.com/vuejs/composition-api-rfc/pull/30/files
  3. 仍然不能正确渲染的地方，使用 <strong> 或 <em> 标记。
  4. 在加粗段落，仅当影响 markdown 渲染情况下，将最后一个句号或逗号、冒号，迁移到 ** 右侧，否则保持原样。(讨论：vuejs/docs-next-zh-cn#49、vuejs/docs-next-zh-cn#78）
// 情况1：
 **相对胜于晦涩。**例如，一个 `<BlogPost>` 组件例子比 `<CurrencyExchangeSettings>` 更好。 // vuepress 无法渲染
（调整为：）
**相对胜于晦涩**。例如，一个 `<BlogPost>` 组件例子比 `<CurrencyExchangeSettings>` 更好。  // 迁移句号有加粗符号右侧

// 情况2：不影响渲染，保持原样
**你好，世界。** ==> **你好，世界。** (不影响渲染，保持原样)

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

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

4. 翻译建议整理

  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