Kako prevesti Markdown datoteke bez kvarenja koda, poveznica ili front mattera

Za prijevod Markdown datoteke prevedite prozni tekst, a strojni dio ostavite netaknutim: ključevi front mattera, kod, URL-ovi, oznake poveznica, oznake komponenti i oznake fusnota moraju se vratiti bajt po bajt. Zatim provjerite tri stvari koje čak i pažljiv prijevod može pokvariti: poveznice na naslove, komentare u kodu i, u kineskom, japanskom ili korejskom, razmake oko podebljanog teksta i raspona brojeva.

Preveli smo MDX stranicu od 73 retka na pojednostavljeni kineski devet puta pomoću lokalnog modela, koristeći tri različita upita, i svaki rezultat provjerili skriptom. Dijelovi oko kojih ljudi obično brinu preživjeli su u svih devet pokretanja: kod, umetnuti kod, URL-ovi, tablica, JSX komponenta i popis zadataka. Tri druge stvari nisu prošle dobro. Poveznica na naslov pokvarila se u svih devet pokretanja. Komentari u kodu prevedeni su u svih šest pokretanja koja su poslala cijelu datoteku, uključujući tri pokretanja u kojima je uputa izričito zabranjivala diranje koda. A uputa koja je sakrila sintaksu iza zamjenskih oznaka, što zvuči kao najsigurnija opcija, pokvarila je front matter u svih svojih triju pokretanja.

Kratki odgovor: što prevesti, a što ostaviti netaknuto

Sve ostalo je običan tekst: odlomci, stavke popisa, ćelije tablice i blok citati.

Što smo testirali

Napisali smo sample-source.mdx, dokumentacijsku stranicu za izmišljenu aplikaciju za čitanje pod nazivom Shelfmark. Napisana je u MDX stilu koji koriste Docusaurus i slične dokumentacijske stranice, s jednim primjerom svake konstrukcije iz gornje tablice, plus tvrdi prijelom retka s dva razmaka, podebljanu poveznicu, podebljanu frazu koja završava zagradom, dva raspona brojeva napisana s crticama i poveznicu unutar stranice na naslov "Zadržite jedan rječnik za cijelu knjigu."

Zatim smo zamolili lokalni model da to prevede na pojednostavljeni kineski na tri načina:

1. Cijela datoteka. Zalijepite cijelu datoteku i zatražite prevedenu datoteku natrag.
2. S uputama. Isto, plus šest pravila: zadržite ključeve front mattera, ne mijenjajte ništa unutar koda, zadržite URL-ove i definicije referenci, zadržite uvoze, oznake i komentare, zadržite oznake fusnota i oznake upozorenja te prevedite naslove, tekst poveznica, alternativni tekst i atribut title.
3. Zaštićeno. Zamijenite kod, ugrađeni kod, URL-ove, oznake, komentare, oznake fusnota, oznake upozorenja i retke front mattera numeriranim čuvarima mjesta poput ⟦12⟧, prevedite ostatak, a zatim vratite originale. Vrijednosti title i description ostavljene su izložene za prijevod, kao i, kako se pokazalo, retci --- front mattera i završni navodnici.

Model je bio Qwen 3.6 27B (Q4_K_M) u LM Studiju, s isključenim razmišljanjem i temperaturom 0,3, na Apple M4 Max s 64 GB memorije. Svaki uvjet pokrenuli smo tri puta, ukupno devet pokretanja, 25. listopada 2026. Skripta je run_llm_markdown_test.py, a svih devet izlaza objavljeno je neuređeno; README navodi svaku datoteku. Ako nikada niste postavili lokalni model, naš vodič za lokalno prevođenje LLM-om pokriva postavke.

Ovo je bio mali test jednog modela, jednog jezičnog para i jedne stranice. Pokazuje koji se problemi događaju i kako ih uhvatiti. Ne rangira modele ni upute.

Rezultat: Sintaksa je preživjela; poveznice i odluke nisu

