翻译与排版说明

原书为 R Packages (2e)。

原书还在编撰中，暂时没有简体中文版，所以笔者先用自己早就遗忘的文学素养进行翻译，使用与原书相同的技术栈生成简体中文版的书籍。

翻译说明

将英文技术书籍翻译为中文是个痛苦的过程，难以避免地会遇到一些没有公认翻译方式的英文词汇，或者是有公认的中文翻译词汇，但该词过于口语化，或者不能很好地反映英文词汇的意思。这些英文词汇以及它们在书中的对应中文词汇将在下方列出，欢迎大家批评。

英文词汇 中文翻译 原因
package 软件包，程序包，包 r packages 是一组用来完成特定任务的程序，作为 R 的补充，符合 Software Package 的定义。“包”作为“软件包”的简称使用，在翻译中可能同时使用“软件包”和“包”两种称呼。
conscious uncoupling 有意识地解耦 这个词最初用于描述相对友好的离婚1，这里使用“有意识地”而非“相对友好的”以突出该决定是经过慎重考虑和精心设计的。
The Whole Game 整体流程 软件包构建的一个 toy example，这里采用意译。
The package within 软件包中的奥秘，包中奥秘 直译过来是“软件包的内部”，感觉过于平淡，使用更吸引人的翻译。
compelling 令人信服的 (intro?) 中 “One compelling reason …” 应该想要表达开发 R 包能带来一个明显的优势，即方便分享自己的代码，这一优势具有强烈的推动力和说服力，让你想要开发 R 包。2
section 章节，段落 本书中的 section 多用于指代层级低于 “chapter” 的文段，有的是小节，也有的是一个段落。
espouse 宣扬，倡导 直译为“支持”，从语句通顺的角度翻译为“宣扬”。
Vignette 主题文档 原意是“小插曲”、“短文”、“小品文”等，在 R 中 Vignette 是对整个包或包的某个功能主题进行概括性的介绍，这里突出其内容特性，强调其内容为功能“主题”，不强调其独立性和概括性。
Shunryu Suzuki 铃木俊隆 人名的中文翻译依据是 Wikipedia
toy package 示例软件包 直译过来是“玩具一般的软件包”，表示其各部分相比于真实软件包来说都较为简单，但包含了真实软件包的必要的部分，用于作为一个实例展示开发流程。
commit history 提交历史 GitHub 或 Git 中列出的 commit 历史。
pane, tab 窗格，选项卡 窗格是对应用程序窗口的一个分割，而选项卡是在窗格中展示的，可以切换不同的选项卡，窗格中将会展示对应的内容。
pull, push 拉取，推送 Git 远程仓库操作的常用翻译。
behind-the-scenes files 临时文件 直译是“幕后文件”，通常指的是一些程序在运行时自动生成的文件，这些文件通常不需要用户干预或直接操作，而是在程序或工具的运行过程中被使用或调用，并且没有用处后会被程序自动删除，因此翻译为更通俗的“临时文件”。
helper; helper function 辅助函数 所谓的“helper”是从函数和包的功能上进行描述的，它多指 devtools 包中的函数，可以辅助使用者进行软件包开发等工作。
expose 提供 我并不是很满意这个翻译。expose 是指 devtools 提供了来自构成它的其他软件包的函数，类似于“暴露接口”，但“暴露”一词有偏向被动、被揭示的意思，此处是主动提供。
qualified call 限定调用 在 R 中是形如 pkg::foo() 的形式，指不附加包而是调用函数时添加限定符 pkg::，指查找路径时将查找范围限定在 pkg 的命名空间中。
the whole game 整个流程 这是第二章节的标题，该章节以一个 toy package 为例，展示了开发一个软件包的整个流程。
toy package 示例软件包 直译过来是“玩具一般的软件包”，表示其各部分相比于真实软件包来说都较为简单，但包含了真实软件包的必要的部分，用于作为一个实例展示开发流程。
public face 公开接口 这里指软件包的用户界面，即用户可以直接使用的函数和数据集。
setup 配置 这里主要指软件包开发的环境配置和初始化。
helper (function) 辅助函数 所谓的“helper”是从函数和包的功能方面进行描述的，多指 devtools 包中的函数，可以辅助使用者进行软件包开发等工作。
home directory 主目录 用户的主目录，Linux 中通常是 ~ 即 /home/<user_name>。
instance 程序界面；实例 这里指软件启动的一个实例，对于 RStudio 等大部分软件来说就是一个新的界面。
pane 窗格 窗格是对应用程序窗口的一个分割。
tab 选项卡 选项卡是在窗格中展示的，可以切换不同的选项卡，窗格中将会展示对应的内容。
source package 源码包 指以源代码形式组织的软件包，通常是一个压缩文件，包含了软件包的所有源代码和元数据。
base R base R 指 R 语言的基础部分，有时也指 R 语言基础部分的编码风格，是相对于以 tidyverse 为代表的任何扩展包来说的。
morally 从逻辑上讲 这个词原意为“按照道义上的”，其翻译依赖于上下文语境，在编程领域可能更倾向于翻译为“从逻辑上讲”。
unlist 列表展开 这里指将列表展开为向量。
attach (library) 载入（包） 这里指载入包，使其可用。实际执行的是将包的路径“附加”到查找路径中。
demo 演示示例 这里指软件包中的演示示例，通常是一个 R 脚本，用于展示软件包的功能。
diff (in git) 版本差异；文件差异 可以参考 git 中的 diff 命令，用于比较两个版本或两个文件的差异。
pre-commit hook 预提交钩子 这里指 git 中的 pre-commit hook，是在执行 commit 命令前执行的脚本，可以用于在 commit 前执行一些操作，例如检查代码风格、运行测试等。
live code 可实时运行的代码 主要指 R Markdown 或其它任何形式的文档中，在生成文档时需要实时执行的代码。
file shuffling 文件移动和重新组织操作 这里指对文件进行移动、重命名、删除等操作，就像“洗牌”一样。
landing page 落地页 在网络营销和网站设计领域，landing page 是指用户通过点击广告或搜索结果等途径首次访问的网页。这里指软件包的主页，通常是软件包的 CRAN 或 GitHub 页面。
release 正式发布版本 这里指软件在平台上正式发布的版本。
Bundled package 归档包 直译为“捆绑包”，但这里指软件包所有文件都被 tar 打包压缩为一个 .tar.gz 文件。由于“捆绑”一词具有歧义，且不是专业的计算机术语，因此这里借用 tar 和 source tarball 的含义， 翻译为“归档包”，表示它是一个包含了软件包的所有源代码和元数据的压缩文件，作为一个版本的归档压缩包。3
compilation artefacts 编译产物 这里指编译过程中产生的文件，例如编译后的二进制文件、编译日志等。
anchoring (regex) 定位锚点 这里指标明正则表达式的定位锚点，用于在搜索文本时将模式限制在字符串的特定位置，例如 ^ 和 $。
escaping (regex) 转义 这里指正则表达式中的转义，用于将特殊字符转义为普通字符，例如 \.。

