开发中文 API 的一些策略
注:本文仅基于个人在其他英文编程语言中实现中文 API 的有限实践和见闻,对易语言等等中文编程语言的生态不甚了解,各种疏漏请指正。
如果要现在的我,选择一个英文 API 进行中文化,或者针对一种功能开发新的中文 API。下面是几方面的考虑。由于编程语言和 API 的紧密关系,设计中文编程语言时也可参考。
成文仓促,权当个人阶段小结。
一、需求
1.1 从自己的需求出发
这里引用 Ruby 之父对编程语言设计者的建议,这里也完全适用:
自己想用就足够了
对于“这门语言是做什么的”和“目标用户是谁”的问题,我觉得有必要做一下补充。
作为资深的编程语言迷,我学习了很多编程语言。在 Ruby 成名之后,我与很多语言设计者也都进行过交流,比如 C++ 的设计者本贾尼·斯特劳斯特卢普(Bjarne Stroustrup)、Perl 的设计者拉里·沃尔(Larry Wall)、Python 的设计者吉多·范罗苏姆(Guido van Rossum)和 PHP 的设计者拉斯马斯·勒德尔夫(Rasmus Lerdorf)等。从和他们的交流中我总结出一点,那就是除了设计者本人以自用为目的设计的语言以外,其余的语言大多没有流行起来。
如果连自己都不打算用,在设计时就考虑不到细节,也无法保持激情去将自己设计的语言培养成人气语言。不少语言都是经过十年以上的时间才变得有人气,因此,要想创造一门人气语言,考虑细节和保持激情不可或缺。也就是说,人气语言的目标用户首先是设计者本人,然后才是拥有相似特质的用户。而“这门语言是做什么的”则取决于设计者本人想做什么。
选择汉化开发者自己使用过的库,是在日常工作中常用的库更好。深度使用才更理解用法和语义,对领域术语会更了解(比如大疆机甲大师教育机器人Python API中文化之三:底盘灯效,也更能找到最恰当的中文命名。尤其是,英文命名的选词用语有时并不符合中文习惯,直译过来会生硬(比如中英文代码对比系列之Java一例末尾),这时对 API 的理解越深就越可以接近信达雅的目标。
1.2 先领域后通用
通用库意味着很多计算机专用术语需要自行翻译,有些一时难以找到得到业界共识的中文对应词;有些词汇可能在不同 API 的语义不尽相同(详见此讨论帖)。还有英文缩写如 char,已有了约定俗成的含义。
专业库相对更能扬长避短,更多时候已经有完备和形成共识的领域相关中文术语可以沿用于API命名。用户的学习成本会更低。越是接近领域业务的库,一般业务相关的词汇在 API 命名中所占比例越大,编程语言通用的计算机术语比例就越小。
这里也可以举大疆机甲大师的例子。另如游戏开发者就很适合选择游戏领域入手。这也符合 1.1 的原则。
用户数量方面,领域库虽然有时用户较少,但社区够大(与库的维护工作量成比例)就行,最好有较活跃的交流渠道,以便推广和搜集反馈。
1.3 针对本地用户
比如汉字简繁转换库,或者中文自然语言处理方面的库,或者有特有中文术语的行业所用库。
总的来说,中文 API 的主要用户群必然以母语为中文的开发者为主。那么越是中文开发者所特别需要的库,将 API 中文化的理由就越充分。
二、设计
2.1 文档中文化的必要性
常有人在看到中文命名的例程或者 API时说,”还不如先翻译 XX 文档“,虽然有点偏颇,但不能否认的是,没有中文文档,中文 API 几乎是无法推广的。这与国外开发者看到没有英文文档的 API 就兴味索然同理。
2.2 API 命名与文档一致
汉化库时,可以参考中文文档中的术语。既省力,术语保持一致也更易学习。像大疆机甲大师机器人的Python API中,”装甲“,”底盘“,”云台“等等中文术语都在官方文档中。类似的,在开发新 API 时,命名也可以直接沿用需求、设计文档中的中文用语。
三、实现(维护)
3.1 重流程和实现机制(中文化模式)
在中文 API 还远未成气候的现状下,尚未总结出一套行之有效、可以普遍适用的流程,包括如何用最小代价随主库更新,发布和维护方式等等。与其从一开始就追求规模(功能大而全),不如从小库(功能)入手,在中文化机制和开发模式逐渐成熟的过程中,其他开发者易于仿效,对各自的领域的库进行中文化。这样更易形成规模效应。
流程可选取小步快跑式的增量式开发发布过程。易于更早获取反馈和尽早积累社区。
3.2 完备测试集和持续集成(CI)
虽然很多情况是直接封装原有库,但为了获取用户信任,仍需完备的测试集。持续集成对于保证质量及其重要。
从这个角度说,如果原英文库就包含完备的测试集,可以省去很多编写和维护测试的时间。但仍需对原测试集进行汉化,这也是 3.1 需要总结的流程的一部分。
四、发布(推广)
4.1 酒香也怕巷子深
把源码、文档放到 github 等平台只是第一步。发布方式经常会影响用户愿不愿意试用。以 Java 为例,个人对尝试没在 maven 发布的库的动力很小。毕竟类似功能(不偏门)的一般都能找到在 maven 发布的库,或者说,能够流传开并且持续维护的,大多发布在了类似 maven 的库管理和发布平台。JS,python 等等也是类似。估计大多数开发者也更乐意使用在常用渠道发布,并可以非常容易集成到项目中的库。
之前提到的简繁转换库,在maven 发布一年后,就引起了 v2 的一个话题:第一次见以汉字命名的 Java 类 - V2EX。
如果英文库本身就在发布平台,那么中文化之后的库一般也可以发布在同一平台。一个例子是之前对 JUnit4 的汉化。
创建一个发行平台也有好处。但并非一定要创建另一个 maven。之前想到的一个可能是,针对中文用户开发 API 门户,辅助用户用中文对 API 进行搜索,在此基础上逐渐向面向 API 的 编程语言和IDE 发展。中文 API 可以选择任何库发布平台发布,然后在此门户登记并加入索引。可以认为这是个针对中文的 API 搜索引擎。这个途径的另一个好处是,可以逐步完善通用术语的中文命名,为 1.2 提供一个开发者学习适应的平台。
4.2 兵贵神速
最好从英文库发布开始就迅速跟进中文化,越早跟进就能越早积累用户。毕竟中文化后的库对原本的库的需求源是相同的。如果用户用惯了英文 API,积累了一定代码之后,再改用中文版的就要付出更多代价。虽然中文版的有可读性的优势,但早入场仍然会更容易获取用户。有了更多用户反馈,也可以在原 API 基础上进行改进和二次封装。
五、其他
5.1 近水楼台先得月
综合以上考虑,国内开发组/公司实现的库可以考虑优先中文化
- 相较汉化英文库+英文文档,汉化国人创建的库至少只要汉化库就可以,因为大多数都已经有中文文档了
- 非技术层面的理由,国人创建的库更多的是针对国内市场的。这一特性决定了,在比例上来说,这些库的使用者(或者潜在使用者)对中文命名的需求较大(与 1.3 同理)。简言之,通用库的国内用户数量不一定比国内某些库的大。即使更大,汉化的工作量也更大,而目标群体不一定那么领情。
- 如果需要技术支持,国内公司也更容易交流。这在对大疆机甲大师的 API 进行中文化的过程中感受颇深。
5.2 前端库自带开源属性
虽然有不少 JS 代码是混淆过的,但也有相当大部分是源码,相当于自带推广作用。
5.3 库的范围很广
除了传统的本地库,也包括在线 API。之前听说过百度的某些 API 的 返回 JSON 键名为中文。如果技术允许也可以对在线 API 进行封装。
5.4 平台无关
考虑到大趋势,应避免选择和单一平台绑定的库,除非其他理由足够充分。
【2019年12月2日夜 暂搁笔】