Skip to content

आर्किटेक्चर ​

आर्किटेक्चर अवलोकन ​

कोडबेस को चार परतों में व्यवस्थित किया गया है। मानसिक मॉडल के लिए इस अनुभाग का उपयोग करें; जब आपको फ़ाइल-स्तरीय विवरण की आवश्यकता हो तो स्रोत ट्री खोलें।

sync रन कैसे एक साथ फिट बैठता है ​

sync (और व्यक्तिगत अनुवाद कमांड) सक्षम सुविधाओं को क्रम में चलाते हैं:

चरणकमांडयह क्या करता है
1extract → translate-uiUI स्रोतों को स्कैन करें → strings.json अपडेट करें → फ़्लैट लोकेल JSON भरें (de.json, …)
2translate-svg (वैकल्पिक)config.svg के तहत SVG टेक्स्ट का अनुवाद करें
3translate-docsमार्कडाउन, MDX, .astro पेजों का अनुवाद करें; Docusaurus कैटलॉग JSON; Nextra _meta / डिक्शनरी .ts; VitePress थीम कैटलॉग
4translate-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)डिस्क पर फ़ाइलें
2UIStringExtractor (ui-string-babel.ts के माध्यम से बैबेल)MD5 हैश द्वारा कुंजीबद्ध खंड
3strings.jsonमास्टर कैटलॉग: { hash: { source, translated, models?, locations? } }
4LlmClient.translateUIBatch()स्रोत स्ट्रिंग्स का जेएसओएन सरणी → अनुवाद (+ प्रति बैच मॉडल आईडी)
5de.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 ​

मास्टर कैटलॉग का आकार है:

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 फ़ील्ड नहीं) को मैप करती है:

