Markdown

Markdown comes in many flavors. The one that is supported by Smartling is the GitHub flavor of Markdown. Consult a member of your internal technical team to confirm which flavor of Markdown you are using.

Preparing Markdown Files for Translation

Before uploading your Markdown file to Smartling, be aware of the following:

Markdown translation is accomplished by transforming content into HTML so that it can be manipulated in translation tools and viewed in context with ease. Once translation is complete, the content is converted from HTML back into Markdown while the translated content is downloaded. As a result, your original Markdown document may differ in some ways from what is downloaded in the translated documents.

During the translation process, Smartling will try to maintain the same visual layout of your file, but can’t guarantee that there won’t be some noticeable differences. Some post-processing may be required to return the same formatting as the original document. See below for more details about the Markdown formatting.

ICU Message Format is not supported with Markdown due to conflicts between ICU special characters and Markdown special characters.

File directives for API Service configuration parameters are listed below. Inline directives are not supported.

Markdown Formatting

Below are some examples of known differences for Markdown formatting in the translated file returned by Smartling.

Alternate Codes

Most Markdown styling can be represented by different Markdown code sequences (or character sequences). One code sequence will be consistently returned for any given style. For example:

H1 and H2 headers (only)

# Header 1
## Header2

Header 1
=======
Header 2
-------------

The above only applies to Markdown h1 and h2 headers. All other headers are unchanged on download.

Italic and bold:

Text with _Italic_, __bold__, *Italic* , **bold**

Text with *Italic*, **bold**, *Italic* , **bold**

Formatting of code blocks is returned with an indentation style:

```
public void main()
{
// body
}
```

public void main()
{
// body
}

Frontmatter in Markdown

Frontmatter is a block of YAML at the top of a markdown file, e.g.:

—
layout: post
title: Blogging Like a Hacker
description: This is a description
—

Anything that is in between the — should be treated as YAML.

This can be controlled by using the yfm_block_enabled directive.

Escaping

The following characters are escaped with a backslash '\' in the downloaded file if they’re in the translated text:

\ backslash

* asterisk

_ underscore

{} curly braces

[] square brackets

() parentheses

# hash mark

+ plus sign

- minus sign (hyphen)

! exclamation mark

. dot sign is escaped when it is placed after a number (e.g. 123\.)
The greater sign (>) is escaped when it is placed on the new line, or after the beginning of a
paragraph (if it is not a blockquote).

Script Tags

Literal (HTML markup inside markdown) script tags are removed.

<script type="text/javascript">
// JavaScript example

document.getElementById("demo").innerHTML = "Hello JavaScript!";
</script>
okay

 okay

<script>
foo
</script>1. *bar*

1\. \*bar\*

Style Tags

Literal (HTML markup inside markdown) style tags are removed.

<style
 type="text/css">
h1 {color:red;}

p {color:blue;}
</style>
okay

 okay

Blockquotes

Blockquotes can be merged.

> foo

> bar

> foo
>
> bar

Bullets With Headings

Extra line breaks can sometimes be returned. 

- # Foo
- Bar
 ---
 baz

*

  Foo
  ===

*

  Bar
  ---

  baz

Lists

An extra line break is added between lists. 

- [x] foo
 - [ ] bar
 - [x] baz
- [ ] bim

* [x] foo
  * [ ] bar
  * [x] baz

* [ ] bim

Custom start position in numeric list currently is not supported.

123. Item 1
124. Item 2
125. Item 3

1. Item 1
2. Item 2
3. Item 3

Italics

Extra spacing can be added around certain styles.

 5*6*78

 5 *6* 78

XML Characters

The following XML character are always escaped. You can control this by using the entity_escaping directive.

Directives

File directives are supported via our API (inline is not supported). Directives are specified in the following format:

API Parameter

smartling.[directive_name] = [value] 

Here are examples of supported directives for plain text files:

smartling.no_translate_keys = title, example.custom.text

smartling.yfm_block_enabled = on

—
layout: post
title: Blogging Like a Hacker
description: This is a description
—