Translator Guide

Introduction

This document is intended to help translators who work on translating Climate Interactive's documentation (such as the En-ROADS User Guide) from English into other languages.

Markdown Syntax

The English source material for the En-ROADS User Guide is written in Markdown format.

If you are new to Markdown, this Translator Guide will show you enough syntax to get started translating the En-ROADS User Guide in Weblate.

For more detailed information about Markdown syntax, please refer to the following sections in the Markdown Guide:

Basic Syntax (headings, lists, bold/italic, etc)
Extended Syntax (tables, code blocks, etc)

General Advice

When in doubt, try to follow the same format in the translated text as it is used in the English text.

For example, suppose you are translating the guide into a fictitious ALLCAPS language. If you see the following English text in Weblate:

This is an intro paragraph.

- This is a list item with **bold text**.
- This is a list item with *italic text*.
- This one has an [inline-style link](page.html).
- This one has a [reference-style link][page].

You can translate the above as follows:

THIS IS AN INTRO PARAGRAPH.

- THIS IS A LIST ITEM WITH **BOLD TEXT**.
- THIS IS A LIST ITEM WITH *ITALIC TEXT*.
- THIS ONE HAS AN [INLINE-STYLE LINK](page.html).
- THIS ONE HAS A [REFERENCE-STYLE LINK][page].

Read on for more details on different kinds of Markdown text you will see in Weblate.

Paragraphs

In Markdown, paragraphs are separated by a blank line. In the following example, there are two paragraphs:

This is the first paragraph.

This is the second paragraph.

