agentleFS
pedroiff0pedroiff0/awesome-skills/skills/content-i18n/mt-markup-preserving-translation/SKILL.md

mt-markup-preserving-translation

Skill1 starsChanged 49 days agoMITView on GitHub

Translate Markdown/Obsidian/Quartz content with LibreTranslate while preserving wikilinks, embeds, URLs, tables, HTML blocks, proper nouns, and canonical section titles. Use for any "translate this vault/site" task.

The file

We split this skill into the rules it gives an agent

1 rule. About 0 are common, 0 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈0

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Never overwrite existing en/*.md flat files (manual pages) even with --overwrite.

    line 42

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Markup-preserving MT translation

The engine (LibreTranslate) WILL corrupt your source if you hand it raw Markdown. The fix is a single principle: never let the engine see anything structural — split the line, keep markup/URLs/wikilinks/proper-nouns/HTML literal, translate only the plain-text spans between them, rejoin.

Core strategy (apply in this order, per line)

  1. Split positional, not placeholder. Find protected spans (wikilinks, embeds, proper nouns, inline HTML) with re.finditer, keep them literal, translate the text BETWEEN them. Placeholders (§N§, ZZNZZ, \x00N\x00) are silently mangled by the engine (see references/libretranslate-notes.md) — do NOT use them for anything except bold/italic (which uses real HTML tags: <strong>/<em> with format=html).
  2. Wikilinks/embeds — capture with !?\[\s*\[\s*[^\[\]]*\]\s*\]\s* (the FIRST [ is mandatory so the ! of embeds is kept; a leading \s* before [ drops the ! and yields broken [[[). Keep literal — engine turns ![[assets/b/b.pdf|B]] into [ [ [assets/b/b.pdf|Banner]].
  3. Internal links — \[([^\]]*)\]\(([^)]+)\); translate only the anchor text, re-emit with the ORIGINAL url. Engine mangles URLs (integrra.iff.edu.br/p/x -> https: / / integrra ... / x).
  4. Proper nouns — positional, NOT to the engine. "Soja" -> "Soya", "Ana Cecília Soja" -> "Chapitre 1" if seen. Stash as literal spans (longest-first ordering matters).
  5. Tables — split each row on |, translate per cell, rejoin. Engine drops inner | and merges columns if given the whole row.
  6. Bold/italic — convert **x**-><strong>x</strong>, *x*-><em>x</em>, call engine with format=html, revert tags after. Engine preserves real HTML tags.
  7. Headings — strip ## (+ emoji) as a prefix, re-prepend after translate; clean a leading ^[-\*#]\s+ the engine may inject.

Inline HTML blocks (carousels etc.) — the hard one

Non-greedy regex (<\w+...>.*?</\w+>) is NOT enough for nested tags: it matches the smallest tag and leaves the outer wrapper (<div class="media-carousel">, <a href=...>) to be fed to the engine, which then corrupts attributes and spaces URLs (< div classe = "media-carrousel" >, href = classe "/ pt-br / ... " = "carrousel-glide").

Fix (see references/carousel-html.md): extract balanced-HTML blocks by TAG DEPTH before translating the line, preserve them, then translate ONLY the inner text (e.g. slide-caption / alt) while keeping href/src/class literal. A depth-counting loop (push on open, pop on close, emit span when depth returns to 0) is the correct tool — regex cannot balance tags.

Frontmatter titles & section titles

  • Translate title/description per language, keep the slug/URL intact (only the DISPLAY changes).
  • The engine mis-contexts academic terms: "Pesquisa" (pt) -> "Search" (en) when it should be "Research". For 1st-level index.md of known sections, force canonical titles via a SECTION_TITLES map (research->Research/Investigación/Recherche, media->Media/Medios/Médias, ...). Detect by rel.name == "index.md" and rel.parent.name == section.

i18n slug rule (Quartz)

Keep slugs IDENTICAL across languages; only the language prefix in the URL changes. Do NOT translate folder/file names — the LanguageToggle swaps only the prefix segment, so renaming slugs breaks it (and causes "duplicate slug" build errors when en/X.md and en/X/index.md both exist). When emitting en/<dir>/index.md, skip if en/<dir>.md already exists (manual page at that slug).

Disclaimer

Append a per-language "translated automatically" notice (citing the translator, e.g. tools/translate_quartz.py) AFTER the last section. Do not translate it.

Guardrails when emitting

  • Never overwrite existing en/*.md flat files (manual pages) even with --overwrite; skip them (lang == "en" and out_path.name != "index.md").
  • Sanitize spacing AFTER translate but NEVER insert a space between [[ or ![ (breaks embeds): space before [ only if the preceding char is a letter or ) (not ! or [).

Support files

  • scripts/translate_quartz.py — worked, validated example for a Quartz/Obsidian vault (the full pipeline above).
  • references/libretranslate-notes.md — engine quirks (placeholder failures, emoji, headings, tables, format=text vs html, Docker).
  • references/verified-regexes.md — the exact regexes that survived real runs.
  • references/carousel-html.md — balanced-HTML extraction + translate-inner-text for carousels.
  • references/html-blocks-titles.md — carrossel/HTML-by-depth protection, canonical section titles (Pesquisa->Research, not Search), fix_bold post-process, and the "verify TSX with npm run check; the GitHub deploy transpile is permissive" pitfall.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.