libretranslate-markdown-i18n

LibreTranslate Markdown i18n

Self-host LibreTranslate (Docker) and translate Markdown/Obsidian content while keeping the markup intact. The naive approach — sending raw Markdown to the MT engine — corrupts the output: emojis vanish or get "translated" into words, #/## headings get rewritten, **bold** grinds into the text, and Obsidian ![[embed]] wikilinks turn into garbage ("Chapitre 1"). This skill encodes the protection technique that makes it safe.

When to use

• "Translate this vault / these notes / the pt-br content into en/es/fr"
• Building i18n for a Quartz site, Obsidian publish, or static Markdown docs
• Any MT task where the source is Markdown with frontmatter and/or wikilinks

1. Stand up LibreTranslate (Docker)

docker run -d --name libretranslate -p 5000:5000 \
  -e LT_LOAD_ONLY=pt,en,es,fr \
  -e LT_UPDATE=false \
  libretranslate/libretranslate:latest

• LT_LOAD_ONLY limits downloaded models (faster first start; ~1-2 min to HTTP 200).
• LT_UPDATE=false stops it phoning home for updates.
• Wait for curl -s -o /dev/null -w '%{http_code}' http://localhost:5000/ -> 200.
• Translation endpoint: POST http://localhost:5000/translate with form fields q, source, target, format=text.

2. The protection technique (CORE)

Never send raw Markdown. Per line:

1. Split frontmatter (---...---) and preserve it verbatim, EXCEPT you MAY translate the display-only fields title and description per language (see 3c). Never translate slug/aliases/URL-bearing fields — those must stay IDENTICAL across languages so the language toggle keeps working. Preserve YAML key order and formatting where possible.
2. Separate block prefix from text. A heading/list/callout line like ## 🗓️ Sobre o evento must be split into prefix ## 🗓️ (markup + adjacent emoji) and text Sobre o evento. Translate ONLY the text. The MT engine must never see ## or the emoji.
   • Regex for the prefix: ^(?:#{1,6}\s+|>\s*|[-*]\s+|\d+\.\s+|!\s*)?<EMOJI_CLASS>* where EMOJI_CLASS covers U+1F000–U+1FAFF, U+2600–U+27BF, U+2190–U+21FF, U+2B00–U+2BFF, U+FE00–U+FE0F, U+2700–U+27BF, \u200d, \u20e3.
3. Wikilinks never reach the MT engine. Extract !?\[\[[^\]]+\]\] from the text and keep them literal (split the line on them, translate only the text between). Do NOT use a placeholder for wikilinks — the engine sometimes deletes long wikilinks entirely.
4. Bold/italic/internal links (**[...]**, *[...]*, [anchor](pt-br/...)) use a placeholder §N§ (see pitfalls).
5. Rejoin prefix + translated text. Guarantee one space after a heading/emoji prefix if the engine dropped it. Strip a leading - /# /* the engine may inject at line start.