HTML पृष्ठ

जब किसी स्थैतिक साइट को प्रति लोकेल एक अनुवादित .html या .htm फ़ाइल की आवश्यकता हो, तो दस्तावेज़ पाइपलाइन का उपयोग करें। translate-docs स्रोत पृष्ठ का अनुवाद करता है, इसके सापेक्ष लिंक को पुनः लिखता है, और outputDir के अंतर्गत लोकेल प्रतियाँ लिखता है। किसी ब्राउज़र i18n रनटाइम या data-i18n* मार्कर की आवश्यकता नहीं होती है।

इसके बजाय सादे HTML ऐप्स का उपयोग तब करें जब एक HTML फ़ाइल अपनी जगह पर रहती है और एक ब्राउज़र स्क्रिप्ट फ्लैट JSON से स्ट्रिंग्स को तुरंत स्वैप करती है। एक ही फ़ाइल को दोनों पाइपलाइनों में न डालें; CLI चेतावनी देता है जब कोई HTML फ़ाइल docs[] स्रोत और ui.sourceRoots कैटलॉग स्रोत दोनों होती है।

रन करने योग्य examples/plain-html-docs साइट पोर्ट 3092 पर अंग्रेज़ी प्रदान करती है और पुर्तगाली को site/pt-BR/ में लिखती है।

त्वरित शुरुआत

एक कार्यशील कॉन्फ़िगरेशन स्कैफ़ोल्ड करें:

ai-i18n-tools init -t docs-plain-html [-P <provider>]

या इस HTML भाग को किसी ऐसे ai-i18n-tools.config.json में जोड़ें जिसमें पहले से ही एक LLM प्रदाता हो:

{
  "sourceLocale": "en",
  "targetLocales": ["pt-BR"],
  "features": {
    "translateDocs": true,
    "translateUIStrings": false
  },
  "docs": [
    {
      "description": "Static HTML pages",
      "contentPaths": ["site/"],
      "outputDir": "site",
      "addFrontmatter": false,
      "docsOutput": {
        "style": "nested",
        "docsRoot": "site",
        "localizedAssets": {
          "include": ["img/**"],
          "pattern": "{stem}-{locale}{ext}",
          "onlyIfExists": true
        },
        "html": {
          "languageList": {
            "format": "links",
            "label": "local"
          },
          "hreflang": {
            "siteUrl": "https://example.com",
            "xDefault": "en",
            "stripIndexHtml": true
          }
        }
      }
    }
  ]
}

docsRoot, contentPaths के अंदर का स्रोत ट्री होना चाहिए। लोकेल निर्देशिका डाले जाने से पहले इसे स्ट्रिप किया जाता है। उपरोक्त कॉन्फ़िग के साथ:

site/index.html       → site/pt-BR/index.html
site/about.html       → site/pt-BR/about.html

वैकल्पिक रूप से प्रत्येक स्रोत पृष्ठ में भाषा-सूची और hreflang मार्कर जोड़ें, फिर चलाएँ:

ai-i18n-tools translate-docs
# Or run every enabled pipeline:
ai-i18n-tools sync

यह कमांड स्रोत-भाषा फ़ाइलों में मार्कर इंटीरियर को भी रिफ्रेश करती है। outputDir के अंतर्गत लोकेल फ़ाइलों को जनरेट किए गए आउटपुट के रूप में मानें; स्रोत पृष्ठों को संपादित करें और कमांड को फिर से चलाएँ।

क्या अनुवादित होता है

HTML एक्सट्रैक्टर इनका अनुवाद करता है:

• दृश्यमान टेक्स्ट जिसमें अक्षर होते हैं, जिसमें <title> और इनलाइन मार्कअप के आसपास का टेक्स्ट शामिल है
• alt, title, aria-label, और placeholder विशेषता मान
• <input type="submit"> और <input type="button"> पर value
• meta name="description", meta property="og:title", और meta property="og:description" पर content

