Hogyan fordítsunk Markdown-fájlokat a kód, a hivatkozások és a front matter törése nélkül

Egy Markdown-fájl fordításához a szöveget kell lefordítani, a gépi részeket pedig érintetlenül hagyni: a front matter kulcsainak, a kódnak, az URL-eknek, a hivatkozások címkéinek, a komponensek címkéinek és a lábjegyzetek címkéinek bájtra pontosan vissza kell térniük. Ezután ellenőrizni kell három dolgot, amit egy gondos fordítás is elronthat: a címsorokra mutató hivatkozásokat, a kódkommenteket, valamint kínai, japán vagy koreai nyelv esetén a félkövér szöveg és a számtartományok körüli térközöket.

Egy 73 soros MDX-oldalt fordítottunk le egyszerűsített kínaira kilenc alkalommal egy helyi modellel, három különböző prompt használatával, és minden eredményt egy szkripttel ellenőriztünk. Azok a részek, amelyek miatt általában aggódni szoktak, mind a kilenc futásban sértetlenek maradtak: a kód, a beágyazott kód, az URL-ek, a táblázat, a JSX-komponens és a feladatlista. Három másik dolog viszont elromlott. A címsorra mutató hivatkozás mind a kilenc futásban eltört. A kódkommenteket lefordította mind a hat futásban, amely az egész fájlt elküldte, beleértve három olyan futást is, ahol a prompt azt mondta, hogy ne nyúljon a kódhoz. És a prompt, amely helyőrzők mögé rejtette a szintaxist – ami a legbiztonságosabb lehetőségnek hangzik –, mind a három futásában elrontotta a front mattert.

Gyors válasz: mit kell lefordítani és mit kell érintetlenül hagyni

Minden más közönséges szöveg: bekezdések, listaelemek, táblázatcellák és idézetblokkok.

Mit teszteltünk

Megírtuk a sample-source.mdx fájlt, amely egy Shelfmark nevű kitalált olvasóalkalmazás dokumentációs oldala. A Docusaurus és a hasonló dokumentációs oldalak által használt MDX-stílusban íródott, a fenti táblázat minden egyes szerkezetére egy-egy példával, valamint egy két szóközzel jelölt kemény sortöréssel, egy félkövér hivatkozással, egy zárójellel végződő félkövér kifejezéssel, két gondolatjellel írt számtartománnyal és egy oldalon belüli hivatkozással a „Keep one glossary for the whole book.” címre.

Ezután megkértünk egy helyi modellt, hogy háromféleképpen fordítsa le egyszerűsített kínaira:

1. Teljes fájl. Illeszd be a teljes fájlt, és kérd vissza a lefordított fájlt.
2. Utasításokkal. Ugyanaz, plusz hat szabály: tartsd meg a front matter kulcsait, ne változtass semmit a kódon belül, tartsd meg az URL-eket és a hivatkozásdefiníciókat, tartsd meg az importokat, címkéket és megjegyzéseket, tartsd meg a lábjegyzet-címkéket és a figyelmeztető jelölőket, és fordítsd le a címsorokat, a hivatkozások szövegét, az alt szöveget és a title attribútumot.
3. Védett. Cseréld ki a kódot, a beágyazott kódot, az URL-eket, a címkéket, a megjegyzéseket, a lábjegyzet-címkéket, a figyelmeztető jelölőket és a front matter sorait számozott helyőrzőkre, például ⟦12⟧, fordítsd le a többit, majd tedd vissza az eredetieket. A title és description értékeket fordításhoz szabadon hagytuk, és mint kiderült, a front matter --- sorai és a záró idézőjelek is szabadon maradtak.

A modell a Qwen 3.6 27B (Q4_K_M) volt a LM Studio-ban, kikapcsolt gondolkodással és 0,3-as hőmérséklettel, egy Apple M4 Max 64 GB memóriával. Minden feltételt háromszor futtattunk, összesen kilenc futást, 2026. október 25-én. A szkript a run_llm_markdown_test.py, és mind a kilenc kimenet szerkesztetlenül jelent meg; a README minden fájlt felsorol. Ha még soha nem állítottál be helyi modellt, a helyi LLM-fordítási útmutatónk ismerteti a beállításokat.

Ez egy kis teszt volt egy modellel, egy nyelvpárral és egy oldallal. Megmutatja, milyen problémák fordulnak elő, és hogyan lehet elkapni őket. Nem rangsorol modelleket vagy promptokat.

