Links in Markdown syntax and how to localize them

Localization matters

Let me start with something you will hear a lot from me: Localization is much more than just translating. It is not a fancy word, it is simply more than just translating. When localizing websites, you need to know the language or syntax used (HTML, Markdown, etc.) in order to correctly localize different elements, such as links, snippets, formatting tags, and so on.

Links in Markdown syntax

An error I see quite often is the incorrect localization of links written in Markdown syntax, which look like this:

This is a sentence [with a hyperlinked text](URL the link directs to).

This will render this way in the live content:

This is a sentence with a hyperlinked text.

The use of brackets and parentheses is not random, they play a very important role and must be kept as they are, but you can translate the text within brackets and even localize the URL within parentheses. However, if you add anything, even a space or a period, between the closing bracket ] and the opening parentheses (, the code will be broken and you will be showing everything to your readers, including the brackets, the parentheses and the URL:

This is a sentence [with a hyperlinked text incorrectly localized] (URL the link directs to).

Do you imagine having that in your live content? It looks bad, very bad. It shows lack of knowledge, concern or a good QA phase (or all of them). And I have seen it lots of times on different localized websites.

You can learn more about links in Markdown syntax and test your Markdown links with a preview of the live content.

All issues have a solution

Knowing the syntax used to write the page you are translating will help a lot when localizing links and other bits of code, but the human eye isn’t perfect. However, a good localizer will always have a tool to make sure they never overlook an error like this one.

My favorite QA tool for this (and many more cases) is Xbench, and I have been using it for more than 9 years, so I know quite well how to take the most out of it. This simple QA check will flag every time there is a space between the closing bracket and the opening parentheses:

  • Source: \]\(
  • Target: \] \(
  • Search mode: Regular Expression
  • PowerSearch: On

Or if you prefer, you can search for the lack of “](” in the translation, which will also flag it if there is any text between both symbols:

  • Source: \]\(
  • Target: -“\]\(“
  • Search mode: Regular Expression
  • PowerSearch: On

This simple check will ensure all your Markdown links are correctly localized and no code fragment is shown to the readers. It’s that easy. Xbench (and other QA software) is a great tool if you know how to use it.