इनलाइन तत्व जैसे <a>, <em>, <strong>, <span>, <img>, और <br> सुरक्षित रखे जाते हैं जबकि आसपास के वाक्य का अनुवाद किया जाता है। कोड-जैसे इनलाइन तत्व जैसे <code> और <kbd> बरकरार रखे जाते हैं:

<p>Run <code>pnpm build</code> before deployment.</p>

संपूर्ण script, style, textarea, pre, और code सबट्री को बिना बदले कॉपी किया जाता है। अन्य विशेषताएँ—जिनमें class, id, src, href, और URL-युक्त मेटाडेटा शामिल हैं—मॉडल पर नहीं भेजी जाती हैं।

प्रत्येक लोकेल प्रति पर, पाइपलाइन <html lang="…"> और लोकेल का dir (ltr या rtl) सेट करती है। स्रोत पृष्ठ अपने लेखक द्वारा लिखे गए lang और dir को रखता है। UTF-8 HTML का उपयोग करें; CLI चेतावनी देता है जब कोई <meta charset> किसी अन्य एन्कोडिंग को घोषित करता है।

आउटपुट लेआउट

सामान्य स्थैतिक-साइट लेआउट के लिए, सेट करें:

{
  "outputDir": "site",
  "docsOutput": {
    "style": "nested",
    "docsRoot": "site"
  }
}

style: "nested" {outputDir}/{locale}/{path relative to docsRoot} लिखता है। style: "flat" लोकेल-प्रत्यय वाली फ़ाइलें जैसे site/about.pt-BR.html लिखता है। सभी शैलियों और कस्टम पथ टेम्पलेट्स के लिए आउटपुट लेआउट देखें।

outputDir के अंतर्गत जनरेट की गई लोकेल निर्देशिकाएँ और फ्लैट लोकेल फ़ाइलनाम भविष्य के स्रोत डिस्कवरी से बाहर रखे जाते हैं। यह site/pt-BR/index.html या site/index.pt-BR.html को दोबारा अनुवादित होने से रोकता है।

लिंक और छवियाँ

.html या .htm में समाप्त होने वाले सापेक्ष लिंक पुनः लिखे जाते हैं जब उनका लक्ष्य उसी docs[] ब्लॉक में कोई अन्य स्रोत पृष्ठ होता है। क्वेरी स्ट्रिंग्स और फ्रैगमेंट्स सुरक्षित रखे जाते हैं। उदाहरण के लिए, site/index.html में href="about.html#history", site/pt-BR/index.html में href="./about.html#history" बन जाता है।

अन्य सापेक्ष href, src, srcset, और poster URL को डेप्थ-प्रीफ़िक्स्ड किया जाता है ताकि साझा फ़ाइलें अभी भी लोकेल पृष्ठ से रिज़ॉल्व हो सकें। निरपेक्ष URL, प्रोटोकॉल-सापेक्ष URL, data: URL, और केवल-फ्रैगमेंट लिंक अपरिवर्तित रहते हैं। रूट-सापेक्ष URL रूट-सापेक्ष ही रहते हैं।

docsOutput.localizedAssets एक लोकेल-विशिष्ट छवि या आइकन फ़ाइलनाम चुन सकता है:

"localizedAssets": {
  "include": ["img/**"],
  "pattern": "{stem}-{locale}{ext}",
  "onlyIfExists": true
}

प्लेसहोल्डर	अर्थ
{stem}	एक्सटेंशन के बिना फ़ाइलनाम
{ext}	एक्सटेंशन, डॉट सहित
{basename}	एक्सटेंशन के साथ फ़ाइलनाम
{locale}	कॉन्फ़िगर किए गए अनुसार लोकेल कोड (pt-BR)
{llocale}	लोअरकेस लोकेल
{LOCALE}	अपरकेस लोकेल

