Soluling home   Document home

Markdown Localization and Internationalization

Markdown (Wikipedia) is a lightweight markup language. It is used to write readme files, documentation, documentation sites, blogs, and wikis. Soluling Desktop and Soluling Cloud support Markdown files (.md, .markdown).

• What Soluling localizes
• Localization process
• Samples
• Configuring Markdown localization

The end of the document contains links to get the full source code of the samples. After reading this document, we recommend reading a tutorial about how to use Soluling.

What Soluling localizes

Soluling reads the original Markdown file and extracts the text elements, such as headings, paragraphs, list items, and table cells. Inline formatting, such as bold, italic, code spans, and links, stays inside the strings so that the translator can translate whole sentences. When building, Soluling creates one localized Markdown file for each language. Take a look at the following simple Markdown file.

Sample
====

This is a sample.

Line one.
Line two.

This is **bold**, *italic*, ***both*** and `code`.

## List

- One
- Two
- Three

You can find the file in <data-dir>\Samples\Markdown\Simple\Simple.md. The file has several text parts that need to be translated. If we translate the above file into Finnish, we get:

Esimerkki
====

Tämä on esimerkki.

Rivi yksi.
Rivi kaksi.

Tämä on **lihavoitu**, *kursivoitu*, ***sekä*** että `koodi`.

## Lista

- Yksi
- Kaksi
- Kolme

The structure of the Finnish Markdown file is identical to the structure of the original English Markdown file; only the text in each element has been translated into Finnish. If you change the original Markdown file, use Soluling to rescan the file. Soluling aligns the elements again to keep the unchanged elements, adds the new elements, and marks the modified elements. You only need to translate the new elements and check the modified elements.

By default, Soluling does not translate code blocks, because they usually contain source code. If your code blocks contain text that should be translated, check Scan code blocks on the Options sheet.

Note! Write the localized files in UTF-8, the encoding that most Markdown tools, such as GitHub, expect. If your original file contains only ASCII characters, check the encoding on the Output sheet so that characters such as Finnish ä or Japanese characters are written correctly.

Localization process

You can localize a Markdown file either in Soluling Desktop or in Soluling Cloud.

Desktop process

Start by creating a new project for your Markdown file, for example, Simple.md. The Project Wizard first shows the Options sheet where you can configure what elements are localized.

Click Next to get to the Languages sheet where you can select the original language and add the target languages. You can later add any number of languages to the project.

Select English as the original language and add one or more target languages. In our sample, we chose Finnish. Click Finish to complete the wizard. Soluling creates a project for the Markdown file, scans the file, and shows the elements in the editor.

Follow the general translation instructions to translate your project.

When you have translated the project, choose Home | Build All to build the localized files. The Finnish Markdown file is created into the fi subdirectory with the same name as the original file (e.g., fi\Simple.md).

Cloud process

With Soluling Cloud, you translate the Markdown file in your browser: upload the file, translate it in Translate, and download the localized files. You need a Soluling account. See the available Cloud plans.

Create a project

1. Sign in at www.soluling.com and open Cloud > Dashboard for Projects, Users and Terminology.
2. Click Add a new project, then Select files and pick your Markdown file (e.g., Simple.md), or drag and drop the file onto the page. Click Create.
3. On the next page, check the project's Name. It defaults to the file's name.
4. Set the Original language to the language of your file, for example, English.
5. Under Target languages, check the languages you want to translate to, for example, Finnish and Japanese.
6. Check that the Source type is Markdown file (.md, .markdown).
7. Click Create. The project appears on the dashboard, and its status changes to Ready once the file has been processed.

Translate the project

Click the project's green Translate button on the dashboard. Translate opens the project, and you can type the translations into the grid. Machine translation suggestions, translation memory, and spell checking are available there. You do not have to finish every language before moving on to the next step.

Inline formatting, such as bold text, code spans, and links, is shown as protected tags.

Get the localized files

1. In Translate's top bar, click the project's name. It opens the project's Manage page, the same page that the project's Manage button on the dashboard opens.
2. If you have translated something since the localized files were last built, the page says Localized files need to be built. Click Build localized files and wait until it finishes.
3. The Files section lists the Markdown file with a download button for each target language. Download the localized files.

Update the project

When you change the original Markdown file, upload it again, translate what is new or changed, and download the localized files again. On the dashboard, click the project's Update file button (the upload arrow), select the new file or drop it onto the page, and click Update. Existing translations are kept, so you only translate the text that was added or changed.

If you want to translate code blocks, create the project in Soluling Desktop, where you can set the option, and upload it to Soluling Cloud. See the Cloud tutorial.

Samples

GitHub and <data-dir>\Samples\Markdown contain the following Markdown sample directories:

Configuring Markdown localization

You can configure how to localize your Markdown file by selecting the item in the project tree, right-clicking, and choosing the Options menu. A source dialog appears that lets you edit the options. This source uses the following option sheets.

• File
• Options
• Output

Read more about other document files such as DITA, Help+Manual, HTML, HTML Help, LaTeX, Word, PowerPoint, Markdown, RTF, and PDF files.