[2024-feb-29] Sad news: Eric Layton aka Nocturnal Slacker aka vtel57 passed away on Feb 26th, shortly after hospitalization. He was one of our Wiki's most prominent admins. He will be missed.

Welcome to the Slackware Documentation Project

This is an old revision of the document!


How-to translate a document in AsciiDoc format

Introduction

According to its Home Page:

AsciiDoc is a text document format for writing notes, documentation, articles, books, ebooks, slideshows, web pages, man pages and blogs. AsciiDoc files can be translated to many formats including HTML, PDF, EPUB, man page.

AsciiDoc is highly configurable: both the AsciiDoc source file syntax and the backend output markups (which can be almost any type of SGML/XML markup) can be customized and extended by the user.

Let's take an example: if you write mypage.txt in AsciiDoc format, then this command:

asciidoc -b xhtml11 mypage.txt

will process mypage.txt to generate mypage.html in XHTML 1.1 format

AsciiDoc is included in Slackware, in package linuxdoc-tools.

An AsciiDoc document contains both content and markup, in other words formatting instructions to be applied by the asciidoc command.

For instance Slint Project's Home Page has been generated with AsciiDoc from a text file that can be displayed clicking on Page Source in its menu.

As you can see, syntax of AsciiDoc markup is not very complicated.

But when translating documents in AsciiDoc format, it can seem difficult at times to preserve this markup, while translating all that may and should be translated, hence this How-To.

Intended audience is people wanting to translate documents in AsciiDoc format, in other words text files mixing content and AsciiDoc markup, to be processed by the asciidoc command.

Recommendations

Of course you'll need to get acquainted with AsciiDoc markup syntax. The reference document is the AsciiDoc User Guide but for a starter, you could just read this AsciiDoc cheatsheet. Even faster, assuming that asciidoc is installed this command, typed in a terminal:

asciidoc --help syntax > asciidoc.txt

will write the AsciiDoc Markup Syntax Summary in file asciidoc.txt that you can then display with a pager or print.

Preserve the markup

Be careful to preserve the markup as is, if you are not sure of the syntax. For instance, adding or removing spaces or “newline” characters can have unexpected effects. Here are a few examples :

  • Beginning a paragraph with a space will generate a 'literal paragraph' displayed with a specific font
  • '= some text' will generate a level 0 header (document title), but only if '=' is the first character of the line, there is a space after it and there is a blank line before.
  • ' +' appended to a line will generate a 'line break' only if there is space before the '+', that should be the last character of the line

If you use a text editor to translate, just make a copy the genuine file and edit it.

If instead you use an on line editor like that of Transifex, begin with copying then paste in the translation field each genuine text string containing AsciiDoc markup.

Check the rendering of your translation

If you translate using a text editor, just issue an asciidoc command then display the generated file and compare it with the genuine one. For instance, assuming that your translation of genuine.txt is translation.txt:

asciidoc genuine.txt
asciidoc translation.txt
firefox genuine.html asciidoc.html

If you use an on line editor like that of Transifex instead, just download the translation first.

Translate or not translate, that is the question

Following words have a special meaning for Transifex and should not be translated when they begin an admonition paragraph (and are often replaced by icons): TIP, NOTE, IMPORTANT, WARNING and CAUTION.

Generally speaking, links and URLs should not be translated, but associated caption can, depending on the context. In following examples (taken from ascii doc –help syntax only value of caption may be translated:

Document links:
[[id]]                      (define link target)
<<id,caption>>              (link to target id)
link:filename#id[caption]   (link to external HTML file)

URLs:
http:address[caption]       (link to web page)
mailto:address[caption]     (link to mail recipient)

Images:
image:filename[caption]     (inline image)
image::filename[caption]    (block image)

Sources

* Originally written by didierspaier

 howtos:misc:how-to_translate_a_document_in_asciidoc_format ()