نیویگیشن: تیار کردہ فائلیں کیسے کام کرتی ہیں

ہر لوکیل کے لیے چار نیویگیشن اجزا اس لوکیل کے موضوعات سے تیار ہوتے ہیں، ہاتھ سے نہیں لکھے جاتے (نیز README.md، جو حوالہ جاتی لوکیل en-gb-oxendict کے لیے ایک بار تیار ہوتا ہے):

• README.md (ریپوزٹری کے ہوم پیج پر فہرستِ مضامین؛ صرف حوالہ جاتی لوکیل)
• locales/<locale>/index.md (شائع شدہ سائٹ کا ہوم پیج)
• locales/<locale>/front-matter/table-of-contents.md
• locales/<locale>/topics/09-07-index.md (موضوعات کا اشاریہ، لنکس کے ساتھ)

یہ سب tools/gen_nav.py بناتا ہے۔ انہیں ہاتھ سے ایڈٹ نہ کریں، کیونکہ اگلی تیاری آپ کی تبدیلیوں کو مٹا دے گی۔

دوبارہ کب تیار کریں

جب بھی آپ:

• موضوع شامل کریں، ہٹائیں، نام بدلیں، یا دوبارہ نمبر دیں، یا
• کسی موضوع کا # N.M Title عنوان بدلیں (فہرستِ مضامین اسے استعمال کرتی ہے)

تو just nav (یا python3 tools/gen_nav.py) چلائیں۔

اگر آپ نے locales/en-gb-oxendict/ کے تحت کچھ بدلا ہے تو پہلے python3 tools/localize.py چلائیں تاکہ باقی تین لوکیلز کے موضوعات (اور ان کے بنائے عنوانات) اپ ٹو ڈیٹ ہوں اس سے پہلے کہ gen_nav.py انہیں پڑھے؛ دیکھیں spec/locales.md۔

یہ کیسے کام کرتا ہے

ہر لوکیل کے لیے gen_nav.py ہر locales/<locale>/topics/*.md فائل پڑھتا ہے، اعشاری نمبر کے مطابق ترتیب دیتا ہے، حصے کے لحاظ سے گروہ بند کرتا ہے، اور:

• ہر موضوع کے H1 عنوان سے حصہ بہ حصہ فہرستِ مضامین بناتا ہے،
• اسے locales/<locale>/index.md اور locales/<locale>/front-matter/table-of-contents.md میں لکھتا ہے (اور، صرف حوالہ جاتی لوکیل کے لیے، README.md میں)،
• بنیادی موضوعات (حصے 1 تا 8) کو کلیدی اصطلاحات کی مقررہ فہرست کے لیے اسکین کرتا ہے اور موضوعات کا اشاریہ locales/<locale>/topics/09-07-index.md میں لکھتا ہے۔

مشترکہ بنیادی متن (تعارفی پیراگراف، “اس کتاب کو کیسے پڑھیں”، “ہمہ گیر موضوعات”، اور حصوں کے عنوانات) اسی طرح مقامی بنایا جاتا ہے جیسے موضوعات کی نثر، tools/localize.py کے لوکیل فنکشنز کے ذریعے، تاکہ تیار کردہ صفحات ہر لوکیل میں فطری طور پر پڑھے جائیں۔

حصوں کے عنوانات اسکرپٹ کے اوپر کے قریب PART_TITLES ڈکشنری میں ہیں۔ جنریٹر کولن والے انداز کے حصوں کے عنوانات استعمال کرتا ہے (“Part 2: Delivery and Flow Metrics”)، کبھی طویل ڈیش نہیں۔

ہاتھ سے ترجمہ شدہ لوکیلز کے لیے ہوم پیج اور فہرستِ مضامین کا صفحہ ہاتھ سے لکھے جاتے ہیں (ترجمہ شدہ عنوانات اور ہر حصے کی N.0 تعارفی سطر)، اور tools/gen_translated_nav.py اس لوکیل کے موضوعات کے H1 عنوانات سے موضوعات کی فہرست تازہ کرتا ہے۔

یہ کس چیز کو نہیں چھوتا

ریپوزٹری کی جڑ میں تفصیل (spec/index.md، spec/structure.md، اور ان کے ساتھی) ہاتھ سے لکھا سچائی کا ماخذ ہے۔ جنریٹر اسے نہیں لکھتا، اور وہ شائع شدہ سائٹ کا حصہ نہیں۔ اگر آپ ڈھانچہ بدلیں تو spec/structure.md خود اپ ڈیٹ کریں، پھر اخذ شدہ فائلوں کے لیے just nav اور یہ تصدیق کرنے کے لیے just test چلائیں کہ سب کچھ ہم آہنگ ہے۔