आर्किटेक्चर
आर्किटेक्चर अवलोकन
कोडबेस को चार परतों में व्यवस्थित किया गया है। मानसिक मॉडल के लिए इस अनुभाग का उपयोग करें; जब आपको फ़ाइल-स्तरीय विवरण की आवश्यकता हो तो स्रोत ट्री खोलें।
sync रन कैसे एक साथ फिट बैठता है
sync (और व्यक्तिगत अनुवाद कमांड) सक्षम सुविधाओं को क्रम में चलाते हैं:
| चरण | कमांड | यह क्या करता है |
|---|---|---|
| 1 | extract → translate-ui | UI स्रोतों को स्कैन करें → strings.json अपडेट करें → फ़्लैट लोकेल JSON भरें (de.json, …) |
| 2 | translate-svg (वैकल्पिक) | config.svg के तहत SVG टेक्स्ट का अनुवाद करें |
| 3 | translate-docs | मार्कडाउन, MDX, .astro पेजों का अनुवाद करें; Docusaurus कैटलॉग JSON; Nextra _meta / डिक्शनरी .ts; VitePress थीम कैटलॉग |
| 4 | translate-json (वैकल्पिक) | json[] के तहत नेस्टेड JSON लीव्स का अनुवाद करें |
प्रत्येक पाइपलाइन एक ही मुख्य लूप का अनुसरण करती है: सेगमेंट निकालें → सिंटैक्स को सुरक्षित रखें → बैच → कैश लुकअप या LLM कॉल → आउटपुट लिखें। बीच में साझा सेवाएं — कॉन्फ़िग, प्लेसहोल्डर, कैश, शब्दावली, LlmClient — साझा इन्फ्रास्ट्रक्चर के तहत वर्णित हैं।
मॉड्यूल मैप
| परत | फ़ोल्डर | भूमिका |
|---|---|---|
| एंट्री | src/cli/ | CLI कमांड: init, extract, mark-html, translate-ui, translate-docs, translate-json, translate-svg, sync, status, dashboard, … |
| पाइपलाइन | src/extractors/ | JS/TS, HTML मार्कर, मार्कडाउन, JSON, SVG, .astro से सेगमेंट निष्कर्षण |
src/processors/ | प्लेसहोल्डर सुरक्षा, बैचिंग, सत्यापन, लिंक पुनर्लेखन | |
| साझा | src/core/ | कॉन्फ़िग, प्रकार, SQLite कैश, प्रॉम्प्ट, आउटपुट पाथ, लोकेल यूटिलिटीज |
src/api/ | LlmClient — प्रदाता-अज्ञेय चैट क्लाइंट (Vercel AI SDK) मॉडल फ़ॉलबैक के साथ | |
src/glossary/ | प्रॉम्प्ट के लिए शब्दावली लोडिंग, शब्द संकेत और वैकल्पिक प्रोजेक्ट-संदर्भ फ़ाइलें | |
src/utils/ | लॉगर, हैशिंग, इग्नोर पार्सर, डिस्प्ले-चौड़ाई टेबल, .env लोडर | |
| आपका ऐप रनटाइम | src/runtime/ | i18next हेल्पर और डिस्प्ले यूटिलिटीज — 'ai-i18n-tools/runtime' के रूप में निर्यात किया गया (रनटाइम हेल्पर) |
| उपकरण UI (डॉगफूडिंग) | src/i18n/, src/dashboard-app/, src/server/ | यह पैकेज के अपने CLI और अनुवाद डैशबोर्ड का स्थानीयकरण करता है — आपकी परियोजना सामग्री से अलग (स्व-स्थानीयकरण) |
प्रोग्रामेटिक उपयोग के लिए अभिप्रेत सब कुछ src/index.ts (प्रोग्रामेटिक एपीआई) से फिर से निर्यात किया जाता है।
पाइपलाइन सारांश
| पाइपलाइन | अनुभाग | इनपुट → आउटपुट |
|---|---|---|
| यूआई स्ट्रिंग्स | यूआई स्ट्रिंग्स इंटरनल | स्रोत फ़ाइलें → strings.json → फ़्लैट {locale}.json |
| दस्तावेज़ | दस्तावेज़ इंटरनल | मार्कडाउन / एमडीएक्स / .astro / डॉक्यूसॉरस जेएसओएन → docs[].outputDir के तहत प्रति-स्थानिक फ़ाइलें |
| जेएसओएन बंडल | जेएसओएन इंटरनल | json[] के तहत नेस्टेड जेएसओएन → प्रति-स्थानिक जेएसओएन फ़ाइलें |
| एसवीजी | दस्तावेज़ इंटरनल — एक्सट्रैक्टर | config.svg के तहत एसवीजी फ़ाइलें → अनुवादित एसवीजी प्रतियां |
यूआई स्ट्रिंग्स इंटरनल
| चरण | घटक | परिणाम |
|---|---|---|
| 1 | स्रोत फ़ाइलें (जेएस/टीएस; वैकल्पिक .astro / .html) | डिस्क पर फ़ाइलें |
| 2 | UIStringExtractor (ui-string-babel.ts के माध्यम से बैबेल) | MD5 हैश द्वारा कुंजीबद्ध खंड |
| 3 | strings.json | मास्टर कैटलॉग: { hash: { source, translated, models?, locations? } } |
| 4 | LlmClient.translateUIBatch() | स्रोत स्ट्रिंग्स का जेएसओएन सरणी → अनुवाद (+ प्रति बैच मॉडल आईडी) |
| 5 | de.json, pt-BR.json, … | फ़्लैट मैप्स: स्रोत स्ट्रिंग → अनुवाद (कोई मॉडल मेटाडेटा नहीं) |
UIStringExtractor
extractUiCallsFromFileContent ui-string-babel.ts में t("literal") और i18n.t("literal") कॉल ढूंढता है। JS और TS फ़ाइलें @babel/parser (मॉड्यूल स्रोत, टाइपस्क्रिप्ट और JSX) के साथ पार्स की जाती हैं। .astro स्रोतों के लिए (जब ui.uiExtractor.extensions में सूचीबद्ध हों), वही फ़ंक्शन फ्रंटमैटर और टेम्पलेट {expression} ब्लॉक को पार्स करता है और वही funcNames नियम लागू करता है। फ़ंक्शन नाम और फ़ाइल एक्सटेंशन ui.uiExtractor के माध्यम से कॉन्फ़िगर किए जा सकते हैं (ui.reactExtractor एक समर्थित उपनाम है)। extract अतिरिक्त इनपुट को भी उसी कैटलॉग में मर्ज करता है: प्रोजेक्ट package.json description जब includePackageDescription सक्षम हो (डिफ़ॉल्ट), और बंडल किए गए ui-languages मास्टर कैटलॉग (sourceLocale + targetLocales से निर्मित) से प्रत्येक englishName जब includeUiLanguageEnglishNames true हो (स्रोत में पहले से मिली स्ट्रिंग प्राथमिकता बनाए रखती हैं; languagesManifestPath नहीं पढ़ता है)। extract languagesManifestPath पर ui-languages.json को भी पुनः उत्पन्न करता है। सेगमेंट हैश ट्रिम की गई स्रोत स्ट्रिंग के MD5 के पहले 8 हेक्स वर्ण होते हैं — ये strings.json में कुंजियाँ बन जाते हैं।
.html / .htm स्रोतों के लिए (जब ui.uiExtractor.extensions में सूचीबद्ध हों), extract इसके बजाय फ़ाइल को html-i18n-marks.ts के माध्यम से रूट करता है, जो data-i18n / data-i18n-title / data-i18n-placeholder / data-i18n-alt / data-i18n-aria-label मार्कर विशेषताओं को स्कैन करता है (ui.uiExtractor.htmlI18nAttributes के माध्यम से कॉन्फ़िगर किया जा सकता है)। एक नंगे मार्कर तत्व के अपने textContent या विशेषता से अपना स्रोत पाठ लेता है; एक मान वाला मार्कर (data-i18n="Key") मान का उपयोग करता है। data-i18n-locale-src और data-i18n-locale-href ब्राउज़र रनटाइम के लिए आरक्षित हैं और कभी नहीं निकाले जाते हैं। वही मॉड्यूल mark-html कमांड को संचालित करता है, जो नंगे मार्करों को स्वचालित रूप से सम्मिलित करता है (alt और aria-label सहित) और कभी भी लोकेल URL मार्करों को सम्मिलित नहीं करता है। HTML फ़ाइलें कभी भी बैबेल पास तक नहीं पहुँचती हैं। डॉक्स outputDir के तहत जेनरेट किया गया लोकेल HTML इस स्कैन से बाहर रखा गया है।
सामान्य Astro SSG साइटें i18next को छोड़ सकती हैं: बिल्ड समय पर फ्लैट {locale}.json लोड करें और स्रोत-पाठ कुंजी द्वारा t('source text') को हल करें। स्रोत भाषा sourceLocale है और कोई भी भाषा हो सकती है (examples/astro-website/src/i18n/t.ts और UI स्ट्रिंग्स — Astro वेबसाइट देखें)।
साधारण HTML ऐप्स t() कॉल्स के बजाय मार्कर एट्रिब्यूट्स के साथ उसी कैटलॉग मॉडल का पालन करते हैं — अनुवाद के लिए HTML को चिह्नित करना देखें। उपयोग के लिए तैयार स्क्रिप्ट ai-i18n-tools/html-runtime/i18n.js है।
स्टैटिक HTML जो प्रति लोकेल एक फ़ाइल बननी चाहिए, एक डॉक्यूमेंट्स पाइपलाइन (translate-docs के अंदर HtmlTemplateExtractor) है, न कि यह कैटलॉग। HTML पेज देखें।
strings.json
मास्टर कैटलॉग का आकार है:
{
"a1b2c3d4": {
"source": "The English string",
"translated": {
"de": "Der deutsche Text",
"pt-BR": "O texto em português"
},
"models": {
"de": "anthropic/claude-3.5-haiku",
"pt-BR": "openai/gpt-4o"
},
"locations": [{ "file": "src/app/page.tsx", "line": 51 }]
}
}models (वैकल्पिक) — प्रति स्थानीय, किस मॉडल ने उस अनुवाद को उस स्थानीय के लिए अंतिम सफल translate-ui रन के बाद उत्पादित किया (या user-edited यदि पाठ अनुवाद डैशबोर्ड से सहेजा गया था)। locations (वैकल्पिक) — जहाँ extract को स्ट्रिंग मिली (स्कैनर + पैकेज विवरण पंक्ति; बंडल-मास्टर englishName स्ट्रिंग्स locations को छोड़ सकते हैं)।
extract नई कुंजियाँ जोड़ता है और स्कैन में अभी भी मौजूद कुंजियों (स्कैनर लिटरल, वैकल्पिक विवरण, वैकल्पिक बंडल-मास्टर englishName) के लिए मौजूदा translated / models डेटा को सुरक्षित रखता है। translate-ui गुम translated प्रविष्टियों को भरता है, उन लोकेल के लिए models को अपडेट करता है जिनका वह अनुवाद करता है, और फ्लैट लोकेल फ़ाइलें लिखता है।
ui-languages.json मैनिफेस्ट — { code, label, englishName, direction } (BCP-47 code, UI label, संदर्भ englishName, "ltr" या "rtl") का JSON सरणी। sourceLocale + targetLocales और बंडल किए गए मास्टर data/ui-languages-complete.json से एक प्रोजेक्ट फ़ाइल बनाने के लिए generate-ui-languages या extract का उपयोग करें।
फ्लैट लोकेल फ़ाइलें
प्रत्येक लक्ष्य लोकेल को एक फ्लैट JSON फ़ाइल (de.json) मिलती है जो स्रोत स्ट्रिंग → अनुवाद (कोई models फ़ील्ड नहीं) को मैप करती है:
{
"The English string": "Der deutsche Text",
"Save": "Speichern"
}i18next इन्हें संसाधन बंडल के रूप में लोड करता है और स्रोत स्ट्रिंग (की-एज़-डिफ़ॉल्ट मॉडल) द्वारा अनुवादों को देखता है।
UI अनुवाद प्रॉम्प्ट
buildUIPromptMessages सिस्टम + उपयोगकर्ता संदेशों का निर्माण करता है जो:
- स्रोत और लक्ष्य भाषाओं की पहचान करें (
localeDisplayNamesयाui-languages.jsonसे प्रदर्शन नाम द्वारा)। - जब लक्ष्य लोकेल में अपेक्षित लेखन प्रणाली हो तो एक स्क्रिप्ट निर्देश को पहले लगाएं (स्पष्ट BCP-47 स्क्रिप्ट, या एक भाषा डिफ़ॉल्ट जैसे
hi→ देवनागरी,ar→ अरबी,ja→ जापानी काना/कांजी)। - स्ट्रिंग का एक JSON सरणी भेजें और बदले में अनुवादों का एक JSON सरणी का अनुरोध करें।
- उपलब्ध होने पर शब्दावली संकेत शामिल करें।
LlmClient.translateUIBatch प्रत्येक मॉडल को क्रम से आज़माता है, पार्स, नेटवर्क, या गलत-स्क्रिप्ट त्रुटियों (देशी-स्क्रिप्ट लोकेल के लिए रोमनकृत/लैटिन फ़ॉलबैक सहित) पर वापस आता है। CLI localeModels, वैकल्पिक uiModels, और translationModels से प्रति लक्ष्य लोकेल उस सूची का निर्माण करता है (AI मॉडल देखें)।
दस्तावेज़ आंतरिक
| चरण | घटक | परिणाम |
|---|---|---|
| 1 | Markdown / MDX / JSON / .astro फ़ाइलें (translate-docs) | स्रोत फ़ाइलें |
| 2 | MarkdownExtractor / JsonExtractor / AstroTemplateExtractor | segments[] — हैश + सामग्री के साथ टाइप किए गए खंड |
| 3 | PlaceholderHandler | संरक्षित पाठ — HTML, एडमोनिशन, एंकर, MDX, URL, इनलाइन कोड, टोकन के रूप में मास्क किया गया जोर |
| 4 | splitTranslatableIntoBatches | batches[] — गणना + वर्ण सीमा द्वारा समूहीकृत |
| 5 | TranslationCache लुकअप | कैश हिट → छोड़ें; मिस → LlmClient.translateDocumentBatch |
| 6 | PlaceholderHandler.restoreAfterTranslation | अंतिम पाठ — प्लेसहोल्डर बहाल |
| 7 | resolveDocumentationOutputPath | आउटपुट फ़ाइल — Docusaurus लेआउट या फ्लैट लेआउट |
एक्सट्रैक्टर
सभी एक्सट्रैक्टर BaseExtractor का विस्तार करते हैं और extract(content, filepath): Segment[] को लागू करते हैं।
MarkdownExtractor- मार्कडाउन को टाइप किए गए सेगमेंट में विभाजित करता है:frontmatter,heading,paragraph,code,admonition। YAML फ्रंटमैटर को गैर-अनुवाद योग्य के रूप में वर्गीकृत किया गया है (slug,id, और अन्य रूटिंग कुंजियाँ स्थिर रहती हैं)। शीर्ष-स्तरीयexport ...ब्लॉक (जैसे React कंपोनेंट परिभाषाएँ) को मौजूदाimport ...हैंडलिंग के साथ गैर-अनुवाद योग्यotherसेगमेंट के रूप में वर्गीकृत किया गया है। एक बड़े JSX टैग (जैसे एक<Tabs>ब्लॉक) से शुरू होने वाले मल्टी-लाइन ब्लॉक को अनुवाद योग्य पैराग्राफ के रूप में वर्गीकृत किया गया है। गैर-अनुवाद योग्य सेगमेंट (कोड ब्लॉक, रॉ HTML) को यथावत रखा जाता है।AstroTemplateExtractor-.astroमार्केटिंग पेजों के लिए पार्स-और-रिप्लेस (doc-translate.tsमेंtranslateAstroFileके माध्यम सेtranslate-docs)। उपयोगकर्ता-सामने वाले HTML टेक्स्ट नोड्स और अनुवाद योग्य एट्रिब्यूट (alt,title,aria-label,placeholder) निकालता है, साथ ही उपयोगकर्ता-सामने होने पर टेम्पलेट{expression}ब्लॉक के अंदर स्ट्रिंग लिटरल। फ्रंटमैटर टाइपस्क्रिप्ट,<script>,<style>, संरक्षित एट्रिब्यूट/कुंजी मान, औरt('…')के अंदर के लिटरल को छोड़ देता है। जब आउटपुट पाथ गहरे होते हैं (जैसेsrc/pages/de/index.astro), तो पुनर्संयोजन सापेक्ष इंपोर्ट को समायोजित करता है। Astro वेबसाइट पेज देखें।JsonExtractor- Docusaurus JSON लेबल फ़ाइलों (Docusaurus UI कैटलॉग, MDX बॉडी नहीं) से स्ट्रिंग मान निकालता है।SvgExtractor- SVG से<text>,<title>, और<desc>सामग्री निकालता है (config.svgके तहत फ़ाइलों के लिएtranslate-svgद्वारा उपयोग किया जाता है,translate-docsद्वारा नहीं)।html-i18n-marks.ts- एक फोकस्ड एचटीएमएल टैग स्कैनर जिसका उपयोगextractद्वारा.html/.htmस्रोतों औरmark-htmlकमांड द्वारा किया जाता है।collectHtmlI18nStrings/collectHtmlI18nLocationsdata-i18n*मार्कर विशेषताओं (नग्न मार्कर → तत्वtextContent/title/placeholder; मूल्यांकित मार्कर → मूल्य) पढ़ते हैं, औरmarkHtmlContentनग्न मार्कर्स को पत्ती पाठ / शीर्षक / प्लेसहोल्डर तत्वों में डालता है (आदिम,data-i18n-ignoreका सम्मान करता है, कोड जैसे और मिश्रित सामग्री तत्वों को छोड़ देता है)। साझाnormalizeI18nTextहेल्पर निर्माण समय कुंजियों को ब्राउज़र रनटाइम के समान रखता है।
एस्ट्रो हाइब्रिड साइटें (यूआई + पेज एचटीएमएल)
सादे एस्ट्रो ऐप्स अक्सर एक कॉन्फ़िग (संदर्भ: examples/astro-website/) में दोनों यूआई स्ट्रिंग्स और दस्तावेज़ को सक्षम करते हैं:
| परत | तंत्र | आउटपुट |
|---|---|---|
| टेम्पलेट एचटीएमएल | AstroTemplateExtractor + translate-docs | प्रति-स्थानीय .astro के तहत docs[].outputDir |
फ्रंटमैटर / t('…') | ui-string-babel.ts + extract + translate-ui | फ्लैट public/locales/{locale}.json (कुंजी के रूप में स्रोत-भाषा स्ट्रिंग; sourceLocale कोई भी भाषा हो सकती है) |
sync कमांड सक्षम चरणों को क्रम में चलाता है: निकालें फिर अनुवाद-यूआई (जब features.translateUIStrings) → वैकल्पिक अनुवाद-एसवीजी → अनुवाद-दस्तावेज → वैकल्पिक अनुवाद-जेसन (जब तक --no-ui, --no-svg, --no-docs, या --no-json के साथ छोड़ा नहीं जाता है)। प्रारंभ टेम्पलेट ui-astro-website केवल यूआई स्ट्रिंग्स को बनाता है; पेज एचटीएमएल के लिए docs[] और features.translateDocs जोड़ें।
शीर्षक एंकर सम्मिलन (write-heading-ids सीएलआई)
write-heading-ids कमांड प्रलेखन मार्कडाउन के लिए एक स्थानीय, गैर-एलएलएम प्रीप्रोसेसर है। कार्यान्वयन: src/cli/write-heading-ids.ts फ़ाइल खोज को समन्वयित करता है; src/markdown/write-heading-ids-core.ts पंक्तियों को पार्स करता है और एंकर सम्मिलित करता है।
यह एक वैध कॉन्फ़िग की आवश्यकता होती है जिसमें कम से कम एक docs[] ब्लॉक हो। प्रत्येक ब्लॉक के लिए यह .md / .mdx फ़ाइलों को contentPaths के तहत इकट्ठा करता है, परियोजना के .translate-ignore नियमों (डॉक ट्रांसलेशन के समान विचार) को लागू करता है, और वैकल्पिक रूप से --path / --file के साथ एक सबट्री तक सीमित करता है। प्रत्येक फ़ाइल को applyHeadingAnchorsToMarkdown के साथ परिवर्तित किया जाता है: बाड़े वाले कोड ब्लॉक के बाहर फ्लैट एटीएक्स हेडिंग (# … से ###### …) के लिए, मौजूदा हेडिंग आईडी किसी भी रूप में चुने गए शैली से बदल दी जाती है। एचटीएमएल शैलियां एक सuffix-मुक्त हेडिंग के ऊपर की पंक्ति पर <a id="slug"></a> लिखती हैं; --slug-style mdx-comment हेडिंग पंक्ति पर {/* #slug */} (और एक पूर्ववर्ती एचटीएमएल एंकर को छोड़ देती है) लिखती है। स्लग हमेशा वर्तमान हेडिंग पाठ से आते हैं। --remove एचटीएमएल एंकर, क्लासिक {#id} सuffixes, और एमडीएक्स टिप्पणी आईडी को नए लिखे बिना हटा देता है। स्लग अल्गोरिदम सामान्य पारिस्थितिकी तंत्र — github (डिफ़ॉल्ट), bitbucket, gitlab, pymdown (वैकल्पिक यूनिकोड सामान्यीकरण / प्रतिशत-एन्कोडिंग फ़्लैग), azure-devops, प्लस mdx-comment (गिटहब स्लग + एमडीएक्स टिप्पणी आउटपुट) — से मेल खाते हैं ताकि एंकर आईडी मौजूदा टूलिंग (doctoc, PyMdown, Docusaurus, आदि) के साथ संगत रहें। --dry-run रिपोर्ट लिखे बिना संभावित संपादन करता है।
स्रोत पास के बाद, वही कमांड उन अंग्रेज़ी आईडी को प्रत्येक लोकेल के मौजूदा अनुवादित मार्कडाउन (resolveTranslatedOutputPath) पर फिर से स्थापित करता है। अनुवादित शीर्षकों को कभी भी फिर से स्लग नहीं किया जाता है; एक मध्य-शीर्षक {#id} / {/* #id */} को प्रत्यय (या HTML एंकर) पर वापस ले जाया जाता है जिसकी चयनित शैली अपेक्षा करती है। गुम लोकेल फ़ाइलों को छोड़ दिया जाता है।
यह कमांड translate-docs या sync के अंदर नहीं चलता है; स्थिर फ्रैगमेंट आईडी के लिए स्रोत फ़ाइलों में अनुवाद या प्रकाशन से पहले इसे स्पष्ट रूप से चलाएं।
प्लेसहोल्डर सुरक्षा
अनुवाद से पहले, संवेदनशील वाक्य रचना को अपारदर्शी टोकन के साथ बदल दिया जाता है ताकि एलएलएम भ्रष्टाचार को रोका जा सके, इस क्रम में लागू किया जाता है (पुनर्स्थापना इसके विपरीत है):
- फ़ेंस्ड कोड ब्लॉक (तीन या ज़्यादा बैकटिक्स या टिल्ड, जिसमें एक लंबा फ़ेंस भी शामिल है जो एक छोटे फ़ेंस को रैप करता है) - पूरे फ़ेंस को, जानकारी स्ट्रिंग सहित,
{{CDF_N}}से बदल दिया जाता है और दूसरे स्ट्रक्चरल टोकन के साथ क्रम में रखा जाता है। यह::: code-groupया::: tipजैसे कंटेनरों के अंदर सैंपल को अपनी जगह पर रखता है। फ़ेंस जानकारी स्ट्रिंग्स (VitePress टैब लेबल) स्रोत भाषा में ही रहती हैं। एक बिना बंद किया हुआ ओपनर टेक्स्ट के रूप में छोड़ दिया जाता है ताकि बाद का कंटेनर क्लोजर गायब न हो जाए। - हेडिंग-आईडी सफ़िक्स (ATX हेडिंग के आखिर में क्लासिक
{#id}/ MDX{/* #id */}) — लाइन से पूरी तरह से हटा दिया जाता है और मॉडल को नहीं भेजा जाता है। रीस्टोर करने के बाद उन्हें मेल खाने वाली हेडिंग के आखिर में वापस पिन कर दिया जाता है ताकि Docusaurus को अभी भी एक मान्य आईडी दिखाई दे। हेडिंग के बीच की टिप्पणियाँ टेक्स्ट में बनी रहती हैं और बाद की MDX /{#…}लेयर्स द्वारा हैंडल की जाती हैं। मास्क्ड फ़ेंस के अंदर की हेडिंग्स हटाई नहीं जाती हैं। - HTML टैग और टिप्पणियाँ (
<strong>,<!-- ... -->, आदि) - एक ज्ञात अलाउलिस्ट से लोअरकेस HTML टैग{{HTM_N}}टोकन से बदल दिए जाते हैं। कैपिटलाइज़्ड JSX टैग (<Highlight>,<Tabs>,</Tab>) MDX लेयर (चरण 6) द्वारा अलग से हैंडल किए जाते हैं। - एडमोनिशन मार्कर (
:::note,:::) - केवल शुरुआती लाइन पर डायरेक्टिव प्रीफ़िक्स को{{ADM_OPEN_N}}से बदल दिया जाता है; उसी लाइन के किसी भी टाइटल को मॉडल के अनुवाद के लिए छोड़ दिया जाता है। सटीक मूल टेक्स्ट के साथ रीस्टोर किया जाता है। - डॉक एंकर (HTML
<a id="…">, बची हुई मिड-हेडिंग Docusaurus{#…}) - हूबहू संरक्षित किए जाते हैं। - केवल-MDX कंस्ट्रक्ट्स (
src/processors/mdx-placeholders.ts):- MDX टिप्पणियाँ (
{/* … */}, जिसमें एक मिड-हेडिंग{/* #my-id */}शामिल है जो लाइन-एंड सफ़िक्स नहीं था) को{{MDX_N}}से बदल दिया जाता है। - कैपिटलाइज़्ड JSX टैग (
<Highlight>,<Tabs>,<TabItem>,<TOCInline />,</Highlight>) -{{MDX_N}}के रूप में संरक्षित किए जाते हैं, जिसमें अनुवाद योग्य स्ट्रिंग एट्रिब्यूट (label,tooltip,aria-label) टैग के अंदर{{JXA_N}}के रूप में फिर से लिखे जाते हैं, जब तक कि एट्रिब्यूट का नामdocs[].protectAttributesमें दिखाई न दे;<Tabs values={[ { label: '…' } ]}>ऑब्जेक्ट लिटरल्स के अंदरlabel:(docs[].protectKeysके ज़रिए स्किप करने योग्य) और<TabItem value="…">(जब कोईlabelएट्रिब्यूट मौजूद नहीं होता है, तो लोअरकेस स्लग-जैसे मानों को स्किप करते हुए) भी निकाले जाते हैं। सेगमेंट में||JXA_N: …||लाइनों के रूप में जोड़ा जाता है,restoreMdxद्वारा वापस मर्ज किया जाता है। - MDX ब्रेस एक्सप्रेशन (
{frontMatter.title},style={{…}}) - डेप्थ-अवेयर मैचिंग, को{{MDX_N}}से बदल दिया जाता है।
- MDX टिप्पणियाँ (
- मार्कडाउन URLs (
](url),src="…") - अनुवाद के बाद एक मैप से रीस्टोर किए जाते हैं। - इनलाइन कोड स्पैन (
`code`) और बोल्ड-रैप किया गया इनलाइन कोड (**code**) - संरक्षित किए जाते हैं। - मार्कडाउन एम्फ़सिस (वैकल्पिक, CJK/RTL लोकेल के लिए ऑटो-एनेबल्ड) - एम्फ़सिस डिलिमिटर्स मास्क किए गए।
मॉडल के वापस आने के बाद, translate-docs मैप्स को रीस्टोर करता है और सेगमेंट को मान्य करता है: डबल-ब्रेस टोकन का वही मल्टीसेट मौजूद होना चाहिए, स्ट्रक्चरल टोकन ({{HTM_N}}, एडमोनिशन मार्कर, {{CDF_N}}) को अपना क्रमित सबसीक्वेंस बनाए रखना चाहिए (सामग्री टोकन जैसे {{ILC_N}} / {{URL_N}} / {{SE}} शब्द क्रम के साथ स्थानांतरित हो सकते हैं), रीस्टोर किए गए HTML टैग प्रकारों को अनप्रोटेक्टेड स्रोत से मेल खाना चाहिए, और कोई भी बचा हुआ डबल-ब्रेस आइडेंटिफ़ायर स्रोत में पहले से मौजूद होना चाहिए (इसलिए बनाए गए टोकन विफल हो जाते हैं)। दस्तावेज़ प्रॉम्प्ट मॉडल से प्रत्येक टोकन को एक बार कॉपी करने, स्ट्रक्चरल-टोकन क्रम बनाए रखने और नए डबल-ब्रेस रैपर न बनाने के लिए भी कहता है; मैकेनिकल जाँचें आधिकारिक बनी रहती हैं।
एस्ट्रो टेम्प्लेट और एमडीएक्स जेएसएक्स के लिए साझा विशेषता/कुंजी सुरक्षा src/processors/expression-attribute-protection.ts में लागू की जाती है और docs[].protectAttributes और docs[].protectKeys द्वारा प्रति ब्लॉक संचालित की जाती है (देखें protectAttributes / protectKeys)।
कैश (TranslationCache)
एसक्यूलाइट डेटाबेस (node:sqlite के माध्यम से) (source_hash, locale) द्वारा translated_text, model, filepath, last_hit_at, और संबंधित फ़ील्ड के साथ कुंजीबद्ध पंक्तियों को संग्रहीत करता है। हैश सामान्यीकृत सामग्री (व्हाइटस्पेस कोलैप्स) के SHA-256 के पहले 16 हेक्स वर्ण हैं।
प्रत्येक रन पर, सेगमेंट को हैश × लोकेल द्वारा देखा जाता है। केवल कैश मिस LLM पर जाते हैं। अनुवाद के बाद, वर्तमान अनुवाद स्कोप में उन सेगमेंट पंक्तियों के लिए last_hit_at रीसेट किया जाता है जिन्हें हिट नहीं किया गया था। दस्तावेज़ अनुवाद के दौरान सफल कैश हिट उस सेगमेंट के लिए पुरानी translation_failures पंक्तियों को साफ़ करते हैं।
cleanup पहले sync --force-update चलाता है, फिर:
- पुरानी सेगमेंट पंक्तियों को हटाता है (शून्य
last_hit_at/ खाली फ़ाइलपाथ); - जब हल किया गया स्रोत पथ डिस्क पर अनुपलब्ध हो तो
file_trackingकुंजियों को छाँटता है (doc-block:…,json-block:…,svg-files:…, आदि); - उन अनुवाद पंक्तियों को हटाता है जिनका मेटाडेटा फ़ाइलपाथ एक अनुपलब्ध फ़ाइल को इंगित करता है;
- अनाथ
translation_failuresपंक्तियों को छाँटता है; - अनाथ
markdown_source_issuesपंक्तियों को छाँटता है जिनका हल किया गया स्रोत पथ डिस्क पर अनुपलब्ध है; - कॉन्फ़िग से अनुपस्थित लोकेल के लिए कैश पंक्तियों को हटाता है (
sourceLocale, रूटtargetLocales, और कोई भी प्रति-ब्लॉकdocs[]/json[]targetLocales; केवल SQLite — जेनरेट की गई फ़ाइलों को हटाने के लिएpurge-localeका उपयोग करें)।
यह cache.db का बैकअप नहीं लेता है जब तक कि --backup <path> पास नहीं किया जाता है, जो पहले उस पथ पर एक बैकअप लिखता है।
बिल किए गए मॉडल कॉल (स्वीकृत अनुवाद और रद्द किए गए पुनःप्रयास) api_calls में संग्रहीत किए जाते हैं। कॉल रिकॉर्ड करने वाले कमांड के बाद, सात UTC कैलेंडर दिनों से पुरानी विवरण पंक्तियाँ मासिक api_totals में स्थानांतरित हो जाती हैं। usage और डैशबोर्ड का उपयोग और लागत दृश्य दोनों तालिकाओं को संयोजित करते हैं। उपयोग और लागत देखें।
शब्दावली Context नोट्स और glossary.contextFiles को फ़िंगरप्रिंट किया जाता है (prompt_context_hash) और UI, दस्तावेज़ों, JSON, SVG और प्रूफरीड प्रॉम्प्ट में इंजेक्ट किया जाता है। उस मार्गदर्शन को बदलने से अगली रन पर मिलान वाले कैश किए गए सेगमेंट और फ़ाइल-ट्रैकिंग पंक्तियाँ अमान्य हो जाती हैं। डैशबोर्ड user-edited कैश पंक्तियाँ रखी जाती हैं। गैर-अनिवार्य पंक्ति पर केवल पसंदीदा शब्दावली अनुवाद को बदलने से मौजूदा कैश --force / --force-update तक यथावत रहता है। एक Force पंक्ति कैश से केवल उन सेगमेंट के लिए चूक जाती है जिनके स्रोत में वह शब्द शामिल है जब संग्रहीत टेक्स्ट में पहले से अनिवार्य अनुवाद शामिल नहीं होता है, और अपरिवर्तित-फ़ाइल स्किप उस फ़ाइल के लिए अस्वीकार कर दिया जाता है जिसके आउटपुट में अभी भी इसकी कमी है। उस पंक्ति पर Context को खाली छोड़ दें; एक संदर्भ नोट अभी भी पूरे लोकेल को रीफ़्रेश करता है। मार्कडाउन एक अनुवादित सेगमेंट को भी अस्वीकार करता है जो उद्धृत दो से पाँच शब्दों वाले UI लेबल (कैटलॉग कुंजी या एक सीडेड लेबल-आकार का उपसर्ग) को छोड़ देता है। एक उद्धरण बोल्ड, इनलाइन कोड, एक शीर्षक, या एक पंक्ति जो केवल वह लेबल है, होता है। वाक्य के भीतर शीर्षक केस एक संकेत है, ताकि अनुवाद में विभक्ति हो सके (हिंदी Cursor account शब्दकोश रूप कर्सर खाता के बजाय कर्सर खाते बन सकता है)। एक एकल-सामग्री-शब्द लेबल जैसे Sign in एक संकेत रहता है। जाँच अनुवाद में पूंजीकरण को अनदेखा करती है, इसलिए वाक्य में एक छोटा अक्षर वाला लेबल तब भी गिना जाता है जब स्रोत इसका उल्लेख करता है। सामान्य गद्य जो उन्हीं शब्दों का उपयोग करता है, उन्हें विभक्ति कर सकता है। एक सीडेड उपसर्ग एक पूंजीकृत लेबल होना चाहिए जिसका साझा अनुवाद एक छोटा वाक्यांश हो जिसमें कोई प्लेसहोल्डर न हो; वाक्य के मूल शब्द सीडेड नहीं होते हैं। वह जाँच अगले मॉडल को पुनः प्रयास करती है और सेगमेंट को विभाजित नहीं करती है।
translate-docs कमांड फ़ाइल ट्रैकिंग का भी उपयोग करता है ताकि मौजूदा, अप-टू-डेट आउटपुट वाले अपरिवर्तित स्रोत काम को पूरी तरह से छोड़ सकें। --check-cache अपेक्षित लेखन प्रणाली के साथ लोकेल को फिर से खोलता है ताकि कैश किए गए सेगमेंट को फिर से मान्य किया जा सके; --force-update सेगमेंट कैश का उपयोग करते हुए भी हर लोकेल के लिए फ़ाइल प्रोसेसिंग को फिर से चलाता है; --force फ़ाइल ट्रैकिंग को साफ़ करता है और API अनुवाद के लिए सेगमेंट कैश रीड को बायपास करता है। जब मार्कडाउन सेगमेंट के लिए कोशिश किए गए मॉडल AST सत्यापन में विफल होते हैं, तो translate-docs सेगमेंट को धीरे-धीरे विभाजित कर सकता है और छोटे हिस्सों को फिर से कोशिश कर सकता है (docs[].segmentSplitting.qualityRetrySplit, डिफ़ॉल्ट रूप से चालू)। वही गुणवत्ता त्रुटि तीन बार उस मॉडल सूची को जल्दी समाप्त कर देती है। पूरी फ़्लैग तालिका के लिए दस्तावेज़ — कैश व्यवहार और फ़्लैग देखें।
बैच प्रॉम्प्ट प्रारूप: translate-docs --prompt-format केवल LlmClient.translateDocumentBatch के लिए एक्सएमएल (<seg> / <t>) या जेएसओएन सरणी/ऑब्जेक्ट आकार का चयन करता है; निष्कर्षण, प्लेसहोल्डर और सत्यापन अपरिवर्तित रहते हैं। बैच प्रॉम्प्ट प्रारूप देखें।
आउटपुट पथ रिज़ॉल्यूशन
resolveDocumentationOutputPath(config, cwd, locale, relPath, kind) एक स्रोत-सापेक्ष पथ को आउटपुट पथ पर मैप करता है:
nestedशैली (डिफ़ॉल्ट): मार्कडाउन के लिए{outputDir}/{locale}/{relPath}।doc-systemशैली:docsRootके तहत, आउटपुट{outputDir}/{locale}/[localeSubpath/]{relativeToDocsRoot}का उपयोग करते हैं;docsRootके बाहर के पथ नेस्टेड लेआउट पर वापस आ जाते हैं। उपनाम:docusaurus(डिफ़ॉल्टlocaleSubpath= Docusaurus प्लगइन पथ),astro-starlight(डिफ़ॉल्ट खालीlocaleSubpath),vitepress(खालीlocaleSubpathके साथdoc-systemके समान; BCP-47 फ़ोल्डर केसिंग को संरक्षित करता है)।flatशैली:{outputDir}/{stem}.{locale}{extension}। जबflatPreserveRelativeDirtrueहोता है, तो स्रोत उपनिर्देशिकाएँoutputDirके तहत रखी जाती हैं।- कस्टम
pathTemplate:{outputDir},{locale},{LOCALE},{relPath},{stem},{basename},{extension},{docsRoot},{relativeToDocsRoot}का उपयोग करके कोई भी मार्कडाउन लेआउट। - कस्टम
jsonPathTemplate: JSON लेबल फ़ाइलों के लिए अलग कस्टम लेआउट, समान प्लेसहोल्डर का उपयोग करके। linkRewriteDocsRootफ्लैट-लिंक रीराइटर को सही उपसर्गों की गणना करने में मदद करता है जब अनुवादित आउटपुट डिफ़ॉल्ट प्रोजेक्ट रूट के अलावा कहीं और रूट किया जाता है।
फ्लैट लिंक रीराइटिंग
जब docsOutput.style === "flat", अनुवादित मार्कडाउन फ़ाइलें लोकेल प्रत्यय के साथ स्रोत के बगल में रखी जाती हैं। पृष्ठों के बीच सापेक्ष लिंक को फिर से लिखा जाता है ताकि readme.de.md में [Guide](./guide.md) guide.de.md की ओर इशारा करे। rewriteRelativeLinks द्वारा नियंत्रित (कस्टम pathTemplate के बिना फ्लैट शैली के लिए स्वतः सक्षम)। वही पास postProcessing.regexAdjustments चलने से पहले गैर-मार्कडाउन एसेट यूआरएल में प्रति-फ़ाइल गहराई उपसर्ग जोड़ता है — फ्लैट लिंक रीराइटर देखें।
JSON आंतरिक
| चरण | घटक | परिणाम |
|---|---|---|
| 1 | json[].contentPaths | फ़ाइलें हल की गईं (फ़ाइल, निर्देशिका, या ग्लोब) |
| 2 | NestedJsonExtractor | keyPolicy (डॉट पथ + मिनिमाच) द्वारा चयनित स्ट्रिंग लीव्स |
| 3 | PlaceholderHandler + बैच + TranslationCache | कैश हिट → छोड़ें; मिस → LlmClient.translateDocumentBatch (साझा एसक्यूलाइट) |
| 4 | NestedJsonExtractor.reassemble | expandJsonBlockOutputPath(outputPathTemplate) के माध्यम से आउटपुट फ़ाइल |
NestedJsonExtractor(src/extractors/nested-json-extractor.ts) मनमाने ढंग से नेस्टेड JSON को पार करता है और प्रति अनुवाद योग्य स्ट्रिंग लीफ एक सेगमेंट उत्सर्जित करता है।keyPolicy.mode(allowlist,denylist, याboth) डॉट नोटेशन पर मिनिमैच के साथ पाथ को फ़िल्टर करता है (slugजैसे नंगे नाम अंतिम कुंजी सेगमेंट से मेल खाते हैं)।- कैश फ़ाइल ट्रैकिंग
file_trackingमेंjson-block:{blockIndex}:{projectRelPath}का उपयोग करती है (दस्तावेज़ों और SVG के समानcacheDir)। - Docusaurus
write-translationsकैटलॉग ({ message, description }आकार) के लिए नहीं — वे दस्तावेज़ों का उपयोग करते हैं (docs[].docusaurusCatalogDir+JsonExtractortranslate-docsके अंदर)। t()UI स्ट्रिंग्स के लिए नहीं — UI स्ट्रिंग्स (strings.json+ फ्लैट बंडल)।- CLI:
translate-json;src/cli/translate-json-run.tsमें ऑर्केस्ट्रेशन। टेम्पलेट प्रारंभ करें:ui-json-bundles।
साझा अवसंरचना
LlmClient
Vercel AI SDK (ai + @ai-sdk/openai-compatible) पर निर्मित प्रदाता-अज्ञेयवादी चैट क्लाइंट। यह provider / providers से सक्रिय प्रदाता को हल करता है, उस प्रदाता के baseUrl + API कुंजी के लिए एक OpenAI-संगत क्लाइंट (createOpenAICompatible) बनाता है, और सभी कॉलों को generateText के माध्यम से रूट करता है। OpenRouterClient को एक अप्रचलित उपनाम के रूप में रखा गया है। मुख्य व्यवहार:
- मॉडल फ़ॉलबैक: हल की गई सूची में प्रत्येक मॉडल को क्रम से आज़माता है; अनुरोध या पार्स विफलताओं पर फ़ॉलबैक करता है। प्रत्येक लक्ष्य स्थानीय को अपनी हल की गई श्रृंखला मिलती है: कॉन्फ़िगर किए जाने पर
localeModels(locale)पहले, फिरuiModels(केवल UI पाइपलाइन), फिरtranslationModels। दस्तावेज़, JSON और SVG अनुवाद गैर-UI श्रृंखला के साथ प्रति-स्थानीय क्लाइंट बनाते हैं। इसके बजायbench-modelsकमांड प्रति कॉन्फ़िगर किए गए आईडी के लिए एक एकल-मॉडल क्लाइंट बनाता है (translationModels,uiModels, औरlocaleModelsका संघ;translationModels: [id], कोई फ़ॉलबैक नहीं) ताकि यह प्रत्येक मॉडल का समय और मूल्य स्वतंत्र रूप से निर्धारित कर सके। - अनुरोध टाइमआउट: सक्रिय प्रदाता पर
requestTimeout(सेकंड) याrequestTimeoutMs, अन्यथा कॉन्फ़िग के शीर्ष पर समान कुंजियाँ (डिफ़ॉल्ट 120 सेकंड),AbortSignal.timeoutके माध्यम से प्रत्येक अनुरोध को रद्द करता है। वही मानGET /modelsपर लागू होता है जब CLIcheck-models(किसी भी प्रदाता) के लिए प्रदाता की मॉडल सूची लोड करता है। वैकल्पिक प्री-फ़्लाइट फ़िल्टर जो अज्ञात मॉडल आईडी को हटाता है, केवल तभी चलता है जब सक्रिय प्रदाता OpenRouter हो। - OpenRouter अतिरिक्त सुविधाएँ (केवल तभी जब
openrouterसक्रिय हो):providerअनुरोध फ़ील्ड औरHTTP-Referer/X-Titleहेडर के माध्यम से थ्रूपुट रूटिंग। टोकन उपयोग प्रत्येक प्रदाता के लिए रिपोर्ट किया जाता है। OpenRouter और Cheaper Inference एक बिल की गई USD राशि भी लौटाते हैं (usage.cost; Cheaper Inferencecheaper_inference.billing.billed_cost_usdपर फ़ॉलबैक करता है)। जब प्रदाता उस राशि को छोड़ देता है, तो USD लागतproviders.<name>.modelPricingसे, फिर प्रदाता-व्यापीpricingडिफ़ॉल्ट से, फिर models.dev इनपुट और आउटपुट सूची मूल्य से गणना की जाती है, औरapi_callsपंक्ति पर संग्रहीत की जाती है। प्रदाता द्वारा रिपोर्ट की गई लागत (0सहित) कभी नहीं बदली जाती है। अज्ञात लागत अनसेट रहती है। एक कॉल का मूल्य निर्धारण केवल<cacheDir>/benchmark-scores.jsonके models.dev स्लाइस को पढ़ता है; यह languagebench या Arena फ़ाइल डाउनलोड नहीं करता है। - डीबग ट्रैफ़िक लॉग: यदि
debugTrafficFilePathसेट है, तो अनुरोध और प्रतिक्रिया JSON को एक फ़ाइल में जोड़ता है (प्रोग्रामेटिक)। CLI--debug-failedcacheDirके तहतFAILED-TRANSLATIONफ़ाइलें लिखता है जिसमें सिस्टम/उपयोगकर्ता प्रॉम्प्ट, कच्ची सहायक प्रतिक्रिया, और विफल UI, दस्तावेज़, JSON, और SVG अनुवाद-जाँच प्रयासों के लिए सत्यापन त्रुटियाँ होती हैं। प्रदाता API / खाली-बॉडी विफलताएँ केवल प्रॉम्प्ट-वाली फ़ाइल डंप करने के बजाय कंसोल पर प्रिंट होती हैं।
suggest-models और डैशबोर्ड का मॉडल टैब एलएलएम को कॉल नहीं करते हैं। वे सक्रिय प्रदाता के चैट कैटलॉग को लैंग्वेजबेंच ChrF और एलएमएरेना एरेना स्कोर से प्राप्त गुणवत्ता सूचकांक के साथ रैंक करते हैं। कीमत 3:1 के अनुपात में मिश्रित USD-प्रति-1M-टोकन दर है (कैटलॉग, फिर models.dev, फिर लैंग्वेजबेंच)। --quality सूचकांक के अनुसार सॉर्ट करता है; --price गुणवत्ता-मूल्य पैरेटो फ्रंटियर का अनुसरण करता है। वे वैकल्पिक रूप से providers.<name>.translationModels को प्रतिस्थापित करते हैं। एग्रीगेट्स <cacheDir>/benchmark-scores.json में रहते हैं। एआई मॉडल्स और सुझाव मॉडल देखें।
कॉन्फ़िग लोडिंग
loadI18nConfigFromFile(configPath, cwd) पाइपलाइन:
ai-i18n-tools.config.json(JSON) पढ़ें और पार्स करें।mergeWithDefaults-defaultI18nConfigPartialके साथ डीप-मर्ज करें, और किसी भीdocs[].sourceFilesप्रविष्टियों कोcontentPathsमें मर्ज करें।expandTargetLocalesFileReferenceInRawInput-targetLocalesको एक सरणी में परिवर्तित करें और पाथ-जैसे प्रविष्टियों को अस्वीकार करें (BCP-47 कोड होने चाहिए,ui-languages.jsonका पाथ नहीं);languagesManifestPathmergeWithDefaultsके दौरान{ui.flatOutputDir}/ui-languages.jsonपर डिफ़ॉल्ट होता है।expandDocumentationTargetLocalesInRawInput- प्रत्येकdocs[].targetLocalesप्रविष्टि के लिए समान।expandJsonTargetLocalesInRawInput- प्रत्येकjson[].targetLocalesप्रविष्टि के लिए समान।parseI18nConfig- Zod सत्यापन +validateI18nBusinessRules।applyProviderOverrideToRawInput- जब CLI पर-P/--providerपास किया जाता है।applyEnvOverrides-OPENROUTER_BASE_URL,OLLAMA_BASE_URL,I18N_SOURCE_LOCALE, औरI18N_TARGET_LOCALESको सेट होने पर लागू करें (API कुंजियाँLlmClientके अंदर प्रति प्रदाता अलग से हल की जाती हैं)।augmentConfigWithUiLanguagesMaster- बंडल किए गए मास्टर कैटलॉग से मैनिफेस्ट डिस्प्ले नाम संलग्न करें।assertEffectiveLocalesInUiLanguagesMaster- लागू होने पर मास्टर कैटलॉग के विरुद्ध लोकेल कोड को मान्य करें।
init initConfigTemplates से स्टार्टर कॉन्फ़िग लिखता है: ui-markdown (UI स्ट्रिंग्स और एक फ़्लैट README ब्लॉक), docs-markdown (केवल README और Markdown), ui-docusaurus, ui-starlight, ui-vitepress (VitePress डॉक्स + vitepressThemeCatalog), ui-nextra (Nextra डॉक्स + nextraDictionaryPath), ui-astro-website (साधारण Astro UI; .astro पेज अनुवाद के लिए docs[] जोड़ें), ui-json-bundles (केवल JSON json[]), ui-python, ui-python-gettext, ui-python-django, और ui-python-flask। --with-readme उसी README ब्लॉक को किसी भी टेम्पलेट में जोड़ता है जिसमें पहले से README.md सूचीबद्ध नहीं है, और translateDocs को चालू करता है। देखें UI स्ट्रिंग्स — इनिशियलाइज़ करें, अपने README और Markdown डॉक्स में i18n जोड़ें, और पायथन एप्लिकेशन।
लॉगर
Logger ANSI रंग आउटपुट के साथ debug, info, warn, error स्तरों का समर्थन करता है। वर्बोस मोड (-v) debug को सक्षम करता है। जब logFilePath सेट होता है, तो लॉग लाइनें उस फ़ाइल में भी लिखी जाती हैं।
स्व-स्थानीयकरण (उपकरण UI)
उपकरण अपने स्वयं के UI — CLI सहायता, उच्च-ट्रैफ़िक लॉग/सारांश/त्रुटि संदेश, और अनुवाद डैशबोर्ड — का स्थानीयकरण उस सामग्री से अलग करता है जिसे वह आपके लिए अनुवाद करता है।
- लोकेल रिज़ॉल्यूशन (
resolveUiLocaleमेंsrc/core/ui-locale.ts): UI लोकेल को-L/--ui-lang>AI_I18N_LANG> कॉन्फ़िगuiLanguage> होस्ट OS लोकेल (Intl.DateTimeFormat().resolvedOptions().locale) से चुनता है। उम्मीदवार को सामान्यीकृत किया जाता है और भेजे गए बंडल सेट से ठीक-ठीक या निकटतम भिन्नता (जैसेpt-PT→pt-BR,en-US→en-GB) द्वारा मिलान किया जाता है, स्रोत लोकेल (en-GB) पर वापस आता है। CLI सहायता बनने से पहले (प्री-पार्स आर्ग्व स्कैन) एक बार और कॉन्फ़िग लोड होने के बाद फिर से हल करता है ताकिuiLanguageलागू हो (फ़्लैग और env var अभी भी जीतते हैं)। - रनटाइम (
src/i18n/index.ts):{{name}}इंटरपोलेशन के साथ एक न्यूनतमt(source, vars), जोsrc/i18n/locales/<code>.jsonमें फ्लैट प्रति-लोकेल बंडलों के खिलाफ अंग्रेजी स्रोत स्ट्रिंग द्वारा कुंजीबद्ध है (बिल्ड परdist/i18n/localesमें कॉपी किया गया)। गुम हुई कुंजियाँ या बंडल स्रोत पाठ लौटाते हैं। यह UI स्ट्रिंग्स के समान कुंजी-के-डिफ़ॉल्ट मॉडल है — कोई हैश लुकअप नहीं है। - डैशबोर्ड: सर्वर हल किए गए UI लोकेल के लिए
{ locale, dir, bundle }लौटाते हुएGET /api/ui-i18nको उजागर करता है; फ्रंटएंड<html lang>/dirसेट करता है औरdata-i18n*विशेषताओं के माध्यम से स्थिर मार्कअप का स्थानीयकरण करता है। - डॉगफूडिंग: बंडल
pnpm i18n:self(sync-ui --ui-block src/i18n/strings.json) द्वारा उत्पादित होते हैं, जोai-i18n-tools.config.jsonमें CLI और डैशबोर्डuiब्लॉक को निकालता और अनुवाद करता है। कैटलॉग कुंजियाँsrc/cli/औरsrc/i18n/मेंt()कॉल से आती हैं, साथ हीsrc/dashboard-app/index.htmlमें डैशबोर्ड केdata-i18n*मार्कर से भी।
एक्सटेंशन पॉइंट
कस्टम फ़ंक्शन नाम (UI एक्सट्रैक्शन)
कॉन्फ़िग के माध्यम से गैर-मानक अनुवाद फ़ंक्शन नाम जोड़ें:
{
"ui": {
"uiExtractor": {
"funcNames": ["t", "i18n.t", "translate", "i18n.translate"],
"extensions": [".js", ".jsx", ".ts", ".tsx", ".astro", ".html"],
"htmlI18nAttributes": ["data-i18n", "data-i18n-title", "data-i18n-placeholder", "data-i18n-alt", "data-i18n-aria-label"]
}
}
}(ui.reactExtractor ui.uiExtractor के लिए पूरी तरह से समर्थित उपनाम है।)
extract के दौरान HTML मार्कर विशेषताओं को स्कैन करने के लिए extensions में .html / .htm जोड़ें। ui.uiExtractor.htmlI18nAttributes वैकल्पिक है और डिफ़ॉल्ट रूप से ["data-i18n", "data-i18n-title", "data-i18n-placeholder"] है; data-i18n तत्व textContent पर मैप करता है और data-i18n-<attr> उस विशेषता के मान पर मैप करता है (उदाहरण के लिए data-i18n-aria-label)।
कस्टम एक्सट्रैक्टर
पैकेज से ContentExtractor लागू करें:
import { BaseExtractor, type Segment } from 'ai-i18n-tools';
class MyExtractor extends BaseExtractor {
readonly name = 'my-format';
canHandle(filepath: string) { return filepath.endsWith('.myext'); }
extract(content: string, filepath: string): Segment[] { /* … */ }
reassemble(segments: Segment[], translations: Map<string, string>): string { /* … */ }
}'ai-i18n-tools' से निर्यात किए गए सार्वजनिक एक्सट्रैक्टर वर्गों का विस्तार करके कस्टम एक्सट्रैक्टर पंजीकृत करें (उदाहरण के लिए सबक्लास MarkdownExtractor)। CLI आंतरिक रूप से अंतर्निहित एक्सट्रैक्टरों को तार करता है; doc-translate.ts का कोई समर्थित गहरा आयात नहीं है।
कस्टम आउटपुट पाथ
किसी भी फ़ाइल लेआउट के लिए docsOutput.pathTemplate का उपयोग करें:
{
"docs": [
{
"docsOutput": {
"pathTemplate": "{outputDir}/{locale}/{relativeToDocsRoot}"
}
}
]
}स्रोत ट्री
पूर्ण src/ लेआउट (फ़ाइल-स्तरीय संदर्भ)
src/
├── index.ts Public API re-exports
│
├── cli/
│ ├── index.ts CLI entry point (commander)
│ ├── extract-strings.ts `extract` command implementation
│ ├── mark-html.ts `mark-html` command (insert bare `data-i18n*` markers into HTML)
│ ├── translate-ui-strings.ts `translate-ui` command implementation
│ ├── doc-translate.ts `translate-docs` command (documentation files only)
│ ├── translate-json-run.ts `translate-json` command (`json[]` nested locale bundles)
│ ├── translate-svg.ts `translate-svg` command (SVG files from `config.svg`)
│ ├── write-heading-ids.ts `write-heading-ids` command (markdown heading anchors)
│ ├── bench-models.ts `bench-models` command (per-model translate latency/token/cost benchmark)
│ ├── helpers.ts Shared CLI utilities
│ └── file-utils.ts File collection helpers
│
├── markdown/
│ └── write-heading-ids-core.ts Slug styles + `<a id="…">` insertion for `write-heading-ids`
│
├── core/
│ ├── types.ts Zod schemas + TypeScript types for all config shapes
│ ├── config.ts Config loading, merging, validation, init templates
│ ├── cache.ts SQLite translation cache (node:sqlite)
│ ├── prompt-builder.ts LLM prompt construction for docs and UI strings
│ ├── output-paths.ts Docusaurus / flat output path resolution
│ ├── ui-languages.ts ui-languages.json loading and locale resolution
│ ├── ui-locale.ts Resolve the tool's own UI locale (flag/env/config/OS → shipped bundle)
│ ├── locale-utils.ts BCP-47 normalisation, locale list parsing, script/Han-variant validation
│ └── errors.ts Typed error classes
│
├── extractors/
│ ├── base-extractor.ts Abstract base class for all extractors
│ ├── ui-string-extractor.ts JS/TS and `.astro` UI scanner (Babel via `ui-string-babel.ts`)
│ ├── ui-string-babel.ts Babel `t()` discovery (`extractUiCallsFromFileContent`)
│ ├── ui-string-locations.ts Source locations for extracted UI strings
│ ├── html-i18n-marks.ts HTML `data-i18n*` marker scanner + `mark-html` annotator
│ ├── classify-segment.ts Heuristic segment type classification
│ ├── markdown-extractor.ts Markdown / MDX segment extraction
│ ├── markdown-segment-split.ts Optional segment splitting for long markdown blocks
│ ├── frontmatter-fields.ts Selective YAML front matter field translation
│ ├── astro-template-extractor.ts `.astro` parse-and-replace (HTML + template expressions; used by `translate-docs`)
│ ├── json-extractor.ts Docusaurus catalog JSON extraction (`translate-docs`)
│ ├── nested-json-extractor.ts Arbitrary nested JSON leaves (`translate-json`, `json[]`)
│ └── svg-extractor.ts SVG text extraction
│
├── processors/
│ ├── placeholder-handler.ts Chain: HTML → admonitions → anchors → MDX → URLs → emphasis
│ ├── expression-attribute-protection.ts Shared protected attribute/key lists (Astro + MDX JSX)
│ ├── url-placeholders.ts Markdown URL protection/restore
│ ├── admonition-placeholders.ts Docusaurus admonition protection/restore
│ ├── anchor-placeholders.ts HTML anchor / heading ID protection/restore
│ ├── html-tag-placeholders.ts Lowercase HTML tag / comment protection ({{HTM_N}})
│ ├── placeholder-integrity.ts Pre/post-restore token sequence + tag-kind + invented {{IDENT}} checks
│ ├── mdx-placeholders.ts MDX comments, JSX tags, brace expressions, JSX attribute extraction
│ ├── batch-processor.ts Segment → batch grouping (count + char limits)
│ ├── validator.ts Post-translation structural checks
│ └── flat-link-rewrite.ts Relative link rewriting for flat output
│
├── api/
│ ├── llm-client.ts LlmClient: provider-agnostic chat client (AI SDK) with model fallback chain
│ └── provider-models-catalog.ts Fetch/parse any provider's OpenAI-compatible GET /models catalog
│
├── glossary/
│ ├── glossary.ts Glossary loading (CSV + auto-build from strings.json)
│ ├── matcher.ts Term hint extraction for prompts
│ └── translation-context.ts contextFiles loader and guidance fingerprints
│
├── runtime/
│ ├── index.ts Runtime re-exports
│ ├── template.ts interpolateTemplate, flipUiArrowsForRtl
│ ├── ui-language-display.ts getUILanguageLabel, getUILanguageLabelNative
│ └── i18next-helpers.ts RTL detection, i18next setup factories
│
├── i18n/ Self-localisation runtime for the tool's own UI
│ ├── index.ts t(source, vars) + bundle/manifest loaders (keyed by English source string)
│ └── locales/ Shipped UI bundles (de.json, es.json, …; generated by `pnpm i18n:self`)
│
├── dashboard-app/
│ ├── index.html Translation Dashboard static UI (HTML/CSS/JS)
│ ├── app.js
│ └── styles.css
│
├── server/
│ └── translation-dashboard.ts Express app for Translation Dashboard (cache / strings.json / glossary)
│
└── utils/
├── logger.ts Leveled logger with ANSI support
├── hash.ts Segment hash (SHA-256 first 16 hex)
├── table.ts Display-width aware table rendering (CJK/emoji column alignment)
├── load-dotenv.ts Load `.env` / `.env.local` beside the config when no API key is set
└── ignore-parser.ts .translate-ignore file parser