Jak překládat soubory Markdown bez poškození kódu, odkazů nebo front matter

Chcete-li přeložit soubor Markdown, přeložte prózu a strojovou část nechte nedotčenou: klíče front matter, kód, URL adresy, popisky odkazů, značky komponent a popisky poznámek pod čarou se musí vrátit bajt po bajtu. Poté zkontrolujte tři věci, které i pečlivý překlad stále rozbíjí: odkazy na nadpisy, komentáře v kódu a – v čínštině, japonštině nebo korejštině – mezery kolem tučného textu a číselných rozsahů.

Přeložili jsme 73řádkovou stránku MDX do zjednodušené čínštiny devětkrát pomocí lokálního modelu, se třemi různými prompty, a každý výsledek zkontrolovali skriptem. Části, o které lidé obvykle mají obavy, přežily ve všech devíti bězích: kód, inline kód, URL adresy, tabulka, komponenta JSX a seznam úkolů. Tři další věci se pokazily. Odkaz na nadpis se rozbil ve všech devíti bězích. Komentáře v kódu byly přeloženy ve všech šesti bězích, které odeslaly celý soubor, včetně tří běhů, kde prompt říkal, aby se kód neměnil. A prompt, který skryl syntaxi za zástupné symboly, což zní jako nejbezpečnější možnost, rozbil front matter ve všech třech svých bězích.

Rychlá odpověď: Co překládat a co nechat být

Vše ostatní je běžný text: odstavce, položky seznamu, buňky tabulek a blokové citace.

Co jsme testovali

Napsali jsme sample-source.mdx, dokumentační stránku pro fiktivní čtečku s názvem Shelfmark. Je napsána ve stylu MDX, který používají Docusaurus a podobné dokumentační weby, s jedním příkladem každého konstruktu z tabulky výše, plus dvoumezerový pevný zlom řádku, tučný odkaz, tučnou frázi končící závorkou, dva číselné rozsahy zapsané pomocí pomlček a odkaz na stránce na nadpis „Keep one glossary for the whole book.“

Poté jsme požádali lokální model, aby jej přeložil do zjednodušené čínštiny třemi způsoby:

1. Celý soubor. Vložte celý soubor a požádejte o vrácení přeloženého souboru.
2. S instrukcemi. Totéž plus šest pravidel: zachovat klíče front matter, nic neměnit uvnitř kódu, zachovat URL a definice odkazů, zachovat importy, značky a komentáře, zachovat označení poznámek pod čarou a značky upozornění a překládat nadpisy, text odkazů, alternativní text a atribut title.
3. S ochranou. Nahradit kód, inline kód, URL, značky, komentáře, označení poznámek pod čarou, značky upozornění a řádky front matter číslovanými zástupnými symboly, jako je ⟦12⟧, přeložit zbytek a poté vrátit originály zpět. Hodnoty title a description zůstaly odhalené pro překlad, a jak se ukázalo, stejně tak řádky --- front matter a uzavírací uvozovky.

Model byl Qwen 3.6 27B (Q4_K_M) v LM Studio, s vypnutým myšlením a teplotou 0,3, na Apple M4 Max s 64 GB paměti. Každou podmínku jsme spustili třikrát, celkem devět běhů, dne 25. října 2026. Skript je run_llm_markdown_test.py a všech devět výstupů je zveřejněno bez úprav; README uvádí každý soubor. Pokud jste nikdy nenastavovali lokální model, náš průvodce překladem s lokálním LLM pokrývá nastavení.

Byl to malý test jednoho modelu, jednoho jazykového páru a jedné stránky. Ukazuje, které problémy nastávají a jak je odhalit. Neřadí modely ani výzvy.

Výsledek: Syntaxe přežila; odkazy a rozhodnutí ne

Každý výstup jsme zkontrolovali pomocí check_markdown_translation.py a každý vykreslili pomocí remark a kompilátoru MDX. Úplný výstup kontroly je v check-results.txt a results.csv obsahuje jeden řádek na běh.

