1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
|
= Localization Support
:keywords: translations, labels, l10n, internationalization, i18n
:url-docbook-i8n: http://www.sagehill.net/docbookxsl/Localizations.html
:url-lang-attributes: {url-org}/asciidoctor/blob/{page-origin-refname}/data/locale/attributes.adoc
Asciidoctor is not restricted to working with English-only content.
Asciidoctor can process the full range of the UTF-8 character set.
That means you can write your document in any language, save the file with UTF-8 encoding, and expect Asciidoctor to convert the text properly.
Furthermore, you can customize the built-in labels (e.g., "`Appendix`") to match the language in which you are writing.
This process is known as localization (l10n).
The built-in labels used in the output generated by Asciidoctor are English by default.
These labels can be modified by changing the value of the <<label-attributes,corresponding attributes>>.
There are some caveats to know about:
* Currently, the official HTML and PDF converters only fully support left-to-right (and top-to-bottom) reading.
Support for right-to-left (RTL) is being considered.
See {url-org}/asciidoctor/issues/1601[issue #1601^] for details.
In the interim, you can leverage the DocBook toolchain to get right-to-left support.
* Attributes that store dates and times (e.g., `docdatetime`) are always formatted like `2019-01-04 19:26:06 -0600`.
* Application messages (i.e., log messages) are always in English.
* Asciidoctor does not support the language conf files used by AsciiDoc.py.
However, Asciidoctor does provide {url-lang-attributes}[a translation file^] that can be used for a similar purpose.
[#customizing-labels]
== Translating built-in labels
When converting to DocBook, you can rely on the DocBook toolchain to translate (most) built-in labels.
To activate this feature, set the `lang` attribute to a valid country code (which defaults to `en` for English).
For example:
$ asciidoctor -a lang=es -b docbook article.adoc
The list of supported languages, as well as additional language considerations for DocBook, are described in {url-docbook-i8n}[DocBook XSL: The Complete Guide^].
The `lang` attribute _does not_ enable automatic translation of built-in labels when converting directly to HTML or PDF.
It's merely a hint to configure the DocBook toolchain.
If you're not using the DocBook toolchain for publishing, you must translate each built-in label yourself.
One way is to set the following attributes in the document header or by passing the attributes via the API or CLI:
.Attributes that control built-in labels
[#label-attributes,cols="~,~,30%"]
|===
|Attribute |Default English Value |Notes
|`appendix-caption`
|Appendix
|
|`appendix-refsig`
|Appendix
|Used when referencing an appendix.
|`caution-caption`
|Caution
|
|`chapter-signifier`
|Chapter
|Only applies when `doctype` is `book`.
|`chapter-refsig`
|Chapter
|Used when referencing a chapter.
|`example-caption`
|Example
|
|`figure-caption`
|Figure
|
|`important-caption`
|Important
|
|`last-update-label`
|Last updated
|
|`listing-caption`
|_not set_
|By default, listing blocks do not have captions.
Specify `listing-caption` to turn on captions for listing blocks.
|`manname-title`
|NAME
|Only applies when `doctype` is `manpage`.
|`note-caption`
|Note
|
|`part-signifier`
|Part
|
|`part-refsig`
|Part
|Used when referencing a part.
|`preface-title`
|_not set_
|Only applies when `doctype` is `book`.
|`section-refsig`
|Section
|Used when referencing a section.
|`table-caption`
|Table
|
|`tip-caption`
|Tip
|
|`toc-title`
|Table of Contents
|
|`untitled-label`
|Untitled
|
|`version-label`
|Version
|
|`warning-caption`
|Warning
|
|===
If you plan to support multiple languages, you'll want to define the attributes for each language inside a xref:asciidoc:directives:conditionals.adoc[conditional preprocessor directive].
For example:
[,asciidoc]
----
\ifeval::["{lang}" == "de"]
:caution-caption: Achtung
...
\endif::[]
----
Of course, you're probably hoping this has already been done for you.
Indeed, it has!
You can find an {url-lang-attributes}[AsciiDoc file^] in the Asciidoctor repository that provides translations of these attributes for most major languages.
Thus far, the built-in labels have been translated into the following languages: Arabic, Belarusian, Bulgarian, Catalan, Czech, Danish, Dutch, German, Spanish, Persian (Farsi), Finnish, French, Hungarian, Bahasa Indonesian, Italian, Japanese, Korean, Norwegian Bokmål, Norwegian Nynorsk, Polish, Portuguese, Brazilian Portuguese, Romanian, Russian, Serbian Cyrillic, Serbian Latin, Swedish, Turkish, Ukrainian, Vietnamese, Simplified Chinese, and Traditional Chinese.
The translations are defined using AsciiDoc attribute entries inside conditional preprocessor blocks, just as suggested above.
To use this file to translate the built-in labels according the value of the `lang` attribute (just like the DocBook toolchain does), follow these steps:
. Download the AsciiDoc file {url-lang-attributes}[attributes.adoc^] from the Asciidoctor repository.
. Put the file in the folder [.path]_locale_ relative to your document.
. Add the following line to the header of your AsciiDoc document:
+
[,asciidoc]
----
\include::locale/attributes.adoc[]
----
. Set the language using the `lang` attribute.
This attribute must be set before the include directive gets processed.
For example:
-a lang=es
The built-in labels will now be translated automatically based on the value of the `lang` attribute.
There's an ongoing discussion about how to make language support even simpler ({url-org}/asciidoctor/issues/1129[issue #1129^]).
Input is welcome.
== Translation
Asciidoctor (or DocBook) currently does not support translation of content out of the box.
There's a proposal to integrate gettext (https://discuss.asciidoctor.org/Professional-providers-translating-Asciidoc-tt2692.html#none[discussion^]), and suggestions are welcome.
|