Svaki izlaz provjerili smo s check_markdown_translation.py i svaki prikazali pomoću remarka i MDX kompajlera. Cijeli izlaz provjere nalazi se u check-results.txt, a results.csv ima jedan redak po pokretanju.

Prvi redovi su dobra vijest. Ovaj model vratio je Markdown sintaksu netaknutom kada smo zalijepili cijelu datoteku; nismo pronašli ništa što treba popraviti u kodu, URL-ovima ili tablicama. Zadnja četiri retka su ono gdje je posao, a nijedan od njih ne prikazuje se kao pogreška kada gradite stranicu.

1. Prevedeni naslovi prekidaju poveznice na njih

Primjer povezuje na svoj odjeljak pojmova s [glossary section](#keep-one-glossary-for-the-whole-book). Svako pokretanje prevelo je naslov, kako i treba, i svako pokretanje zadržalo je cilj poveznice, kako i treba. Rezultat je poveznica na ID koji više ne postoji.

Većina Markdown alata generira ID-ove naslova iz teksta naslova. Pandocova dokumentacija opisuje identifikator kao "zasnovan na tekstu naslova", a Docusaurus upozorava da biste mogli poželjeti promijeniti ili prevesti naslov "bez ažuriranja postojećeg ID-a kako biste izbjegli prekidanje poveznica". Nakon što naslov glasi 为整本书保留一个术语表, njegov generirani ID je kineski, a #keep-one-glossary-for-the-whole-book ne vodi nikamo. Stranica se i dalje gradi, pa vas ništa ne obavještava.

To ne možete popraviti ni uređivanjem poveznice nakon prevođenja. Tijekom devet pokretanja model je napisao isti naslov na četiri različita načina, pa bi se generirani ID ponovno mijenjao sa svakim ponovnim prevođenjem. Rješenje pripada prije prevođenja: svakom naslovu na koji se povezuje dodijelite fiksni ID.

• U Docusaurus MDX-u upotrijebite ## Keep one glossary for the whole book {/* #keep-one-glossary */}. Docusaurus napominje da stariji oblik {#id} "više nije valjana MDX sintaksa", a njegova naredba write-heading-ids dodaje ID-ove svakom dokumentu umjesto vas.
• U Pandocu i u Markdown procesorima koji slijede PHP Markdown Extra upotrijebite {#keep-one-glossary} na kraju naslova.

ID tada ostaje isti na svakom jeziku, a provjeravač ga tretira kao cilj poveznice.

2. Komentari u kodu prevode se, a vidljivi niz ne

Primjer ima shell komentar i YAML komentar:

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

Svih šest pokretanja koja su poslala cijelu datoteku prevelo je oba komentara, uključujući tri u kojima je prompt glasio "Ne mijenjaj ništa unutar ograđenih blokova koda." Sam kod bio je netaknut u svih devet pokretanja. U međuvremenu "My books", za koji komentar kaže da se prikazuje u bočnoj traci, ostao je na engleskom u svih devet pokretanja. Model je učinio suprotno od onoga što lokalizirana stranica treba: preveo je napomenu za developere, a ostavio oznaku koju će čitatelji vidjeti.

Nijedan izbor nije pogrešan u svakom slučaju. Za tutorial čiji će čitatelji kopirati kod u vlastiti projekt prevedeni komentari pomažu. Za referentnu dokumentaciju čiji kod mora odgovarati repozitoriju, oni čine da se stranica ne slaže s izvorom. Odlučite jednom za projekt i ručno pregledajte vrijednosti nizova u primjerima konfiguracije jer nijedan alat ne može razlikovati oznaku za prikaz od identifikatora. Provjeravač iz tog razloga prijavljuje promjene samo u komentarima kao upozorenja.

3. Metoda koja se činila sigurnom pokvarila je front matter

Zaštićeni uvjet učinio je što je obećao: svih 32 rezerviranih mjesta vratilo se u svih tri pokretanja, pa su kod, URL-ovi i oznake savršeno obnovljeni. No naša skripta ostavila je dvije male stvari izvan rezerviranih mjesta: redak --- koji otvara front matter i završni navodnik nakon prevedenog naslova i opisa. Model ih je ispustio u svih tri pokretanja. Datoteka je počinjala ovako:

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

Bez početnog ---, Markdown parser više ne vidi front matter. Čita šest YAML redaka plus završni --- kao naslov, pa bi se stranica otvorila velikim naslovom koji sadrži YAML. I dalje se kompajlirala kao MDX. Ni vraćanje --- nije dovoljno: YAML parser odbija dva nezavršena navodnika.

Lekcija nije izbjegavati rezervirana mjesta. Nego da se sve što ostavite izloženo može vratiti promijenjeno i da front matter uopće ne bi trebao ići modelu kao dio stranice. Parsirajte ga, pošaljite samo vrijednosti namijenjene čitatelju (title, description) kao zasebne nizove i upišite prijevode natrag u izvornu strukturu. To je nekoliko redaka koda i uklanja cijelu klasu problema.

Podebljani tekst i rasponi na kineskom, japanskom i korejskom

Dva dodatna problema nikada se nisu pojavila u naših devet pokretanja, ali ih vrijedi provjeriti jer tiho kvare stranice, a oba su pogodila i BookTranslatorov vlastiti blog. Blog je napisan u MDX-u i strojno preveden na 27 jezika, a u jednom zakazanom pokretanju prevođenja dva korejska članka pala su na našoj provjeri strukture tri ponovna pokušaja zaredom. Uzroci su bili dva uzorka u nastavku.

Podebljani tekst koji završava interpunkcijom. CommonMark odlučuje može li ** otvoriti ili zatvoriti podebljani tekst promatrajući znakove s obje strane. Završni ** koji dolazi odmah nakon interpunkcije mora biti praćen razmakom, interpunkcijom ili krajem retka; to je pravilo desnog ruba. Engleski uvijek ima razmak na tom mjestu. Kineski, japanski i korejski često nemaju. Stoga 打开**设置 → 导出（测试版）**并选择 prikazuje doslovne zvjezdice jer podebljani tekst završava punom zagradom i odmah ga slijedi 并. Isti redak bez zagrade prikazuje se podebljano, kao i redak s razmakom nakon **. Podebljana poveznica ima isti problem jer poveznica završava s ): 点击**[导出](./export-options.md)**打开 ne uspijeva, kao ni korejski **[API](./api.md)**는.

Naš je model slučajno stavio razmak s obje strane svakog podebljanog izraza pa se njegov izlaz ispravno prikazao. Urednik koji kasnije ukloni te razmake kako bi slijedio kineske tipografske konvencije ponovno uvodi grešku. Možete isprobati svih sedam varijanti u render-cases.md.

Brojčani rasponi s tildom. Kineski i japanski tekst često piše raspone kao 3~5. GitHub Flavored Markdown stranice izgrađene na remarku pretvaraju pojedinačne tilde u prekriženi tekst prema zadanim postavkama: opcija remark-gfm singleTilde je true osim ako je promijenite. Dva raspona u jednom odlomku, poput 需要 3~5 分钟，生成 10~20 MB 的文件夹, prikazuju se s prekriženim tekstom između njih. Naš je uzorak koristio crtice, a osam izvršavanja ih je zadržalo dok je deveto napisalo 3 到 5. Zatražite crtice ili riječi u rasponima ili postavite singleTilde: false u svojoj remark konfiguraciji.

Strukturni provjeravač označava oba uzorka. Kako biste potvrdili što se stvarno prikazuje, render_check.mjs broji podebljani tekst, kurziv, prekriženi tekst i preostale zvjezdice u izvorniku i prijevodu te pokušava MDX kompilaciju:

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

Manje čvorova podebljanog teksta ili više doslovnih zvjezdica u prijevodu znači da se neki naglasak prestao zatvarati.

Radni postupak koji funkcionira

1. Prvo popravite ID-ove naslova. Dodajte eksplicitne ID-ove svakom naslovu na koji nešto vodi, u sintaksi koju podržava vaš generator stranica. Učinite to na izvornom jeziku, jednom, i predajte prije nego što se bilo što prevede.

2. Izvadite front matter iz stranice. Prevedite samo vrijednosti namijenjene čitatelju poput title i description, kao zasebne nizove, i upišite ih natrag u izvorni YAML.

3. Odredite pravila za kod. Prevode li se komentari ili ne; prevode li se prikazni nizovi u primjerima konfiguracije ili ne. Zapišite to u svoj rječnik prijevoda uz nazive proizvoda koji se ne smiju mijenjati, poput Shelfmarka u našem uzorku.

4. Prevedite tijelo. Koristite alat koji parsira Markdown ili pošaljite cijelu stranicu s eksplicitnim pravilima. U našem testu slanje cijele stranice zadržalo je sintaksu netaknutom; ako koristite oznake čuvare, zaštitite cijele konstrukcije i ne ostavljajte ništa napola izloženo.

5. Pokrenite strukturnu provjeru.

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

   Ona uspoređuje ključeve i vrijednosti front mattera, uvoze, blokove koda, ugrađeni kod, ciljeve poveznica, definicije referenci, razine naslova, ciljeve poveznica unutar stranice, JSX oznake i atribute, MDX komentare, oznake napomena, oznake fusnota, oblik tablice, okvire popisa zadataka, tvrde prijelome redaka, naglaske koji se ne mogu zatvoriti, tilde raspone i pojmove koje tražite da zadrži. Ne procjenjuje kvalitetu prijevoda.

6. Provjerite prikaz za CJK ciljeve pomoću render_check.mjs i dodajte razmak nakon svakog završnog ** koji slijedi interpunkciju.

7. Izgradite stranicu i kliknite poveznice. Otvorite stranicu na svakom jeziku, kliknite svaku poveznicu unutar stranice i pročitajte primjere konfiguracije. Uspješna izgradnja dokazuje samo da se datoteka kompilira.

Za dokumentaciju gdje je točnost važna, koraci terminologije i pregleda iz našeg radnog postupka tehničkog prevođenja primjenjuju se povrh ovoga.

Gdje se BookTranslator uklapa

BookTranslatorov prevoditelj TXT datoteka prihvaća .txt, .md i .mdx datoteke. Prema stranici proizvoda, prevodi ih čuvajući odlomke, prijelome redaka, posebne znakove i strukturu teksta, a velike datoteke dijeli na segmente za prevođenje s obzirom na kontekst, tako da možete prenijeti cijeli priručnik ili knjigu napisanu u Markdownu umjesto da je lijepite u dijelovima.

Stranica proizvoda ne opisuje posebno rukovanje front matterom, blokovima koda ili MDX komponentama, a ovaj uzorak nismo provodili kroz BookTranslator za ovaj članak. Koji god alat koristili, napravite korake od 1 do 3 prije prevođenja i korake od 5 do 7 nakon toga. Naslov bez fiksnog ID-a i dalje gubi svoje poveznice, a raspon napisan s tildama i dalje se pretvara u prekriženi tekst. Ako objavljujete knjigu na više jezika, naš vodič za samostalno objavljivanje na više jezika pokriva ostatak tog posla.

Preuzmite testne datoteke

Sve iz ovog testa slobodno je za ponovnu upotrebu:

• sample-source.mdx: engleski uzorak od 73 retka;
• check_markdown_translation.py: strukturni provjeravač (samo Python standardna biblioteka);
• render_check.mjs i render-cases.md: provjera prikaza i sedam CJK testnih slučajeva;
• run_llm_markdown_test.py: tri uvjeta upita za bilo koji lokalni poslužitelj kompatibilan s OpenAI-jem;
• devet izlaza u mapi outputs, s datotekama check-results.txt i results.csv.