První řádky jsou dobrá zpráva. Tento model vrátil syntaxi Markdown neporušenou, když jsme vložili celý soubor; v kódu, URL ani tabulkách jsme nenašli nic k opravě. Poslední čtyři řádky ukazují, kde je práce, a žádný z nich se při sestavení webu neprojeví jako chyba.

1. Přeložené nadpisy rozbíjejí odkazy na ně

Ukázka odkazuje na svou sekci slovníčku pomocí [glossary section](#keep-one-glossary-for-the-whole-book). Každé spuštění přeložilo nadpis, jak má, a každé spuštění zachovalo cíl odkazu, jak má. Výsledkem je odkaz na ID, které už neexistuje.

Většina nástrojů pro Markdown vytváří ID nadpisů z textu nadpisu. Dokumentace Pandocu popisuje identifikátor jako „založený na textu nadpisu“ a Docusaurus varuje, že můžete chtít změnit nebo přeložit nadpis „bez aktualizace stávajícího ID, abyste předešli rozbití odkazů“. Jakmile nadpis zní 为整本书保留一个术语表, jeho vygenerované ID je čínské a #keep-one-glossary-for-the-whole-book nikam nescrolluje. Stránka se stále sestaví, takže vám nic neřekne.

To neopravíte ani úpravou odkazu po překladu. Napříč devíti spuštěními model napsal stejný nadpis čtyřmi různými způsoby, takže vygenerované ID by se změnilo při každém dalším překladu. Oprava patří před překlad: každému nadpisu, na který se odkazuje, dejte pevné ID.

• V Docusaurus MDX použijte ## Keep one glossary for the whole book {/* #keep-one-glossary */}. Docusaurus poznamenává, že starší forma {#id} „už není platná syntaxe MDX“ a jeho příkaz write-heading-ids přidá ID do každého dokumentu za vás.
• V Pandocu a v procesorech Markdown, které následují PHP Markdown Extra, použijte {#keep-one-glossary} na konci nadpisu.

ID pak zůstane stejné v každém jazyce a kontroler jej považuje za cíl odkazu.

2. Komentáře v kódu se překládají a viditelný řetězec ne

Ukázka obsahuje komentář shellu a komentář YAML:

library:
  name: "My books"   # shown in the sidebar
  sort: title

Všech šest spuštění, která odeslala celý soubor, přeložilo oba komentáře, včetně tří, kde výzva říkala „Neměňte nic uvnitř bloků kódu ohraničených plotem“. Samotný kód zůstal ve všech devíti spuštěních nedotčen. Mezitím "My books", o kterém komentář říká, že se zobrazuje v postranním panelu, zůstalo ve všech devíti spuštěních anglicky. Model udělal opak toho, co lokalizovaná stránka potřebuje: přeložil poznámku pro vývojáře a ponechal popisek, který uvidí čtenáři.

Ani jedna volba není špatná ve všech případech. U tutoriálu, jehož čtenáři budou kód kopírovat do vlastního projektu, překlad komentářů pomáhá. U referenční dokumentace, jejíž kód musí odpovídat repozitáři, způsobí, že stránka nebude souhlasit se zdrojem. Rozhodněte se jednou pro projekt a hodnoty řetězců v konfiguračních příkladech zkontrolujte ručně, protože žádný nástroj nerozliší zobrazovaný popisek od identifikátoru. Kontroler proto hlásí změny pouze v komentářích jako varování.

3. Zdánlivě bezpečná metoda rozbila front matter

Chráněná podmínka splnila, co slíbila: všech 32 zástupných symbolů se vrátilo ve všech třech spuštěních, takže kód, URL a tagy byly dokonale obnoveny. Náš skript však nechal dvě drobnosti mimo zástupné symboly: řádek ---, který otevírá front matter, a uzavírací uvozovku za přeloženým názvem a popisem. Model je ve všech třech spuštěních vynechal. Soubor začínal takto:

title: "导出您的书库
description: "在更换设备之前，请备份您的笔记和书籍。
slug: export-library

Bez úvodního --- už parser Markdown nevidí front matter. Přečte šest řádků YAML plus uzavírací --- jako nadpis, takže stránka by začínala velkým nadpisem obsahujícím YAML. Stále se to zkompilovalo jako MDX. Ani vrácení --- nestačí: parser YAML odmítne dvě neuzavřené uvozovky.

Ponaučení není vyhýbat se zástupným symbolům. Je to, že cokoli necháte odhalené, se může vrátit změněné, a že front matter by se modelu neměl posílat jako součást stránky vůbec. Parsujte ho, posílejte pouze hodnoty určené čtenáři (title, description) jako samostatné řetězce a překlady zapisujte zpět do původní struktury. To je pár řádků kódu a odstraní to celou třídu problémů.

Tučný text a rozsahy v čínštině, japonštině a korejštině

Další dva problémy se v našich devíti spuštěních nikdy neobjevily, ale stojí za kontrolu, protože tiše rozbíjejí stránky, a oba zasáhly i blog BookTranslatoru. Blog je napsán v MDX a strojově přeložen do 27 jazyků a při jednom plánovaném překladovém běhu dva korejské články neprošly naší strukturální kontrolou třikrát po sobě. Příčinami byly dva vzory níže.

Tučné písmo končící interpunkcí. CommonMark rozhoduje, zda ** může otevřít nebo zavřít tučné písmo, podle znaků na obou stranách. Zavírací **, které následuje hned po interpunkci, musí být následováno mezerou, interpunkcí nebo koncem řádku; jde o pravidlo pravého okraje. Angličtina tam vždy má mezeru. Čínština, japonština a korejština často ne. Takže 打开**设置 → 导出（测试版）**并选择 zobrazí doslovné hvězdičky, protože tučné písmo končí plnovou závorkou a bezprostředně po něm následuje 并. Stejný řádek bez závorky se vykreslí tučně, stejně jako řádek s mezerou za **. Stejný problém má i tučný odkaz, protože odkaz končí na ): 点击**[导出](./export-options.md)**打开 selže, stejně jako korejské **[API](./api.md)**는.

Náš model náhodou vložil mezeru na obě strany každé tučné fráze, takže jeho výstup se vykreslil správně. Editor, který později tyto mezery odstraní, aby dodržel čínské typografické zvyklosti, chybu vrátí. Všech sedm variant si můžete vyzkoušet v render-cases.md.

Číselné rozsahy s vlnovkou. Čínský a japonský text často zapisuje rozsahy jako 3~5. Weby s GitHub Flavored Markdown postavené na remarku ve výchozím nastavení mění jednotlivé vlnovky na přeškrtnutí: volba singleTilde v remark-gfm je true, pokud ji nezměníte. Dva rozsahy v jednom odstavci, například 需要 3~5 分钟，生成 10~20 MB 的文件夹, se vykreslí s přeškrtnutým textem mezi nimi. Náš vzorek používal pomlčky a osm běhů si je ponechalo, zatímco devátý napsal 3 到 5. Žádejte pomlčky nebo slova v rozsazích, nebo nastavte singleTilde: false ve své konfiguraci remarku.

Strukturální kontrola označí oba vzory. Chcete-li ověřit, co se skutečně vykreslí, render_check.mjs spočítá tučné písmo, kurzívu, přeškrtnutí a zbývající hvězdičky ve zdroji a překladu a zkusí kompilaci MDX:

npm install @mdx-js/mdx@3 unified@11 remark-parse@11 remark-gfm@4
node render_check.mjs source.mdx translated.mdx

Méně uzlů tučného písma nebo více doslovných hvězdiček v překladu znamená, že se některé zvýraznění přestalo zavírat.

Postup, který obstojí

1. Nejprve opravte ID nadpisů. Přidejte explicitní ID ke každému nadpisu, na který něco odkazuje, v syntaxi, kterou váš generátor webu podporuje. Udělejte to ve zdrojovém jazyce, jednou, a zaveďte do repozitáře, než se cokoli přeloží.

2. Vyjměte front matter ze stránky. Překládejte pouze hodnoty určené čtenáři, jako title a description, jako samostatné řetězce, a zapište je zpět do původního YAML.

3. Rozhodněte o politice kódu. Komentáře přeložené nebo ne; zobrazované řetězce v konfiguračních příkladech přeložené nebo ne. Zapište to do svého překladového slovníku vedle názvů produktů, které se nesmí měnit, jako je Shelfmark v našem vzorku.

4. Přeložte tělo. Použijte nástroj, který parsuje Markdown, nebo pošlete celou stránku s explicitními pravidly. V našem testu odeslání celé stránky zachovalo syntaxi; pokud používáte zástupné symboly, chraňte celé konstrukce a nenechávejte nic napůl odhalené.

5. Spusťte strukturální kontrolu.

   python3 check_markdown_translation.py source.mdx translated.mdx --keep Shelfmark
   

   Porovnává klíče a hodnoty front matter, importy, bloky kódu, inline kód, cíle odkazů, definice referencí, úrovně nadpisů, cíle odkazů v rámci stránky, JSX tagy a atributy, komentáře MDX, značky admonic, popisky poznámek pod čarou, tvar tabulek, zaškrtávací políčka seznamu úkolů, pevné zlomy řádků, zvýraznění, která se nemohou zavřít, rozsahy s vlnovkou a termíny, které chcete zachovat. Nehodnotí kvalitu překladu.

6. Zkontrolujte vykreslení pro cílové jazyky CJK pomocí render_check.mjs a přidejte mezeru za každé zavírací **, které následuje po interpunkci.

7. Sestavte web a klikněte na odkazy. Otevřete stránku v každém jazyce, klikněte na každý odkaz v rámci stránky a přečtěte si konfigurační příklady. Úspěšné sestavení dokazuje jen to, že se soubor zkompiluje.

Pro dokumentaci, kde záleží na přesnosti, se nad rámec tohoto postupu uplatní kroky s terminologií a revizí z našeho pracovního postupu technického překladu.

Kam zapadá BookTranslator

Překladač TXT od BookTranslator přijímá soubory .txt, .md a .mdx. Podle produktové stránky je překládá se zachováním odstavců, zlomů řádků, speciálních znaků a struktury textu a velké soubory rozděluje na segmenty pro překlad s ohledem na kontext, takže můžete nahrát celý manuál nebo knihu napsanou v Markdownu, místo abyste je vkládali po částech.

Produktová stránka nepopisuje speciální zacházení s front matter, bloky kódu nebo komponentami MDX a tento vzorek jsme pro tento článek přes BookTranslator neproháněli. Ať už použijete jakýkoli nástroj, proveďte kroky 1 až 3 před překladem a kroky 5 až 7 po něm. Nadpis bez pevného ID stále ztrácí odkazy a rozsah zapsaný vlnovkami se stále mění na přeškrtnutí. Pokud vydáváte knihu ve více jazycích, náš průvodce samovydáváním ve více jazycích pokrývá zbytek této práce.

Získejte testovací soubory

Vše z tohoto testu lze zdarma znovu použít:

• sample-source.mdx: anglický vzorek o 73 řádcích;
• check_markdown_translation.py: strukturální kontrola (pouze standardní knihovna Pythonu);
• render_check.mjs a render-cases.md: kontrola vykreslení a sedm testovacích případů CJK;
• run_llm_markdown_test.py: tři podmínky promptu pro jakýkoli lokální server kompatibilní s OpenAI;
• devět výstupů ve složce outputs, spolu s check-results.txt a results.csv.