====== How-to translate a document in AsciiDoc format ======
===== Introduction =====
According to its [[http://asciidoc.org/|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 [[http://slint.fr/slint.html.en|Home Page]] has been generated with AsciiDoc from a text file that can be displayed clicking on [[http://slint.fr/slint.en.txt|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 [[http://asciidoc.org/userguide.html|AsciiDoc User Guide]] but for a starter, you could just read this [[http://powerman.name/doc/asciidoc|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)

====== Sources ======
<!-- If you are copying information from another source, then specify that source -->
<!-- * Original source: [[http://some.website.org/some/page.html]] -->
<!-- Authors are allowed to give credit to themselves! -->
  * Originally written by [[wiki:user:didierspaier]]
<!-- * Contributions by [[wiki:user:yyy | User Y]] -->

<!-- Please do not modify anything below, except adding new tags.-->
<!-- You must remove the tag-word "template" below before saving your new page -->
{{tag>howtos asciidoc translation}}