Eredmény: A szintaxis túlélte; a hivatkozások és a döntések nem

Minden kimenetet ellenőriztünk a check_markdown_translation.py segítségével, és mindegyiket rendereltük a remarkkal és az MDX-fordítóval. Az ellenőrző teljes kimenete a check-results.txt fájlban található, a results.csv pedig futásonként egy sort tartalmaz.

Az első sorok a jó hírek. Ez a modell érintetlenül adta vissza a Markdown szintaxist, amikor a teljes fájlt beillesztettük; nem találtunk javítanivalót a kódban, az URL-ekben vagy a táblázatokban. Az utolsó négy sorban van a munka, és egyik sem jelenik meg hibaként az oldal buildelésekor.

1. A lefordított címsorok elrontják a rájuk mutató hivatkozásokat

A minta a szószedet szakaszára a [glossary section](#keep-one-glossary-for-the-whole-book) hivatkozással mutat. Minden futás lefordította a címsort, ahogy kell, és minden futás megtartotta a hivatkozás célját, ahogy kell. Az eredmény egy olyan azonosítóra mutató hivatkozás, amely már nem létezik.

A legtöbb Markdown-eszköz a címsor szövegéből állítja elő a címsor-azonosítókat. A Pandoc dokumentációja szerint az azonosító „a címsor szövegén alapul”, a Docusaurus pedig figyelmeztet, hogy érdemes lehet megváltoztatni vagy lefordítani egy címsort anélkül, hogy „frissítenéd a meglévő azonosítót, hogy elkerüld a hivatkozások eltörését”. Amint a címsor így szól: 为整本书保留一个术语表, a generált azonosítója kínai lesz, és a #keep-one-glossary-for-the-whole-book hivatkozás sehová sem görget. Az oldal továbbra is buildelődik, így semmi sem jelzi a problémát.

Ezt nem lehet a fordítás utáni hivatkozás szerkesztésével javítani. Kilenc futás során a modell ugyanazt a címsort négyféleképpen írta, így a generált azonosító minden újrafordításkor ismét megváltozna. A javítást a fordítás előtt kell elvégezni: minden hivatkozott címsorhoz rendelj fix azonosítót.

• A Docusaurus MDX-ben használd a ## Keep one glossary for the whole book {/* #keep-one-glossary */} formát. A Docusaurus megjegyzi, hogy a régebbi {#id} forma „már nem érvényes MDX szintaxis”, és a write-heading-ids parancsa minden dokumentumhoz hozzáadja az azonosítókat.
• A Pandocban és a PHP Markdown Extra szabványt követő Markdown-feldolgozókban használd a {#keep-one-glossary} kifejezést a címsor végén.

Így az azonosító minden nyelven ugyanaz marad, és az ellenőrző a hivatkozás céljaként kezeli.

2. A kódkommentek lefordulnak, a látható szöveg pedig nem

A mintában van egy shell-komment és egy YAML-komment:

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

Mind a hat futás, amely a teljes fájlt küldte, lefordította mindkét kommentet, beleértve azt a hármat is, ahol a prompt azt mondta: „Ne változtass semmin a kódblokkokon belül.” Maga a kód mind a kilenc futásban érintetlen maradt. Eközben a "My books", amelyről a komment azt mondja, hogy az oldalsávban jelenik meg, mind a kilenc futásban angolul maradt. A modell az ellenkezőjét tette annak, amire egy lokalizált oldalnak szüksége van: lefordította a fejlesztőknek szóló megjegyzést, és meghagyta az olvasók által látott címkét.

Egyik választás sem hibás minden esetben. Egy olyan útmutatónál, amelynek olvasói a saját projektjükbe másolják a kódot, a lefordított kommentek segítenek. Egy olyan referenciadokumentációnál, amelynek kódjának egyeznie kell egy adattárral, összeütközésbe hozzák az oldalt a forrással. Döntsd el egyszer a projektre vonatkozóan, és a konfigurációs példákban kézzel nézd át a szöveges értékeket, mert egyetlen eszköz sem tud különbséget tenni egy megjelenített címke és egy azonosító között. Az ellenőrző ezért jelenti a csak kommenteket érintő változtatásokat figyelmeztetésként.

3. A biztonságosnak tűnő módszer elrontotta a front mattert

A védett feltétel teljesítette, amit ígért: mind a 32 helyőrző visszajött mindhárom futásban, így a kód, az URL-ek és a tagek tökéletesen helyreálltak. A szkriptünk azonban két apróságot a helyőrzőkön kívül hagyott: a front mattert nyitó --- sort, valamint a lefordított cím és leírás utáni záró idézőjelet. A modell mindhárom futásban elhagyta mindegyiket. A fájl így kezdődött:

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

A nyitó --- nélkül a Markdown-értelmező már nem lát front mattert. A hat YAML-sort és a záró ----t címsorként olvassa, így az oldal egy nagy, a YAML-t tartalmazó címsorral nyílna meg. MDX-ként továbbra is lefordult. A --- visszatétele sem elég: a YAML-értelmező elutasítja a két lezáratlan idézőjelet.

A tanulság nem az, hogy kerülni kell a helyőrzőket. Hanem az, hogy ami kívül marad, az megváltozva jöhet vissza, és a front mattert egyáltalán nem szabad a modellnek elküldeni az oldal részeként. Elemezd, csak az olvasóknak szóló értékeket (title, description) küldd külön szövegként, és írd vissza a fordításokat az eredeti struktúrába. Ez néhány sor kód, és megszünteti a problémák egész osztályát.

Félkövér szöveg és tartományok kínai, japán és koreai nyelven

Két további probléma soha nem jelent meg a kilenc futásunkban, de érdemes ellenőrizni őket, mert csendben elrontják az oldalakat, és mindkettő sújtotta már a BookTranslator saját blogját. A blog MDX-ben íródott, és gépi fordítással 27 nyelvre fordítják, és egy ütemezett fordítási futásban két koreai cikk három egymást követő újrapróbálkozás során is megbukott a struktúraellenőrzésen. Az okok az alábbi két minta voltak.

Félkövér, amely írásjelre végződik. A CommonMark a ** karakterek előtti és utáni karakterek alapján dönti el, hogy azok nyithatnak-e vagy zárhatnak-e félkövér formázást. A záró **-nak, ha közvetlenül írásjel után áll, szóköznek, írásjelnek vagy a sor végének kell követnie; ez a jobb oldali határoló szabály. Az angolban mindig van ott szóköz. A kínai, japán és koreai nyelvekben gyakran nincs. Így a 打开**设置 → 导出（测试版）**并选择 szó szerinti csillagokat mutat, mert a félkövér egy teljes szélességű zárójelre végződik, és közvetlenül a 并 követi. Ugyanaz a sor zárójel nélkül félkövérként jelenik meg, és az a sor is, amelyben a ** után szóköz van. Ugyanez a probléma áll fenn a félkövér hivatkozásoknál is, mert a hivatkozás )-re végződik: a 点击**[导出](./export-options.md)**打开 nem működik, és a koreai **[API](./api.md)**는 sem.

A modellünk véletlenül minden félkövér kifejezés mindkét oldalára szóközt tett, így a kimenete helyesen jelent meg. Ha egy szerkesztő később eltávolítja ezeket a szóközöket, hogy megfeleljen a kínai tipográfiai hagyományoknak, visszahozza a hibát. Kipróbálhatja mind a hét változatot a render-cases.md fájlban.

Számhatárok hullámvonallal. A kínai és japán szövegek gyakran 3~5 formában írják a tartományokat. A remarkra épülő GitHub Flavored Markdown oldalak alapértelmezés szerint egyszeres hullámvonalakat alakítanak áthúzott szöveggé: a remark-gfm singleTilde beállítása true, hacsak nem változtatja meg. Egy bekezdésben két tartomány, például a 需要 3~5 分钟，生成 10~20 MB 的文件夹, áthúzott szövegként jelenik meg a kettő között. A mintánkban en dash karaktereket használtunk, és nyolc futás megtartotta azokat, míg a kilencedik 3 到 5-öt írt. Kérjen en dash karaktereket vagy szavakat a tartományokhoz, vagy állítsa be a singleTilde: false értéket a remark konfigurációjában.

A strukturális ellenőrző mindkét mintát jelzi. Annak megerősítéséhez, hogy mi jelenik meg ténylegesen, a render_check.mjs megszámolja a félkövér, dőlt, áthúzott és visszamaradt csillagokat a forrásban és a fordításban, és megpróbál egy MDX-fordítást:

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

Ha a fordításban kevesebb félkövér csomópont vagy több szó szerinti csillag van, az azt jelenti, hogy néhány kiemelés nem záródott le.

Egy működő munkafolyamat

1. Először a címsor-azonosítókat javítsa. Adjon explicit azonosítókat minden olyan címsorhoz, amelyre valami hivatkozik, a webhelygenerátora által támogatott szintaxissal. Ezt a forrásnyelven tegye meg, egyszer, és commitolja, mielőtt bármit lefordítanának.

2. Vegye ki a front mattert az oldalból. Csak az olvasóknak szóló értékeket fordítson le, például a title és description mezőket, külön karakterláncokként, és írja vissza őket az eredeti YAML-ba.

3. Döntse el a kódra vonatkozó szabályt. A megjegyzések le legyenek-e fordítva vagy sem; a konfigurációs példákban szereplő megjelenített karakterláncok le legyenek-e fordítva vagy sem. Írja le ezt a fordítási szójegyzékében azok mellett a terméknevek mellett, amelyeket nem szabad megváltoztatni, például a mintánkban szereplő Shelfmark mellett.

4. Fordítsa le a törzsszöveget. Használjon olyan eszközt, amely elemzi a Markdownt, vagy küldje el az egész oldalt explicit szabályokkal. Tesztünkben az egész oldal elküldése sértetlenül tartotta a szintaxist; ha helyőrzőket használ, védje meg a teljes szerkezeteket, és ne hagyjon semmit félig kitakarva.

5. Futtassa a strukturális ellenőrzést.

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

   Összehasonlítja a front matter kulcsait és értékeit, az importokat, a kódblokkokat, a beágyazott kódot, a hivatkozások célpontjait, a hivatkozásdefiníciókat, a címsorok szintjeit, az oldalon belüli hivatkozások célpontjait, a JSX tageket és attribútumokat, az MDX megjegyzéseket, a figyelmeztetésjelölőket, a lábjegyzetcímkéket, a táblázat alakját, a feladatlista jelölőnégyzeteit, a kemény sortöréseket, a le nem záródó kiemeléseket, a hullámvonalas tartományokat és azokat a kifejezéseket, amelyeket meg kér, hogy tartson meg. Nem ítéli meg a fordítás minőségét.

6. Ellenőrizze a megjelenítést CJK célnyelvek esetén a render_check.mjs segítségével, és adjon hozzá szóközt minden záró ** után, amely írásjelet követ.

7. Építse fel az oldalt, és kattintson a hivatkozásokra. Nyissa meg az oldalt minden nyelven, kattintson minden oldalon belüli hivatkozásra, és olvassa el a konfigurációs példákat. Egy sikeres build csak azt bizonyítja, hogy a fájl lefordul.

Azoknál a dokumentációknál, ahol a pontosság számít, a műszaki fordítási munkafolyamatunkban leírt terminológiai és ellenőrzési lépések is érvényesek ezen felül.

Hogyan illeszkedik ide a BookTranslator

A BookTranslator TXT-fordítója elfogad .txt, .md és .mdx fájlokat. A termékoldal szerint úgy fordítja le őket, hogy megtartja a bekezdéseket, sortöréseket, speciális karaktereket és szövegszerkezetet, és a nagy fájlokat szegmensekre bontja a kontextusérzékeny fordításhoz, így egy egész kézikönyvet vagy Markdownban írt könyvet is feltölthet darabokban való beillesztés helyett.

A termékoldal nem ír le különleges kezelést a front matter, a kódblokkok vagy az MDX-komponensek esetében, és ezt a mintát nem futtattuk át a BookTranslatoron ehhez a cikkhez. Bármilyen eszközt is használ, végezze el az 1–3. lépést a fordítás előtt, és az 5–7. lépést utána. Egy rögzített azonosító nélküli címsor továbbra is elveszíti a hivatkozásait, és egy hullámvonalakkal írt tartomány továbbra is áthúzott szöveggé válik. Ha több nyelven ad ki egy könyvet, a többnyelvű önkiadásról szóló útmutatónk a munka többi részét is lefedi.

A tesztfájlok letöltése

A teszt minden anyaga szabadon felhasználható:

• sample-source.mdx: a 73 soros angol minta;
• check_markdown_translation.py: a strukturális ellenőrző (csak Python szabványos könyvtár);
• render_check.mjs és render-cases.md: a megjelenítés ellenőrzése és a hét CJK teszteset;
• run_llm_markdown_test.py: a három promptfeltétel bármely OpenAI-kompatibilis helyi szerverhez;
• a kilenc kimenet a kimenetek mappában, valamint a check-results.txt és a results.csv fájl.