When translating text that has multiple paragraphs, be sure to include a blank line between paragraphs just like in the English text. (Weblate will raise a warning if there's a mismatch in blank lines between the English and translated text.)

For example, here is how it should be translated into the ALLCAPS language:

THIS IS THE FIRST PARAGRAPH.

THIS IS THE SECOND PARAGRAPH.

Bold and Italics

In Markdown, you can make a word/phrase bold by surrounding it with double asterisks (or double underlines), like this:

The last word here is **bold**.
The last word here is also __bold__.

You can make a word/phrase appear in italics by surrounding it with single asterisks (or single underlines), like this:

The last word here is in *italics*.
The last word here is also in _italics_.

When translating text that has bold or italic styling, you can use similar styling in the translated text. Feel free to omit styling if it doesn't make sense for the target language.

Lists

Many passages in the En-ROADS User Guide (and in some En-ROADS graph/slider descriptions) are presented to the translator as a single list of items. There are two kinds of lists:

unordered (will appear as a bulleted list)
ordered (will appear as a numbered list)

Unordered Lists

In Markdown, a simple unordered list looks like this:

- This is the first item.
- This is the second item.
- This is the third item.

Sometimes you will see a blank line between items:

- This is the first item.

- This is the second item.

- This is the third item.

In the first case, the list will appear in the final documentation with no space between the items, but in the second, the list will appear with extra space between the items.

We recommend that you use follow the example of the English text. If the list has no blank lines between items, do the same for the translated text. If the list does have blank lines between items, do include blank lines between items in the translated text.

⚠️ Be careful when starting each line of a bulleted list!

Always use a normal dash (-) to start each list item. If you use an "endash" (–) character instead of a normal dash (-) at the beginning of the line, the Markdown parser will not treat it as a bulleted list and it will appear as a normal paragraph.
Always add a space after the dash (for example, "- This is an item"). If you omit the space, the Markdown parser will not treat it as a bulleted list item.

Ordered Lists

In Markdown, a simple ordered list looks like this:

1. This is the first item.
1. This is the second item.
1. This is the third item.

Note that the repeated 1. at the beginning of each item is intentional. Be sure to use this style in your translated string.

Here is a translated example using the ALLCAPS language:

1. THIS IS THE FIRST ITEM.
1. THIS IS THE SECOND ITEM.
1. THIS IS THE THIRD ITEM.

When it is rendered in the final documentation, it will appear as a normal numbered list, like this:

    1. THIS IS THE FIRST ITEM.
    2. THIS IS THE SECOND ITEM.
    3. THIS IS THE THIRD ITEM.

Nested Lists

Sometimes you may see a nested list (a list inside of a list, with added indentation). Each line in the nested list needs to start with 4 spaces, so be sure to follow the example of the English text:

- This is the first item.
- This is the second item.
    - This is the first subitem under the second item.
    - This is the second subitem under the second item.

Links

In general, we strive to keep raw URLs out of the strings that are made available for translation because they are error prone.

Most links you encounter will be reference-style links. These are preferred because you will not need to deal with raw URLs. However, in a few rare cases, you may encounter inline-style links.

In Markdown, the two kinds of links look like this:

This is an [inline-style link](https://climateinteractive.org).
This is a [reference-style link][ci].

Note that there are two parts to a link:

the link text (the part that the user will see in the rendered documentation); this is the "click here" part between the square brackets
the target URL or ID; this is the https://climateinteractive.org or ci part between the parentheses/brackets

When you see a link appear in a string in Weblate:

DO translate the link text (the first part)
DO NOT translate the target URL or ID (the second part)
DO NOT include a space between the first and second parts

For example, in ALLCAPS, the above would be translated as:

THIS IS AN [INLINE-STYLE LINK](https://climateinteractive.org).
THIS IS A [REFERENCE-STYLE LINK][ci].

Note that Weblate will raise a warning if you type the ID part incorrectly.

Subscripts and Superscripts

There isn't a fully standard way of expressing subscripts and superscripts in Markdown.

NOTE: You won't have to worry about subscripts in most cases. There are some common chemical formulas (CO₂, CH₄, N₂O, SF₆) that appear frequently in the En-ROADS User Guide, so we've made our documentation software handle those for you.

For example, if you see the following string in Weblate, note that there is no added markup for a subscript 2:

Land Use CO2 Emissions

That string can be translated into the ALLCAPS language as:

LAND USE CO2 Emissions

When it is rendered in the final documentation, the subscript 2 will be included automatically and will appear as follows:

LAND USE CO₂ EMISSIONS

In the rare cases where subscripts or superscripts do appear in Weblate, we resort to HTML tags.

For example, to have a subscript 2 as in CO₂, use <sub> tags:

CO<sub>2</sub> is carbon dioxide.

To have a superscript 2 as in x², use <sup> tags:

Another way to write "x squared" is x<sup>2</sup>.

Footnote References

We currently do not make footnotes available for translation because many of them are citations that reference scientific articles, and translations may not be useful.

However, you should be aware that references to those footnotes will appear in some English strings. These references have the form footnote-ref:xyz. When you see this string at the end of some English text, be sure to include it verbatim in the translated text.

For example:

New York City, USA: Increasing urban tree density
by 343 trees per square kilometer was shown to
reduce the rate of childhood asthma by 29% in
New York City. footnote-ref:us_1

When translated into the ALLCAPS language, note that we leave the footnote-ref:us_1 part untouched:

NEW YORK CITY, USA: INCREASING URBAN TREE DENSITY
BY 343 TREES PER SQUARE KILOMETER WAS SHOWN TO
REDUCE THE RATE OF CHILDHOOD ASTHMA BY 29% IN
NEW YORK CITY. footnote-ref:us_1

Glossary Links

There is one other type of element with custom syntax that you will see in the En-ROADS User Guide: glossary links.

Glossary links are special in that they are rendered in the final documentation with a dashed underline. When the user hovers the mouse over the word/phrase, a tooltip appears with a definition. The link can also be clicked, which will open the definition in the full Glossary page.

To make these work, we use normal Markdown reference-style link syntax, where the ID takes the form glossary_word.

You should follow the same advice as in the Links section above for translating glossary links:

DO translate the link text (the first part)
DO NOT translate the glossary_word part (the second part)