img/trulli.jpg img/trulli-pt-BR.jpg बन जाता है। onlyIfExists: true (डिफ़ॉल्ट) के साथ, उस URL का उपयोग केवल तभी किया जाता है जब स्थानीयकृत फ़ाइल मौजूद हो; अन्यथा मूल साझा एसेट को रखा जाता है। onlyIfExists: false केवल तभी सेट करें जब कोई अन्य बिल्ड या CDN चरण उन फ़ाइलों की गारंटी देता हो।

include img/** जैसे URL पथों से मेल खाता है। स्थानीयकृत उम्मीदवारों—विशेषकर /img/trulli.jpg जैसे रूट-सापेक्ष URL—की जाँच करने के लिए फ़ाइल सिस्टम डायरेक्टरी सेट करने हेतु assetRoot का उपयोग करें।

वही स्थानीयकरण नियम srcset, poster, <source src>, आइकन <link href>, और og:image / twitter:image पर लागू होते हैं। पाइपलाइन संदर्भों को पुनः लिखती है लेकिन एसेट फ़ाइलें नहीं बनाती, अनुवाद नहीं करती, या कॉपी नहीं करती। CSS url() मान पुनः नहीं लिखे जाते हैं।

भाषा सूची और hreflang

दृश्यमान नेविगेशन के स्थान पर एक भाषा-सूची युग्म रखें, और <head> के अंदर एक hreflang युग्म रखें:

<nav>
  <ul>
    <!-- ai-i18n:lang-list -->
    <!-- /ai-i18n:lang-list -->
  </ul>
</nav>
<!-- ai-i18n:hreflang -->
<!-- /ai-i18n:hreflang -->

प्रत्येक रन पर, पाइपलाइन केवल प्रत्येक युग्म के बीच की सामग्री को बदलती है। यह प्रत्येक लोकेल कॉपी और स्रोत पृष्ठ को अपडेट करती है, जिससे वैकल्पिक लिंक पारस्परिक बने रहते हैं। script, style, pre, और code के अंदर के मार्कर अनदेखे कर दिए जाते हैं। --verbose के साथ, CLI चेतावनी देता है जब कोई कॉन्फ़िगर किया गया युग्म गायब होता है।

"html": {
  "languageList": {
    "format": "links",
    "label": "local",
    "separator": " · "
  },
  "hreflang": {
    "siteUrl": "https://example.com",
    "xDefault": "en",
    "stripIndexHtml": true
  }
}

डिफ़ॉल्ट टिप्पणियाँ तब भी काम करती हैं जब docsOutput.html को छोड़ दिया जाता है। languageList.start / end या hreflang.start / end केवल तभी सेट करें जब स्रोत भिन्न मार्कर टेक्स्ट का उपयोग करता हो।

दृश्यमान भाषा नेविगेशन

• format: "links" <a> तत्व लिखता है। <ul>, <ol>, या <nav> के अंदर, प्रत्येक लिंक <li> में लपेटा जाता है; अन्यत्र, separator लिंक को जोड़ता है।
• format: "select" <option> पंक्तियाँ लिखता है। मार्करों को अपने स्वयं के <select data-lang-select> के अंदर रखें, node_modules/ai-i18n-tools/dist/html-runtime/lang-select.js को साइट में कॉपी करें, और उस क्लासिक स्क्रिप्ट को लोड करें। यह चयनित विकल्प के जनरेट किए गए URL पर नेविगेट करता है।
• label local (एंडोनिम), english, या both (English / endonym जब वे भिन्न हों) है। लेबल ui-languages.json से आते हैं जब उपलब्ध हों, फिर पैकेज की बंडल की गई लोकेल सूची से।

एक मार्कर ब्लॉक एक प्रारूप का उपयोग करता है। जनरेट किए गए लिंक में lang, hreflang, और aria-current शामिल होते हैं; वर्तमान पृष्ठ के लिए जनरेट किए गए विकल्प में selected होता है।

खोज इंजन विकल्प

hreflang.siteUrl वैकल्पिक URL को उपसर्ग करता है। डिप्लॉयमेंट से पहले इसे साइट के पब्लिक ओरिजिन पर सेट करें। जब इसे छोड़ दिया जाता है, तो पाइपलाइन सापेक्ष वैकल्पिक लिंक लिखती है और एक चेतावनी लॉग करती है।

xDefault डिफ़ॉल्ट रूप से sourceLocale होता है; यह केवल तभी उत्सर्जित होता है जब वह लोकेल पृष्ठ के लिए कॉन्फ़िगर किया गया हो। stripIndexHtml: true एक index.html वैकल्पिक को डायरेक्टरी URL में बदल देता है।

मार्कर ब्लॉक आवश्यक है: पाइपलाइन <head> में टैग को स्वचालित रूप से इंजेक्ट नहीं करती है। यह साइटमैप, कैनोनिकल URL, या og:locale भी जनरेट नहीं करती है, और यह ब्राउज़र भाषा द्वारा रीडायरेक्ट नहीं करती है।

केवल कॉन्फ़िगर किए गए स्रोत और लक्ष्य लोकेल भाषा ब्लॉकों के लिए पात्र हैं। जब ui-languages.json मौजूद होता है, तो इसकी पंक्तियाँ और क्रम यह निर्धारित करते हैं कि कौन से पात्र लोकेल दिखाई देते हैं, इसलिए मैनिफेस्ट को कॉन्फ़िग के साथ संरेखित रखें। यदि आप केवल एक उपसमुच्चय जनरेट करने के लिए --locale के साथ अनुवाद करते हैं, तो जब तक प्रत्येक लिंक किया गया लोकेल आउटपुट मौजूद न हो, तब तक प्रकाशित न करें।

दूसरा रन

वाक्य अनुवाद कैश में रहते हैं। फ़ाइल-ट्रैकिंग हैश में लोकेल सूची, आउटपुट शैली, docsOutput.html, और localizedAssets भी शामिल होते हैं। किसी लोकेल को जोड़ने या उन विकल्पों को बदलने से जनरेट किए गए ब्लॉक और लिंक पुनः लिखे जाते हैं, भले ही प्रत्येक वाक्य पहले से कैश किया गया हो। एक मेल खाता हैश और एक अद्यतित आउटपुट फ़ाइल उस लोकेल पृष्ठ को छोड़ देती है।

समस्या निवारण

लक्षण	क्या जाँचें
आउटपुट site/pt-BR/site/index.html है	docsOutput.docsRoot को "site" पर सेट करें ताकि स्रोत उपसर्ग छिन जाए।
लिंक अभी भी अंग्रेज़ी पृष्ठ की ओर इंगित करता है	एक सापेक्ष .html / .htm लिंक का उपयोग करें, और लक्ष्य पृष्ठ को उसी docs[] ब्लॉक में शामिल करें।
लोकेल पृष्ठ से छवि पथ टूटा हुआ है	इसे सापेक्ष रखें ताकि गहराई पुनर्लेखन लागू हो सके; याद रखें कि CSS url() पुनः नहीं लिखा जाता है।
स्थानीयकृत छवि चयनित नहीं है	localizedAssets.include, फ़ाइल नाम pattern, और यह जाँचें कि क्या उम्मीदवार मौजूद है जब onlyIfExists सत्य हो।
भाषा सूची खाली या अपरिवर्तित है	दोनों मार्कर टिप्पणियों को सही क्रम में और script, style, pre, और code के बाहर रखें।
ड्रॉपडाउन नेविगेट नहीं करता	data-lang-select को <select> में जोड़ें और html-runtime/lang-select.js लोड करें।
Hreflang URL गलत होस्ट का उपयोग करते हैं	hreflang.siteUrl को अंतिम सार्वजनिक ओरिजिन पर सेट करें।
अनुवादित पृष्ठ का पुनः अनुवाद होता है	जनरेट की गई लोकेल फ़ाइलों को कॉन्फ़िगर किए गए outputDir के अंतर्गत रखें; उन्हें अलग स्रोतों के रूप में न जोड़ें।