30.4. Translating the Neo4j Manual

To translate the Neo4j Manual, there’s a special project setup to use. See the French translation project for an example: https://github.com/neo4j/manual-french

The project contains:

  • conf/ — configuration for the project.
  • docs/ — translated files for content provided by Neo4j modules.
  • po/ — translation files and po4a configuration files.
  • src/ — translated files for content provided by the original manual.
  • Makefile — a makefile with project-specific configuration.
  • pom.xml — Maven build configuration.


  • Apache Maven
  • GNU Make
  • Python
  • Perl
  • Perl module: Unicode::GCString

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”.

Build flow and file layout

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:

  1. target/original/(src|docs)/ — the contents of the original manual. Note that’s it easier to look for content here than to dig into the original manual itself.
  2. target/(src|docs)/ — the translated source to use for the AsciiDoc build.

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

  1. It starts out as a copy of the original manual.
  2. Next, any static translated files fromt the src/ and docs/ directories of the project are copied.
  3. Finally, the translation files in the po/ directory are used to generate translated documents.

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

Adding a chapter to a translation file

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.


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.

  • make — same as make preview.
  • make add — add a document to a translation file.
  • make preview — refresh and build preview of the manual.
  • make refresh — refresh translation files from the original and generated translated documents.

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.

Translation tools

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