Table of Contents
How-to translate a document in AsciiDoc format
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
An AsciiDoc document contains both content and markup, in other words formatting instructions to be applied by the
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
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 may, 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)
- Originally written by didierspaier