Skip to main content
Markdown

Learn about translating Markdown files (.md, .markdown) with Transifex

Nina Eleftheriadou avatar
Written by Nina Eleftheriadou
Updated over a week ago

File Extension(s)

.md, .markdown

i18n type(s)

GITHUBMARKDOWN

Markdown is a handy way to write for the web, as it’s easy to read and write. Transifex supports standard Markdown syntax (as defined by John Gruber) and GitHub Flavored Markdown (GFM). Additionally, YAML front matter is supported.

As with HTML files, Transifex hides unnecessary syntax in the Editor while preserving them in the translated file.


YAML front matter headers

If you use a static site generator such as Jekyll, you might have YAML front matter blocks with metadata or other variables in your Markdown files. Transifex supports both pre-defined variables (e.g., title) and custom variables. You’ll be able to translate values from these variables just like content from the body of your Markdown file.

For example, if you had this front matter block:

---
title: Paper Products
description: Products made of 100% recycled paper
tags: paper products, sales
visible: true
products:
- top-level: Multi-purpose paper
nested-products:
- name: 8.5 x 11 paper
price: $4
- name: A4 paper
price: $5
- top-level: Boxes
nested-products:
- name: 24 x 24 x 24 shipping boxes
price: $3.50
---

You’ll be able to translate these strings:

Paper Products
Products made of 100% recycled paper
paper products
sales
Multi-purpose paper
8.5 x 11 paper
$4
A4 paper
$5
Boxes
24 x 24 x 24 shipping boxes
$3.50


Lists

Transifex treats each line in a list as a single string and hides list markers in the Editor.

This list:

* Item 1
* Item 2
* Item 2a
* Item 2b

Will produce the following four strings in Transifex:

Item 1
Item 2
Item 2a
Item 2b

Task lists

Each item in a GFM task list will also be treated as a single string, with the checkbox elements ([ ] and [x]) appearing in the Editor.

This task list:

- [x] @mentions, #refs, [links](), **formatting**, and <del>tags</del> supported
- [x] list syntax required (any unordered or ordered list supported)
- [x] this is a complete item
- [ ] this is an incomplete item

Will produce the following four strings in Transifex:

[x] @mentions, #refs, [links](), **formatting**, and <del>tags</del> supported
[x] list syntax required (any unordered or ordered list supported)
[x] this is a complete item
[ ] this is an incomplete item


Code blocks

There are multiple ways to produce code blocks with Markdown. Whether you use spaces, tabs, or ` to denote a code block, Transifex will treat each block as a single string.

By default, Transifex will check to ensure the number of spaces or tabs at the beginning of each line is preserved in the translation. If a translation has a different number of spaces than the source, the translator will see a Warning message, though you can customize this behavior in the translation check settings.


Tables

Tables are not part of the core Markdown spec defined by John Gruber, but Transifex supports them. Transifex will handle tables differently depending on whether it’s an HTML table or a GitHub Flavored Markdown table.

HTML tables like the one below will be treated as a single string.

<table>
<tr>
<th>First Name</th>
<th>Last Name</th>
</tr>
<tr>
<td>Mark</td>
<td>Zuckerberg</td>
</tr>
<tr>
<td>Michael</td>
<td>Scott</td>
</tr>
</table>

However, Transifex treats each cell in a GFM table as a standalone string. This table:

First Name | Last Name
---------- | ----------
Mark | Zuckerberg
Michael | Scott

Will produce the following six strings in Transifex:

First Name
Last Name
Mark
Zuckerberg
Michael
Scott


HTML

In general, block-level elements in HTML are treated as a single string. This means large blocks of plain HTML will result in big source strings that are more difficult to translate and you won’t be able to take advantage of Translation Memory for those strings.


However, the HTML elements will be hidden from translators' view and only the translatable content will be exposed to the editor. Please check here for more details.

Parser Behavior When Pulling Translations via the API/CLI or Exporting Translations via the UI

The following table outlines what occurs to untranslated, unreviewed and un-proofread strings when using the API, CLI or UI to manipulate translation files:

githubmarkdown.jpg#asset:7311

📝 Note: Proofreading needs to be enabled as an option for this logic to take effect. To learn how to enable proofreading click here.


Default placeholders

These are the default place holders that you could have in your file and they will be recognized :

match: ['%1$s', '%(key1)s', '%s', '%d', '%.2f', '%-5d', '%+2d']


Additional Information


💡Tip

Looking for more help? Get support from our Transifex Community Forum!

Find answers or post to get help from Transifex Support and our Community.

Did this answer your question?