Preparing & Translating Supported File Types

  1. Smartling Help Center
  2. Using Smartling
  3. Preparing & Translating Supported File Types

Markdown

 

Extension .md, .markdown
Smartling Identifier MARKDOWN
Example File (see examples below)
Resources GitHub Flavored Markdown Spec

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.

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)

Original  Downloaded 
# 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:

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

 

Formatting of code blocks is returned with an indentation style:

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

 

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.

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

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

 

 
 okay

 

Original Downloaded 
<script>
foo
</script>1. *bar*
 
1\. \*bar\*

 

Style Tags

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

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

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

 

Blockquotes

Blockquotes can be merged.

Original Downloaded 
> foo

> bar
 
> foo
>
> bar

 

Bullets With Headings

Extra line breaks can sometimes be returned. 

Original Downloaded 
- # Foo
- Bar
 ---
 baz
 
*

  Foo
  ===

*

  Bar
  ---

  baz

 

Lists

An extra line break is added between lists. 

Original Downloaded 
- [x] foo
 - [ ] bar
 - [x] baz
- [ ] bim
 
* [x] foo
  * [ ] bar
  * [x] baz

* [ ] bim

Custom start position in numeric list currently is not supported.

Original Downloaded 
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.

Original Downloaded 
 5*6*78
 
 5 *6* 78

 

Directives

Format

smartling.[directive_name] = [value]

 

Parsing of strings in markdown files can also be further customized with Smartling directives.  For this file format directives can only be specified for the entire file via the API.

 

placeholder_format_custom

 

See custom placeholder format article for more information.

 

smartling-cli files push "markdown.md" --type markdown --directive placeholder_format_custom="\{\{.+?\}\}"

 

primary_placeholder_format_custom

Values 

Custom Java compatible regular expression.
Description  Used to define custom placeholders in the raw Markdown source (before the actual parsing). This can be used only as an external api request parameter.
Examples 

smartling.primary_placeholder_format_custom=\*_\w+_\* 

 

markdown_html_strategy

Values 

default | restore (case-insensitive)
Description  The restore value enables the Markdown parser to retain original HTML tags in the translated markdown. This can be used only as an external api request parameter.
Examples 

smartling.markdown_html_strategy=restore

 

markdown_code_notranslate

Values 

true | false
Description 

Used to change default behavior for specific markdown.

By default, this is true, meaning all markdown code strings are excluded from translation.
Examples 

smartling.markdown_code_notranslate=false
Captures code strings for translation.

 

yfm_block_enabled

Values 

on|yes|true or off|no|false 

The default value is off
Description 

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.

The option for recognizing Frontmatter allows you to include the YAML Frontmatter (yfm) block for translation. 

To exclude some of YAML Frontmatter variables, the following directive can be used:
smartling.no_translate_keys = <comma-separated keys>,
for example:

smartling.no_translate_keys = title, example.custom.text
Examples  
 smartling.yfm_block_enabled = on

—
layout: post
title: Blogging Like a Hacker
description: This is a description
—
Content between each — is ingested for translation

 

whitespace_trim

Values 

on|yes|true or off|no|false or leading|trailing

The default value is on
Description 

A whitespace is any character or series of characters that represent horizontal or vertical space in typography. When rendered, a whitespace character is not a visible mark, but does occupy an area or space on a page.

Although whitespaces are necessary within a string (typically to separate words), unnecessary whitespaces can be found at the start of a string (leading) and at the end of a string (trailing).

With this directive, you can trim whitespaces, as it enables or disables whitespace trim management for the ingested strings.

By default, the leading and trailing whitespaces are trimmed.

You can choose to disable trimming or specify trimming for leading or trailing whitespaces.

The directive can be used inline or as the API request parameter.
Examples 

smartling.whitespace_trim=on

Smartling will trim leading and trailing whitespaces (default)

smartling.whitespace_trim=off

Smartling will not trim leading or trailing whitespaces

smartling.whitespace_trim=leading

Smartling will trim only leading whitespaces

smartling.whitespace_trim=trailing

Smartling will trim only trailing whitespaces

 

Was this article helpful?

Related articles