json
{
  "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 मॉडल देखें)।


दस्तावेज़ आंतरिक ​

चरणघटकपरिणाम
1Markdown / MDX / JSON / .astro फ़ाइलें (translate-docs)स्रोत फ़ाइलें
2MarkdownExtractor / JsonExtractor / AstroTemplateExtractorsegments[] — हैश + सामग्री के साथ टाइप किए गए खंड
3PlaceholderHandlerसंरक्षित पाठ — HTML, एडमोनिशन, एंकर, MDX, URL, इनलाइन कोड, टोकन के रूप में मास्क किया गया जोर
4splitTranslatableIntoBatchesbatches[] — गणना + वर्ण सीमा द्वारा समूहीकृत
5TranslationCache लुकअपकैश हिट → छोड़ें; मिस → LlmClient.translateDocumentBatch
6PlaceholderHandler.restoreAfterTranslationअंतिम पाठ — प्लेसहोल्डर बहाल
7resolveDocumentationOutputPathआउटपुट फ़ाइल — 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 / collectHtmlI18nLocations data-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 के अंदर नहीं चलता है; स्थिर फ्रैगमेंट आईडी के लिए स्रोत फ़ाइलों में अनुवाद या प्रकाशन से पहले इसे स्पष्ट रूप से चलाएं।

प्लेसहोल्डर सुरक्षा ​

अनुवाद से पहले, संवेदनशील वाक्य रचना को अपारदर्शी टोकन के साथ बदल दिया जाता है ताकि एलएलएम भ्रष्टाचार को रोका जा सके, इस क्रम में लागू किया जाता है (पुनर्स्थापना इसके विपरीत है):

  1. फ़ेंस्ड कोड ब्लॉक (तीन या ज़्यादा बैकटिक्स या टिल्ड, जिसमें एक लंबा फ़ेंस भी शामिल है जो एक छोटे फ़ेंस को रैप करता है) - पूरे फ़ेंस को, जानकारी स्ट्रिंग सहित, {{CDF_N}} से बदल दिया जाता है और दूसरे स्ट्रक्चरल टोकन के साथ क्रम में रखा जाता है। यह ::: code-group या ::: tip जैसे कंटेनरों के अंदर सैंपल को अपनी जगह पर रखता है। फ़ेंस जानकारी स्ट्रिंग्स (VitePress टैब लेबल) स्रोत भाषा में ही रहती हैं। एक बिना बंद किया हुआ ओपनर टेक्स्ट के रूप में छोड़ दिया जाता है ताकि बाद का कंटेनर क्लोजर गायब न हो जाए।
  2. हेडिंग-आईडी सफ़िक्स (ATX हेडिंग के आखिर में क्लासिक {#id} / MDX {/* #id */}) — लाइन से पूरी तरह से हटा दिया जाता है और मॉडल को नहीं भेजा जाता है। रीस्टोर करने के बाद उन्हें मेल खाने वाली हेडिंग के आखिर में वापस पिन कर दिया जाता है ताकि Docusaurus को अभी भी एक मान्य आईडी दिखाई दे। हेडिंग के बीच की टिप्पणियाँ टेक्स्ट में बनी रहती हैं और बाद की MDX / {#…} लेयर्स द्वारा हैंडल की जाती हैं। मास्क्ड फ़ेंस के अंदर की हेडिंग्स हटाई नहीं जाती हैं।
  3. HTML टैग और टिप्पणियाँ (<strong>, <!-- ... -->, आदि) - एक ज्ञात अलाउलिस्ट से लोअरकेस HTML टैग {{HTM_N}} टोकन से बदल दिए जाते हैं। कैपिटलाइज़्ड JSX टैग (<Highlight>, <Tabs>, </Tab>) MDX लेयर (चरण 6) द्वारा अलग से हैंडल किए जाते हैं।
  4. एडमोनिशन मार्कर (:::note, :::) - केवल शुरुआती लाइन पर डायरेक्टिव प्रीफ़िक्स को {{ADM_OPEN_N}} से बदल दिया जाता है; उसी लाइन के किसी भी टाइटल को मॉडल के अनुवाद के लिए छोड़ दिया जाता है। सटीक मूल टेक्स्ट के साथ रीस्टोर किया जाता है।
  5. डॉक एंकर (HTML <a id="…">, बची हुई मिड-हेडिंग Docusaurus {#…}) - हूबहू संरक्षित किए जाते हैं।
  6. केवल-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}} से बदल दिया जाता है।
  7. मार्कडाउन URLs (](url), src="…") - अनुवाद के बाद एक मैप से रीस्टोर किए जाते हैं।
  8. इनलाइन कोड स्पैन (`code`) और बोल्ड-रैप किया गया इनलाइन कोड (**code**) - संरक्षित किए जाते हैं।
  9. मार्कडाउन एम्फ़सिस (वैकल्पिक, 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}। जब flatPreserveRelativeDir true होता है, तो स्रोत उपनिर्देशिकाएँ 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 आंतरिक ​

चरणघटकपरिणाम
1json[].contentPathsफ़ाइलें हल की गईं (फ़ाइल, निर्देशिका, या ग्लोब)
2NestedJsonExtractorkeyPolicy (डॉट पथ + मिनिमाच) द्वारा चयनित स्ट्रिंग लीव्स
3PlaceholderHandler + बैच + TranslationCacheकैश हिट → छोड़ें; मिस → LlmClient.translateDocumentBatch (साझा एसक्यूलाइट)
4NestedJsonExtractor.reassembleexpandJsonBlockOutputPath(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 + JsonExtractor translate-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 पर लागू होता है जब CLI check-models (किसी भी प्रदाता) के लिए प्रदाता की मॉडल सूची लोड करता है। वैकल्पिक प्री-फ़्लाइट फ़िल्टर जो अज्ञात मॉडल आईडी को हटाता है, केवल तभी चलता है जब सक्रिय प्रदाता OpenRouter हो।
  • OpenRouter अतिरिक्त सुविधाएँ (केवल तभी जब openrouter सक्रिय हो): provider अनुरोध फ़ील्ड और HTTP-Referer / X-Title हेडर के माध्यम से थ्रूपुट रूटिंग। टोकन उपयोग प्रत्येक प्रदाता के लिए रिपोर्ट किया जाता है। OpenRouter और Cheaper Inference एक बिल की गई USD राशि भी लौटाते हैं (usage.cost; Cheaper Inference cheaper_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-failed cacheDir के तहत 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) पाइपलाइन:

  1. ai-i18n-tools.config.json (JSON) पढ़ें और पार्स करें।
  2. mergeWithDefaults - defaultI18nConfigPartial के साथ डीप-मर्ज करें, और किसी भी docs[].sourceFiles प्रविष्टियों को contentPaths में मर्ज करें।
  3. expandTargetLocalesFileReferenceInRawInput - targetLocales को एक सरणी में परिवर्तित करें और पाथ-जैसे प्रविष्टियों को अस्वीकार करें (BCP-47 कोड होने चाहिए, ui-languages.json का पाथ नहीं); languagesManifestPath mergeWithDefaults के दौरान {ui.flatOutputDir}/ui-languages.json पर डिफ़ॉल्ट होता है।
  4. expandDocumentationTargetLocalesInRawInput - प्रत्येक docs[].targetLocales प्रविष्टि के लिए समान।
  5. expandJsonTargetLocalesInRawInput - प्रत्येक json[].targetLocales प्रविष्टि के लिए समान।
  6. parseI18nConfig - Zod सत्यापन + validateI18nBusinessRules।
  7. applyProviderOverrideToRawInput - जब CLI पर -P / --provider पास किया जाता है।
  8. applyEnvOverrides - OPENROUTER_BASE_URL, OLLAMA_BASE_URL, I18N_SOURCE_LOCALE, और I18N_TARGET_LOCALES को सेट होने पर लागू करें (API कुंजियाँ LlmClient के अंदर प्रति प्रदाता अलग से हल की जाती हैं)।
  9. augmentConfigWithUiLanguagesMaster - बंडल किए गए मास्टर कैटलॉग से मैनिफेस्ट डिस्प्ले नाम संलग्न करें।
  10. 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 एक्सट्रैक्शन) ​

कॉन्फ़िग के माध्यम से गैर-मानक अनुवाद फ़ंक्शन नाम जोड़ें:

json
{
  "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 लागू करें:

ts
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 का उपयोग करें:

json
{
  "docs": [
    {
      "docsOutput": {
        "pathTemplate": "{outputDir}/{locale}/{relativeToDocsRoot}"
      }
    }
  ]
}

स्रोत ट्री ​

पूर्ण src/ लेआउट (फ़ाइल-स्तरीय संदर्भ)
text
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

MIT लाइसेंस के तहत जारी किया गया।