Extension | .md, .markdown |
Smartling Identifier | MARKDOWN |
Example File | (see examples below) |
Resources |
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.
Visual context is supported for this file type.
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. 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
} |
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 yaml_front_matter 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.
Original | Downloaded |
<script type="text/javascript">
// JavaScript exampledocument.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 |
XML Characters
The following XML character are always escaped. You can control this by using the entity_escaping directive.
Character (character name) | Escape sequence |
< (less-than) | < |
> (greater-than) | > |
& (ampersand) | & |
' (apostrophe or single quote) | ' |
" (double-quote) | " |
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 markdown files:
Exclude Markdown Code
Directives | markdown_code_notranslate |
Values |
|
Smartling Translate Supported | Yes |
Description | This directive controls if Markdown code blocks are ingested for translation. When set to on/true, Markdown code blocks are not ingested into Smartling for translation. |
Examples | smartling.markdown_code_notranslate=on |
Process Frontmatter blocks
Directives | yfm_block_enabled |
Values |
|
Smartling Translate Supported | Yes |
Description | Enables the Yaml Front Matter block processing for the markdown. Must be used with yaml_front_matter. Used only as an external api parameter. |
Examples | smartling.yfm_block_enabled=yes |
Translate Frontmatter blocks
Directives | yaml_front_matter |
Values |
|
Smartling Translate Supported | Yes |
Description | 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 = title, example.custom.text |
Examples | smartling.yaml_front_matter = on Smartling will capture content between each yaml_front_matter code example smartling.yaml_front_matter = on— layout: post title: Blogging Like a Hacker description: This is a description — |
Exclude Frontmatter block keys
Directives | no_translate_keys |
Values | Comma-separated list of YAML Front Matter key paths to exclude from translation.
|
Smartling Translate Supported | Yes |
Description | Excludes some of Yaml Front Matter block keys from translation. Used only when smartling.yfm_block_enabled is activated. Used only as an external api parameter. |
Examples | smartling.no_translate_keys = title, example.custom.text, example.custom.variables.[2], items.[1].value |
Variant Strategy
Directive | variants_strategy |
Values |
(case-insensitive) |
Smartling Translate Supported | Yes |
Description | This directive can only be used as an API parameter. context_match: enables ICE variants functionality. repetition_indexed: enables the "string indexes as variants for repeated strings" functionality that is the default behavior for business docs. |
Examples | smartling.force_block_for_tags=br Enables string separation by <br> tags |
Standard Placeholder Format
Directive | placeholder_format |
Values | NONE; C; IOS; PYTHON; JAVA; YAML; QT, RESX |
Smartling Translate Supported | Yes |
Description | Used to specify a standard placeholder format. |
Examples | smartling.placeholder_format = IOS Specifies iOS-style placeholders for the file. |
Custom Placeholder Format
Directive | primary_placeholder_format_custom |
Values | 1) Custom Java regular expression. |
Smartling Translate Supported | Yes |
Description | Specifies a custom placeholder format. Any text in your file matching the regular expression you provide will be captured as a placeholder. |
Examples | smartling.primary_placeholder_format_custom = REGEX smartling.primary_placeholder_format_custom=\{([^}]+)\} Any characters surrounded by curly brackets, e.g., {first name}, will be treated as a placeholder. |
See Placeholders in Resource Files for more on placeholders.
Pseudo Translation
Directives | pseudo_inflation |
Values | integer - Accepted values are 0 - 100 |
Description | Sets the percentage by which original strings are inflated when downloading pseudo translations. If this directive is not set, pseudo translations are 30 percent longer than the original strings. |
Examples | smartling.pseudo_inflation = 80 Downloaded pseudo translations will increase the length of original strings by 80 percent. |
Trim Whitespace
Directive | whitespace_trim |
Values | on|yes|true or off|no|false or leading|trailing The default value is on. |
Smartling Translate Supported | Yes |
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. Whitespace is optionally trimmed from content then re-inserted on download for convenience so that translators do not have to manage the extra spaces. However, content owners may want to retain surrounding whitespace so that translators can 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 only be used 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 |