# Translation texts
Texts of translations are formatted in a special standardized way which is described on this page.
{% hint style="warning" %}
There are some differences in formatting for JSON and XML. Although they are minor, it is important to know about them. See the [Translation texts](/digital-quran/standards-and-conventions/translation-texts.md#translation-comments-and-footnotes) section below for details.
{% endhint %}
## Symbols style guide
**ENCODING**. All translations texts are UTF-8 encoded.
**QUOTATION MARKS (**«»**)** should be conventional for the language — not straight quotes. Conventional quotation marks for each language are available [here](https://en.wikipedia.org/wiki/Quotation_mark).
**HYPHENS.** Double(`--`) or triple hyphens (`---`) are replaced with a single em dash (`—`) with white space before and after it. Single hyphen is used only for word connection, like in "follow-up" word. In such case, hyphen has no white space before or after.
**PUNCTUATION**. The language's punctuation is used. For example, Farsi translation has a Farsi comma, not Latin (ASCII).
## Merged translations
Some by-ayah translations and most of the word-by-word translations have merged translations: cases when multiple consecutive words (or ayah for by-ayah translations) share one translation. For example, the first two words in the following picture have a merged word-by-word translation.
In such cases, translation text is put in only in the first (word or ayah) in the sequence. As for the following, their translation text is one symbol -- `*`. I.e. for the provided example above translation looks like so:
{% tabs %}
{% tab title="JSON" %}
```javascript
"words": [
{
"number": 1,
"text": "Дошёл ли до тебя"
},
{
"number": 2,
"text": "*"
},
{
"number": 3,
"text": "рассказ о"
},
{
"number": 3,
"text": "Мусе?"
}
]
```
{% endtab %}
{% tab title="XML" %}
```markup
Дошёл ли до тебя
*
рассказ о
Мусе?
```
{% endtab %}
{% endtabs %}
## **Translation comments & footnotes (`(`, `[`, `[[`, ...)**
{% hint style="info" %}
We try our best to stick with this convention of separation between `(`, `[`, and footnotes. But in some cases, it is difficult to distinguish between them. Besides, authors may have different opinions. So, from our side, we ask authors to follow these rules but we leave the decision for them. Keep this in mind when use translations.
{% endhint %}
Translation comments are of two types
**1. Short inline comments.** These comments are short specifying comments which must be placed inline with the translation. Both single parenthesis and single brackets are allowed for them.
The convention is to use single parenthesis (`(...)`) for words which are implicitly implied in the original Arabic text. Like in the following example below:
And single brackets (`[...]`) for words which are added by the author for a specification but presented neither explicitly nor implicitly in the original Arabic text. For example, in the picture below, the author specifies that "the one who forbids" is Abu Jahl. In English, it would look like "Have you seen \[Abu Jahl] the one who forbids". "Abu Jahl" is not presented in the original Arabic text, it is a specification of the translator according to tafseers and opinions of scholars, so it is put in single brackets.
**2. A detailed explanatory comment.** A detailed comment is something we see as a footnote in a book. It is a broad explanation which is usually quite a long text. Some Quran translations use `[[` for them, some use footnotes. The standard of this project is to use footnotes like so:
**Such translations has different format in JSON and XML.**
{% tabs %}
{% tab title="JSON" %}
```javascript
"ayahs": [
{
"number": 1,
"text": "Ние ти дадохме [о, Мухаммад реката] ал-Каусар.[^1]\n\n[^1]: “Каусар” е името на реката на изобилието, дарена на Мухаммед, мир нему, същевременно означава “голямо изобилие”. В тази сура се повелява да се прави жертвоприношение и се дава отговор на съдружаващите, които обиждали Пророка, наричайки го “Лишения” (“Ал-абтар”), защото нямал мъжка рожба."
},
...
]
```
{% endtab %}
{% tab title="XML" %}
```markup
Ние ти дадохме [о, Мухаммад реката] ал-Каусар.
“Каусар” е името на реката на изобилието, дарена на Мухаммед, мир нему, същевременно означава “голямо изобилие”. В тази сура се повелява да се прави жертвоприношение и се дава отговор на съдружаващите, които обиждали Пророка, наричайки го “Лишения” (“Ал-абтар”), защото нямал мъжка рожба.
...
```
{% endtab %}
{% endtabs %}
JSON format is simply a makdown-formatted footnote:
```
Ние ти дадохме [о, Мухаммад реката] ал-Каусар.[^1]
[^1]: “Каусар” е името на реката на изобилието, дарена на Мухаммед, мир нему, същевременно означава “голямо изобилие”. В тази сура се повелява да се прави жертвоприношение и се дава отговор на съдружаващите, които обиждали Пророка, наричайки го “Лишения” (“Ал-абтар”), защото нямал мъжка рожба.
```
where `\n` is used for a line-break.
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://quranacademy.gitbook.io/digital-quran/standards-and-conventions/translation-texts.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.