Neo4j中文手册翻译指导教程 - kooyeed/manual-chinese GitHub Wiki

Neo4j手册翻译指导教程

概述

由于Neo4j的手册的架构比较复杂，采用了po4a格式，所以对于普通的同学在翻译之前会遇到不少障碍，因此我们特别梳理了下流程，方便大家快速进入翻译角色。

约定

  1. 教程的环境是基于ubuntu desktop版本进行介绍，如果只能使用windows的同学，参考此教程的步骤后依然遇到问题，请与我们 联系。

  2. 翻译时仅进行简体的翻译工作，繁体我们将提供工具(待定)做自动转换。

  3. 如果有意愿加入翻译工作的同学，可以与官方的Anders或者我们联系，确保不要重复翻译。

准备工作

基本工具

  • git相关

因为项目托管在 Github 上面，因此我们的版本管理都通过git来完成，你必须先安装git。

$ sudo apt-get install git

  • AsciiDoc 这是一种跟markdown类似的格式语言，风格很接近，由于官方采用了此格式，因此如果你之前对这种格式不了解，可以做简单了解。即使你不了解 AsciiDoc ，对翻译工作影响也几乎可以忽略。

  • Java SDK

因为Neo4j是由Java开发而成，所以周边相关的都跟Java有关，所以建议安装Java SDK。

$ sudo apt-get install openjdk-7-jdk
Important
 就个人而言，强烈建议安装 官方SDK 。

  • Maven相关

Neo4j的代码都是通过 Maven 来管理的，Neo4j由很多模块组成，每一个模块的手册都在模块中，而统一通过Maven来进行管理。所以你要编译手册源代码（这里的源代码不是计算机语言），生成各种格式（html，pdf，txt等）的手册目标文档，必须先安装Maven。

  • PO编辑工具

Neo4j手册的翻译我们采用了 po4a ，关于po4a我们可以简单的理解为将手册中的文字拆分成一条一条的字符串，我们针对字符串做各种语言的翻译，最后再通过工具生成最终的对应语言版本的手册，这样将手册的结构和内容分离，随着Neo4j版本不断的升级，我们可以提供各种版本的手册，而翻译工作仅仅是对有变化的部分做小小的改动即可。

当然我们做翻译工作其实不需要了解这么多细节，我们只需要用PO编辑器打开po文件，一条一条的翻译即可。

Important
 po4a官方貌似对asciidoc支持不太好，所以官方的Anders进行了补充，所以在实际编译的时候po4a工具会由官方自动下载提供，本地无需自行单独安装。

环境建立

  • 申请一个github账户，登录后先fork官方中文手册项目，并上传pub-key后clone到本地。

$ git clone https://github.com/neo4j/manual-chinese.git
Important
 关于如何使用github，请参考这里：http://www.neo4j.org.cn[如何使用github贡献代码] 。

  • 进入项目根目录，首先使用Maven编译，检测本地环境是否安装成功。如果能成功编译，则可以开始下面的工作。

$ mvn clean package

目录结构

clone到本地后，你会发现手册的目录结构是这样的：

  1. docs: 用于存放与手册相关的模块的原文件。

  2. src: 用于存放官方手册的源文件。 TIP: 在此说明下docs和src的区别，手册的源代码在src中，但Neo4j有很多模块，这些模块的手册代码是分布在模块中的，因此这些模块的手册代码我们只有手动的拷贝来放到docs中。

  3. conf: 这是不同语言的配置。重点在这里配置language。

  4. po: 这是我们需要翻译的文件。通过命令将原始的asciidoc文件转换成po放到这个目录。

  5. target: 这是编译生成的目标目录。并不在版本控制范围内，因此每次clone完成后需要先通过命令mvn生成此目录。

开始翻译

  • 选择自己将要进行的翻译模块，下面我们以Introduction这个章节为例讲解。

  • 首先采用命令将需要翻译的文件转换成po格式。

Tip
 在转换之前，特别注意必须先编译生成target目录，因为target目录不受版本控制，但是后续的工作需要target中的配置和工具的配合。 
$ make add DOCUMENT="src/introduction/index.asciidoc" PART="introduction"

这句话的意思就是将文件"src/introduction/index.asciidoc"转换成它对应的po文件和conf配置文件。

"src/introduction/index.asciidoc"文件其实不在"./src"中，而是在"./target/original/src/"中。 参数PART表示生成的po文件的文件名，可以考虑将相近的文件都存放到同一个目标po文件中，这样会减少翻译工作。 因此，我们同理，可以将"src/introduction/"目录下面的其他文件都转换成po文件。

$ make add DOCUMENT="src/introduction/comparing.asciidoc" PART="introduction"
$ make add DOCUMENT="src/introduction/highlights.asciidoc" PART="introduction"
$ make add DOCUMENT="src/introduction/the-neo4j-graphdb.asciidoc" PART="introduction"
$ make add DOCUMENT="src/introduction/what-is-a-graphdb.asciidoc" PART="introduction"

在"src/introduction/"中还有子目录，我们可以不考虑，以后将它划分到另外一个po文件中。 至此，我们可以在"./po/"目录中发现会生成两个文件"./po/introduction.po"和"./po/introduction.conf"。

  • 用你安装的任意一款po编辑器，打开introduction.po开始翻译。

  • 翻译完成后重新编译并查看翻译的结果是否吻合。

$ make

  • 如果以上步骤成功完成，你可以打开"target/html/index.html"文件，查看你的翻译模块是否成功。

翻译提交

翻译完成后，你可以通过git提交。 具体提交方法，请参考之前我们有关git的使用的文章： 如何使用github贡献代码 。

Add a custom footer
⚠️ **GitHub.com Fallback** ⚠️