The Neo4j Manual v2.0.230.4. Translating the Neo4j Manual

To check if you have the Unicode::GCString module installed, you can issue the following command:

perl -MUnicode::GCString -e ''

If there’s no error, the module has been successfully installed on your system.

To install the module, you can use cpanminus. For a convenient way to install it, see http://cpanmin.us. With cpanminus installed, execute this command:

cpanm Unicode::GCString

You will probably want to use a .po file editor as well, see the section called “Translation tools”.

The build is essentially a two-step process. The first step generates or copies translated documents, while the second step is an ordinary AsciiDoc build using the output from the first step as sources.

Other than the src/ and docs/ diirectories of the project, the build generates files with the same layout in two more places:

The translated documents in target/(src|docs)/ are generated in three steps:

Files produced by later steps will overwrite existing files from earlier steps.

The translation is split over multiple translation files, one per “part” of the manual. It’s all about making the translation easier to manage and the tools to perform well. The basic rule of thumb is that if some content is moved, it should likely still end up in the same translation file. In that case, the tools will even detect this and the translation will be moved automatically.

To add a document to a translation file, do like this:

make add DOCUMENT="src/introduction/the-neo4j-graphdb.asciidoc" PART="introduction"

If the translation file does not already exist, it will be created. The document will be added to the translation build configuration file as well. (The configuration is in the corresponding .conf file in the po/ directory.)

If there exists a translated copy of the document at the location the DOCUMENT parameter points to, the script will attempt to populate the translation file with translated paragraphs from that document. Note that the structure of the document has to be a perfect match, or it will fail. However, the error messages are helpful, so just fix and try again until it works! Translation file and configuration are only changed when the first part succeeds.

Note Only documents that need to be translated should be added. For example Cypher queries and query results should not be translated. In general, documents residing in a directory named includes should not be translated.

Also note that AsciiDoc include:: lines are normally not part of the translation at all, but handled automatically. In case they need to be handled differently in a document, this has to be configured in the corresponding .conf file. For example a normal document entry in such a file can look like this:

[type: asciidoc] target/original/src/operations/index.asciidoc fr:target/src/operations/index.asciidoc

To configure a single document not to handle include:: lines automatically, add the following at the end of the line:

opt: "-o definitions=target/tools/main/resources/conf/translate-includes"

First, use Maven to set up the environment and download the original manual and documentation tools:

mvn clean package

To refresh the original manual and the tools, use the maven command again. For the sake of keeping in sync with the original manual, a daily run of this command is recommended.

Once things are set up, use make during work.

The preview of the translated manual is found in the target/html/ directory.

The actual work on translation is done by editing translation files. Suggested tools for that are found below.

There are different editors for .po files containing the translations Below is a list of editors.