汉化经验总结

这是对草蟒成员汉化工作一些经验的总结，欢迎批评、指正、补充。大家在汉化库的时候，务必参照这些经验，以保持统一性。

  1. 汉化原则：对英文库 API 进行封装的深度汉化（即用户输入的信息和库返回的信息，包括报错信息，基本为中文）。
  1. 库名的汉化：不必拘泥于原英文库名的直译，可以大胆创造你喜欢的易懂易记的名称。比如： pygame - 游戏派 requests - 网络请求 （使用时，如果嫌“网络请求”较长，可以使用汉语拼音首字母缩写 wlqq，这是 lwdnxu 的主意，完全符合中文使用习惯。） 
    1. 导入  网络请求  为  wlqq
  2. 类名、函数名称的汉化：如果直译难以理解或意译更好的话，应根据其作用取意译。
  1. 类名：中文类名加一个后缀“类”字。比如： 
    1. class Label:
    2.        # 汉化为
    3. 类 标签类:
  1. 类的汉化：采用继承原英文类的办法，这样中文类里面的汉化函数就可以调用英文函数。属性和参数运用字典进行汉化。如果英文类是继承而来的，那么其父类可能也需要汉化，中文类的父类要包括汉化的父类。参见海龟库和图快库中的一些做法。
  1. 函数的汉化：调用相应的英文函数进行封装。参数、参数值选项、函数返回值也需要视情况汉化。
  1. 对关键词参数（前面有双星号的参数）的汉化，老吴已写出一个通用函数放到 lib 中，大家可以直接调用。对前面有一个星号的参数的汉化，我将在碰到更多实例后加以总结，写出一个通用函数，当然如果有人先写出来，那就更好了。
  1. 在汉化库的“导入”部分之后加上汉化者信息和版本（日期）。比如： 
    1. 汉化人 = '张三'
    2. 汉化版本 = '20191222 - 20191201' # 分别表示最后更新日期和开始日期
  1. 注释：除了原注释中的必要信息之外，还可以加上你认为必要的或有用的信息、参考资源等。注释中提到参数、函数、类等信息的地方，不要用中文引号，建议用 <> 代替。
  1. 以文件夹形式提供的库的汉化：汉化库同样以文件夹形式提供，对包含 API 的文件进行汉化，并加上一些必要的辅助文件。文件夹中必须包括一个（汉化的）init.py。另外，如果英文库中有 main.py 文件，汉化库也应有（汉化的）main.py 文件。汉化库中的其余文件应为中文名。
  1. 如果某个函数返回的结果是一个含有一些方法和属性的对象，为使 VS Code 能够提示这些方法和属性，应使用类型注解库 typing。参见海龟库中的 <克隆()> 函数。 
    1. 从  typing  导入  TypeVar
    2.  
    3. _T = TypeVar('_T')
    4.  
    5. 函 克隆(自身: _T) -> _T:
    6. '''创建并返回海龟的克隆体, 其与原海龟具有相同的位置、朝向和属性.'''
    7.      返回 自身.clone()
  1. 对于第 10 条，现在有了一个更简单的办法，无需使用 typing，只需在 -> 之后加上带引号的类名（如果是内置类，当然就不必加引号）。例如： 
    1. 函 克隆(自身) -> '海龟类':
    2. '''创建并返回海龟的克隆体, 其与原海龟具有相同的位置、朝向和属性.'''
    3.      返回 自身.clone()
  1. 对第 10 条的引申（由 seawind2012 贡献）：如果函数返回结果是一个英文类，为了对这个结果进行汉化，应当用对应的中文类对结果进行封装。这样做的好处是不必大幅修改原函数便可完成汉化。例如： 
    1. pygame.draw.circle() -> Rect  # （Rect 对应的中文类是 <区块类>）
    2.       # 汉化为
    3. 游戏派.绘画.画圆() -> 区块类(Rect)
  1. 英文库中定义了 all 的，只需汉化 all 中列出的东西。
  1. lwdnxu 写了一个辅助汉化的工具 - 自动提取+关键词.py，大家可以根据需要使用。
  1. 注释中说明已经废弃或即将废弃（deprecated）的 API 不需要汉化。