排版说明

由于书中不可避免地会同时出现中文和英文，因此原书的排版并不完全适用于中文翻译版。为了在尊重原书的基础上使页面变得美观，约定如下排版要求：

  1. 英文单词、标点符号和数字各具有 1 个前导空格和 1 个后导空格。例如：“软件包的名称是 bookdown 吗。”。
    • 英文单词、标点和数字的一侧为标点符号时，该侧无空格。例如：“使用 Leading and Trailing Spaces。”。
  2. 需要展示并链接 URL 时，将其放入尖括号内 <>。
  3. 小括号内的文本包含中文时，使用中文小括号 （）；如果全是英文文本，则使用英文小括号 ()，并各具有 1 个前导和后导空格。
  4. 书中某些操作中带有选项、菜单等名称，在实际操作时不具有中文翻译，此时列出该单词的中文翻译，后跟括号，括号内展示原英文单词。中文翻译便于读者查询相关资料，原英文单词便于按图索骥地进行操作。

翻译进度

常言道，人生未填之坑十之八九。笔者学业繁忙，只能利用空闲时间翻译本书。因此在这里记录一下翻译进度，欢迎加入本项目提交 Pull Request。

符号说明：

  • ✅：已完成
  • ⚙️：进行中
  • 📄：计划中
章节 是否翻译 是否润色
welcome ✅ ✅
Preface ✅ ✅
Introduction ✅ ⚙️
The Whole Game ✅ ⚙️
System setup ✅ ⚙️
Package structure and state ⚙️
Fundamental development workflows
The package within
R Code
Data
Other components
DESCRIPTION
Dependencies: Mindset and Background
Dependencies: In Practice
Licensing
Testing basics
Designing your test suite
Advanced testing techniques
Function documentation
Vignettes
Other markdown files
Website
Software development practices
Lifecycle
Releasing to CRAN
References
Appendix A R CND check

  1. 见 https://en.wikipedia.org/wiki/Conscious_uncoupling↩︎

  2. 译者注：需要再想清楚作者想表达的意思，然后润色↩︎

  3. 译者注：“归档”一词在中国大陆的用语习惯中较少使用，但考虑 tar 的原意，确实有“为一个版本创建只读快照”的含义，和这里的 R 包相符。↩︎