diff --git a/translations/fa/.co-op-translator.json b/translations/fa/.co-op-translator.json index c5606bd54..b72cd5c40 100644 --- a/translations/fa/.co-op-translator.json +++ b/translations/fa/.co-op-translator.json @@ -493,7 +493,7 @@ }, "AGENTS.md": { "original_hash": "a362efd06d64d4134a0cfe8515a86d34", - "translation_date": "2026-04-06T18:58:08+00:00", + "translation_date": "2026-04-20T15:59:07+00:00", "source_file": "AGENTS.md", "language_code": "fa" }, diff --git a/translations/fa/AGENTS.md b/translations/fa/AGENTS.md index eb39bb509..46afcec8d 100644 --- a/translations/fa/AGENTS.md +++ b/translations/fa/AGENTS.md @@ -2,36 +2,36 @@ ## مروری بر پروژه -این مخزن یک برنامه درسی آموزشی برای آموزش اصول توسعه وب به مبتدیان است. این برنامه درسی یک دوره جامع ۱۲ هفته‌ای است که توسط مدافعان مایکروسافت کلود توسعه یافته و شامل ۲۴ درس عملی است که مباحث JavaScript، CSS و HTML را پوشش می‌دهد. +این مخزن یک برنامه آموزشی برای آموزش مفاهیم پایه توسعه وب به مبتدیان است. این برنامه آموزشی یک دوره جامع ۱۲ هفته‌ای است که توسط مدافعان ابری مایکروسافت توسعه یافته و شامل ۲۴ درس عملی در زمینه JavaScript، CSS و HTML می‌باشد. ### اجزای کلیدی -- **محتوای آموزشی**: ۲۴ درس ساختاریافته سازمان‌یافته در قالب ماژول‌های مبتنی بر پروژه -- **پروژه‌های عملی**: تراریوم، بازی تایپ، افزونه مرورگر، بازی فضایی، اپلیکیشن بانکی، ویرایشگر کد و دستیار چت هوش مصنوعی -- **آزمون‌های تعاملی**: ۴۸ آزمون با ۳ سوال هر کدام (ارزیابی پیش و پس از درس) -- **پشتیبانی چندزبانه**: ترجمه‌های خودکار برای بیش از ۵۰ زبان با استفاده از GitHub Actions -- **فناوری‌ها**: HTML، CSS، JavaScript، Vue.js 3، Vite، Node.js، Express، Python (برای پروژه‌های AI) +- **محتوای آموزشی**: ۲۴ درس ساختاربندی شده در ماژول‌های مبتنی بر پروژه +- **پروژه‌های عملی**: تریاریوم، بازی تایپینگ، افزونه مرورگر، بازی فضا، اپلیکیشن بانکی، ویرایشگر کد و دستیار چت AI +- **آزمون‌های تعاملی**: ۴۸ آزمون با ۳ سوال هر کدام (ارزیابی‌های پیش و پس از درس) +- **پشتیبانی چندزبانه**: ترجمه‌های خودکار برای بیش از ۵۰ زبان از طریق GitHub Actions +- **فناوری‌ها**: HTML، CSS، JavaScript، Vue.js 3، Vite، Node.js، Express، پایتون (برای پروژه‌های AI) ### معماری - مخزن آموزشی با ساختار مبتنی بر درس -- هر پوشه درس شامل README، نمونه‌های کد و راه‌حل‌ها +- هر پوشه درس شامل فایل README، نمونه‌های کد و راه‌حل‌ها - پروژه‌های مستقل در دایرکتوری‌های جداگانه (quiz-app، پروژه‌های مختلف دروس) - سیستم ترجمه با استفاده از GitHub Actions (co-op-translator) -- مستندات ارائه شده از طریق Docsify و در دسترس به صورت PDF +- مستندات ارائه شده توسط Docsify و در دسترس به صورت PDF ## دستورات راه‌اندازی -این مخزن عمدتاً برای مرور محتوای آموزشی است. برای کار با پروژه‌های خاص: +این مخزن عمدتاً برای استفاده از محتوای آموزشی است. برای کار با پروژه‌های خاص: -### تنظیم مخزن اصلی +### راه‌اندازی مخزن اصلی ```bash git clone https://github.com/microsoft/Web-Dev-For-Beginners.git cd Web-Dev-For-Beginners ``` -### راه‌اندازی برنامه آزمون (Vue 3 + Vite) +### راه‌اندازی اپلیکیشن آزمون (Vue 3 + Vite) ```bash cd quiz-app @@ -41,14 +41,14 @@ npm run build # ساخت برای تولید npm run lint # اجرای ESLint ``` -### API پروژه بانکی (Node.js + Express) +### API پروژه بانک (Node.js + Express) ```bash cd 7-bank-project/api npm install npm start # شروع سرور API npm run lint # اجرای ESLint -npm run format # فرمت با Prettier +npm run format # قالب‌بندی با Prettier ``` ### پروژه‌های افزونه مرورگر @@ -59,7 +59,7 @@ npm install # دستورالعمل‌های بارگذاری افزونه مخصوص مرورگر را دنبال کنید ``` -### پروژه‌های بازی فضایی +### پروژه‌های بازی فضا ```bash cd 6-space-game/solution @@ -67,51 +67,51 @@ npm install # فایل index.html را در مرورگر باز کنید یا از Live Server استفاده کنید ``` -### پروژه چت (بک‌اند Python) +### پروژه چت (بک‌اند پایتون) ```bash cd 9-chat-project/solution/backend/python pip install openai -# تنظیم متغیر محیطی GITHUB_TOKEN +# متغیر محیطی GITHUB_TOKEN را تنظیم کنید python api.py ``` ## روند توسعه -### برای مشارکت‌کنندگان محتوا +### برای همکاران محتوا -1. **فورک مخزن** به حساب گیت‌هاب خود -2. **کلون فورک** به صورت محلی -3. **ایجاد شاخه جدید** برای تغییرات خود -4. ایجاد تغییرات در محتوای درس یا نمونه‌های کد -5. تست هر تغییر کد در دایرکتوری‌های مربوط به پروژه -6. ارسال درخواست کشش (Pull Request) طبق دستورالعمل‌های مشارکت +1. **مخزن را فورک کنید** به حساب گیت‌هاب خود +2. **فورک خود را کلون کنید** به صورت محلی +3. **یک شاخه جدید بسازید** برای تغییرات خود +4. تغییرات در محتوای درس یا نمونه‌های کد بدهید +5. تغییرات کد را در دایرکتوری‌های مرتبط پروژه آزمایش کنید +6. درخواست‌های پول (Pull Requests) را مطابق با دستورالعمل‌ها ارسال کنید ### برای یادگیرندگان -1. فورک یا کلون مخزن +1. مخزن را فورک یا کلون کنید 2. به ترتیب به دایرکتوری‌های درس بروید -3. فایل‌های README هر درس را مطالعه کنید -4. آزمون‌های پیش از درس را در https://ff-quizzes.netlify.app/web/ تکمیل کنید -5. نمونه‌های کد در پوشه‌های درس را انجام دهید -6. وظایف و چالش‌ها را کامل کنید -7. آزمون‌های بعد از درس را انجام دهید +3. فایل README هر درس را بخوانید +4. آزمون‌های پیش‌درس را در https://ff-quizzes.netlify.app/web/ کامل کنید +5. نمونه‌های کد در پوشه‌های درس را اجرا کنید +6. تمرینات و چالش‌ها را انجام دهید +7. آزمون‌های پس‌درس را بگیرید ### توسعه زنده -- **مستندات**: اجرای `docsify serve` در شاخه ریشه (پورت ۳۰۰۰) -- **برنامه آزمون**: اجرای `npm run dev` در دایرکتوری quiz-app -- **پروژه‌ها**: استفاده از افزونه Live Server در VS Code برای پروژه‌های HTML -- **پروژه‌های API**: اجرای `npm start` در دایرکتوری‌های مربوطه +- **مستندات**: دستور `docsify serve` را در ریشه اجرا کنید (پورت ۳۰۰۰) +- **اپلیکیشن آزمون**: دستور `npm run dev` را در دایرکتوری quiz-app اجرا کنید +- **پروژه‌ها**: از افزونه VS Code Live Server برای پروژه‌های HTML استفاده کنید +- **پروژه‌های API**: دستور `npm start` را در دایرکتوری‌های مربوط به API اجرا کنید ## دستورالعمل‌های تست -### تست برنامه آزمون +### تست اپلیکیشن آزمون ```bash cd quiz-app npm run lint # بررسی مشکلات سبک کد -npm run build # تایید موفقیت ساخت +npm run build # تأیید موفقیت‌آمیز بودن ساخت ``` ### تست API بانک @@ -119,164 +119,164 @@ npm run build # تایید موفقیت ساخت ```bash cd 7-bank-project/api npm run lint # بررسی مشکلات سبک کد -node server.js # تأیید راه‌اندازی سرور بدون خطاها +node server.js # بررسی راه‌اندازی بدون خطا سرور ``` ### رویکرد کلی تست -- این یک مخزن آموزشی است که فاقد تست‌های خودکار جامع است -- تست دستی متمرکز بر: +- این یک مخزن آموزشی است و تست‌های خودکار جامع ندارد +- تست دستی بر مراحل زیر تمرکز دارد: - اجرای بدون خطا نمونه‌های کد - - درستی لینک‌ها در مستندات - - تکمیل موفقیت‌آمیز فرآیند ساخت پروژه - - رعایت بهترین شیوه‌ها در نمونه‌ها + - لینک‌های مستندات به درستی کار می‌کنند + - ساخت پروژه‌ها موفقیت‌آمیز است + - مثال‌ها مطابق بهترین شیوه‌ها هستند ### بررسی‌های پیش از ارسال -- اجرای `npm run lint` در دایرکتوری‌های دارای package.json +- اجرای `npm run lint` در دایرکتوری‌هایی که package.json دارند - اعتبارسنجی لینک‌های مارک‌داون -- اجرای نمونه‌های کد در مرورگر یا Node.js -- بررسی حفظ ساختار صحیح ترجمه‌ها +- تست نمونه‌های کد در مرورگر یا Node.js +- اطمینان از حفظ ساختار صحیح ترجمه‌ها -## دستورالعمل‌های سبک کدنویسی +## راهنمای سبک کد -### JavaScript +### جاوااسکریپت - استفاده از سینتکس مدرن ES6+ -- پیروی از تنظیمات ESLint استاندارد در پروژه‌ها -- استفاده از نام‌های متغیر و توابع معنادار برای وضوح آموزشی -- افزودن توضیحات برای مفاهیم یادگیرندگان -- فرمت کردن با Prettier در صورت وجود تنظیمات +- پیروی از پیکربندی ESLint استاندارد پروژه‌ها +- استفاده از نام‌های متغیر و توابع معنی‌دار برای درک بهتر آموزشی +- افزودن کامنت برای توضیح مفاهیم +- فرمت کردن کد با Prettier در صورت تنظیم شدن ### HTML/CSS - استفاده از عناصر معنایی HTML5 -- رعایت اصول طراحی واکنش‌گرا -- نام‌گذاری واضح کلاس‌ها -- افزودن توضیحات برای تکنیک‌های CSS جهت یادگیرندگان +- اصول طراحی واکنشگرا +- نام‌گذاری واضح برای کلاس‌ها +- کامنت‌های آموزشی در مورد تکنیک‌های CSS برای یادگیرندگان -### Python +### پایتون -- پیروی از دستورالعمل‌های سبک PEP 8 -- نمونه‌های کد روشن و آموزشی -- استفاده از نوع‌دهی (type hints) در صورت مناسب بودن برای یادگیری +- پیروی از دستورالعمل‌های سبک PEP ۸ +- مثال‌های کد آموزشی و خوانا +- استفاده از تایپ هینت‌ها در صورت مفید بودن برای آموزش -### مستندسازی Markdown +### مستندسازی مارک‌داون -- سلسله مراتب واضح سرفصل‌ها -- بلوک‌های کد با مشخص کردن زبان -- لینک به منابع اضافی -- اسکرین‌شات‌ها و تصاویر در پوشه‌های `images/` -- متن جایگزین برای تصاویر جهت دسترسی +- ساختار واضح عنوان‌ها +- بلاک‌های کد با مشخص کردن زبان +- لینک به منابع اضافه +- اسکرین‌شات‌ها و تصاویر در دایرکتوری‌های `images/` +- متن جایگزین برای تصاویر جهت دسترسی‌پذیری ### سازماندهی فایل‌ها -- شماره‌گذاری دروس به ترتیب (1-getting-started-lessons, 2-js-basics و غیره) -- هر پروژه دارای دایرکتوری‌های `solution/` و اغلب `start/` یا `your-work/` -- ذخیره تصاویر در پوشه‌های `images/` مربوط به هر درس +- دروس به صورت مرتب شماره‌گذاری شده (۱-getting-started-lessons، ۲-js-basics و غیره) +- هر پروژه دارای دایرکتوری `solution/` و معمولاً `start/` یا `your-work/` +- تصاویر هر درس در پوشه‌های مخصوص همان درس در `images/` - ترجمه‌ها در ساختار `translations/{language-code}/` ## ساخت و استقرار -### استقرار برنامه آزمون (Azure Static Web Apps) +### استقرار اپلیکیشن آزمون (Azure Static Web Apps) -برنامه آزمون برای استقرار در Azure Static Web Apps پیکربندی شده است: +اپلیکیشن آزمون برای استقرار در Azure Static Web Apps پیکربندی شده است: ```bash cd quiz-app -npm run build # پوشه dist/ را ایجاد می‌کند -# از طریق جریان کاری GitHub Actions در هر بار پوش به شاخه main مستقر می‌کند +npm run build # ایجاد پوشه dist/ +# استقرار از طریق جریان کاری GitHub Actions در هنگام push به main ``` پیکربندی Azure Static Web Apps: -- **مکان برنامه**: `/quiz-app` -- **مکان خروجی**: `dist` +- **مکان اپلیکیشن**: `/quiz-app` +- **مکان تولید خروجی**: `dist` - **روند کاری**: `.github/workflows/azure-static-web-apps-ashy-river-0debb7803.yml` ### تولید PDF مستندات ```bash npm install # نصب docsify-to-pdf -npm run convert # تولید فایل PDF از داکس +npm run convert # ایجاد PDF از داکس ``` ### مستندات Docsify ```bash npm install -g docsify-cli # نصب Docsify به صورت سراسری -docsify serve # خدمت رسانی در localhost:3000 +docsify serve # ارائه در localhost:3000 ``` -### ساخت‌های خاص پروژه +### ساخت‌های اختصاصی پروژه -هر پوشه پروژه ممکن است فرآیند ساخت مختص به خود را داشته باشد: -- پروژه‌های Vue: اجرای `npm run build` برای ایجاد بسته‌های تولید -- پروژه‌های استاتیک: مرحله ساخت ندارد، سرویس‌دهی مستقیم فایل‌ها +هر دایرکتوری پروژه ممکن است فرایند ساخت خاص خود را داشته باشد: +- پروژه‌های Vue: اجرای `npm run build` بسته‌های تولید را ایجاد می‌کند +- پروژه‌های استاتیک: هیچ قدم ساختی ندارند، مستقیماً فایل‌ها سرو می‌شوند -## دستورالعمل‌های ارسال Pull Request +## راهنمای درخواست‌های پول (PR) -### قالب عنوان +### فرمت عنوان -از عناوین واضح و توصیفی استفاده کنید که حوزه تغییرات را نشان دهد: +از عناوین واضح و توصیفی استفاده کنید که بخش تغییر را نمایش دهد: - `[Quiz-app] افزودن آزمون جدید برای درس X` -- `[Lesson-3] اصلاح اشتباه تایپی در پروژه تراریوم` +- `[Lesson-3] رفع غلط املایی در پروژه تریاریوم` - `[Translation] افزودن ترجمه اسپانیایی برای درس ۵` - `[Docs] به‌روزرسانی دستورالعمل‌های راه‌اندازی` -### بررسی‌های مورد نیاز +### چک‌های مورد نیاز قبل از ارسال PR: 1. **کیفیت کد**: - - اجرای `npm run lint` در دایرکتوری‌های پروژه مربوط - - رفع همه خطاها و هشدارهای lint + - اجرای `npm run lint` در دایرکتوری‌های پروژه مرتبط + - رفع تمام خطاها و هشدارهای lint -2. **تایید ساخت**: - - اجرای `npm run build` در صورت لزوم - - اطمینان از عدم وجود خطای ساخت +2. **تأیید ساخت**: + - اجرای `npm run build` در صورت نیاز + - اطمینان از عدم وجود خطا در ساخت -3. **اعتبارسنجی لینک‌ها**: - - تست همه لینک‌های مارک‌داون - - بررسی صحت ارجاعات تصویر +3. **اعتبارسنجی لینک**: + - تست تمام لینک‌های مارک‌داون + - بررسی صحت ارجاعات به تصاویر 4. **بازبینی محتوا**: - - ویرایش املایی و گرامری - - اطمینان از صحت و آموزشی بودن نمونه‌های کد - - بررسی حفظ معنای اصلی ترجمه‌ها + - بازخوانی برای املاء و دستور زبان + - اطمینان از صحیح و آموزشی بودن نمونه‌های کد + - تأیید صحت مفهوم ترجمه‌ها ### الزامات مشارکت -- موافقت با CLA مایکروسافت (بررسی خودکار در اولین PR) +- پذیرش CLA مایکروسافت (چک خودکار در اولین PR) - پیروی از [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/) - مشاهده [CONTRIBUTING.md](./CONTRIBUTING.md) برای دستورالعمل‌های دقیق -- ارجاع شماره مسائل در توضیح PR در صورت لزوم +- ارجاع شماره مسائل در توضیحات PR در صورت کاربرد -### فرایند بازبینی +### روند بازبینی -- PRها توسط نگهدارندگان و جامعه مرور می‌شوند -- وضوح آموزشی در اولویت است -- نمونه‌های کد باید از بهترین شیوه‌های فعلی پیروی کنند -- ترجمه‌ها از نظر دقت و سازگاری فرهنگی بررسی می‌شوند +- PRها توسط نگهدارندگان و جامعه بررسی می‌شوند +- شفافیت آموزشی در اولویت است +- نمونه‌های کد باید بهترین روش‌های فعلی را دنبال کنند +- ترجمه‌ها برای دقت و سازگاری فرهنگی بررسی می‌شوند ## سیستم ترجمه ### ترجمه خودکار -- استفاده از GitHub Actions با گردش کار co-op-translator +- استفاده از GitHub Actions با روند کاری co-op-translator - ترجمه خودکار به بیش از ۵۰ زبان - فایل‌های منبع در دایرکتوری‌های اصلی - فایل‌های ترجمه شده در ساختار `translations/{language-code}/` -### افزودن بهبودهای دستی ترجمه +### افزودن بهبودهای ترجمه دستی -1. پیدا کردن فایل در `translations/{language-code}/` -2. انجام بهبودها بدون تغییر ساختار -3. اطمینان از عملکرد نمونه‌های کد -4. تست محتوای آزمون‌های بومی شده +1. فایل را در `translations/{language-code}/` پیدا کنید +2. بهبودها را در حالی که ساختار حفظ شود، اعمال کنید +3. اطمینان حاصل کنید نمونه‌های کد عملکردی باقی بمانند +4. آزمون محتوای آزمون محلی‌شده در صورت وجود ### متادیتای ترجمه -فایل‌های ترجمه شامل سربرگ متادیتا هستند: +فایل‌های ترجمه‌شده شامل سربرگ متادیتا هستند: ```markdown ``` -## عیب‌یابی و رفع اشکال +## اشکال‌زدایی و رفع مشکلات -### مشکلات رایج +### مسائل رایج -**عدم شروع برنامه آزمون**: -- بررسی نسخه Node.js (توصیه شده v14+) -- حذف پوشه‌های `node_modules` و فایل `package-lock.json`، سپس اجرای مجدد `npm install` -- بررسی تعارض پورت (پیش‌فرض: پورت 5173 توسط Vite استفاده می‌شود) +**اپلیکیشن آزمون اجرا نمی‌شود**: +- نسخه Node.js را بررسی کنید (v14+ توصیه شده) +- پوشه `node_modules` و فایل `package-lock.json` را حذف کرده و دوباره `npm install` بزنید +- بررسی تداخل پورت‌ها (پیش‌فرض: Vite از پورت 5173 استفاده می‌کند) -**سرور API راه‌اندازی نمی‌شود**: -- بررسی نسخه Node.js (حداقل node >=10) -- اطمینان از عدم استفاده پورت توسط برنامه دیگر +**سرور API اجرا نمی‌شود**: +- نسخه Node.js را بررسی کنید (node >=10) +- اطمینان از آزاد بودن پورت - اطمینان از نصب تمام وابستگی‌ها با `npm install` -**بارگذاری نشدن افزونه مرورگر**: -- بررسی قالب صحیح manifest.json -- مشاهده خطاها در کنسول مرورگر -- پیروی از دستورالعمل‌های نصب افزونه خاص مرورگر +**افزونه مرورگر بارگذاری نمی‌شود**: +- بررسی فرمت صحیح manifest.json +- نگاه به کنسول مرورگر برای خطاها +- پیروی از دستورالعمل نصب افزونه مرورگر خاص -**مشکلات پروژه چت Python**: -- اطمینان از نصب بسته OpenAI: `pip install openai` -- تنظیم متغیر محیطی GITHUB_TOKEN -- بررسی دسترسی به مدل‌های GitHub +**مشکلات پروژه چت پایتون**: +- اطمینان از نصب پکیج OpenAI: `pip install openai` +- بررسی تنظیم متغیر محیطی GITHUB_TOKEN +- بررسی مجوزهای دسترسی GitHub Models -**عدم سرویس‌دهی مستندات Docsify**: -- نصب جهانی docsify-cli: `npm install -g docsify-cli` -- اجرا از شاخه ریشه مخزن +**Docsify مستندات را سرو نمی‌کند**: +- نصب docsify-cli به صورت سراسری: `npm install -g docsify-cli` +- اجرای دستور از ریشه مخزن - اطمینان از وجود فایل `docs/_sidebar.md` ### نکات محیط توسعه - استفاده از VS Code با افزونه Live Server برای پروژه‌های HTML -- نصب افزونه‌های ESLint و Prettier برای فرمت یکنواخت -- استفاده از DevTools مرورگر برای اشکال‌زدایی JavaScript -- نصب افزونه Vue DevTools برای پروژه‌های Vue +- نصب افزونه‌های ESLint و Prettier برای قالب‌بندی یکنواخت +- استفاده از DevTools مرورگر برای اشکال‌زدایی جاوااسکریپت +- برای پروژه‌های Vue، نصب افزونه Vue DevTools در مرورگر ### ملاحظات عملکرد -- تعداد زیاد فایل‌های ترجمه شده (بیش از ۵۰ زبان) باعث بزرگ بودن کلون کامل می‌شود -- برای کار فقط روی محتوا از کلون کم‌عمق استفاده کنید: `git clone --depth 1` -- هنگام کار بر روی محتوای انگلیسی، از جستجو در ترجمه‌ها خودداری کنید -- فرآیندهای ساخت ممکن است در اولین اجرا کند باشد (نصب npm، ساخت Vite) +- تعداد زیاد فایل‌های ترجمه شده (بیش از ۵۰ زبان) به معنی کلون‌های حجیم است +- استفاده از کلون کم‌عمق در صورت کار صرفاً روی محتوا: `git clone --depth 1` +- هنگام کار روی محتوای انگلیسی، ترجمه‌ها را از جستجوها مستثنی کنید +- فرایندهای ساخت ممکن است در اجرای اول کند باشند (npm install، ساخت Vite) ## ملاحظات امنیتی ### متغیرهای محیطی - کلیدهای API هرگز نباید در مخزن کامیت شوند -- استفاده از فایل‌های `.env` (که در `.gitignore` هستند) -- مستندسازی متغیرهای محیطی مورد نیاز در README پروژه‌ها +- استفاده از فایل‌های `.env` (که در `.gitignore` موجود است) +- متغیرهای محیطی مورد نیاز را در README پروژه‌ها مستند کنید -### پروژه‌های Python +### پروژه‌های پایتون -- استفاده از محیط مجازی: `python -m venv venv` -- به‌روز نگه داشتن وابستگی‌ها -- توکن‌های GitHub باید حداقل دسترسی لازم را داشته باشند +- استفاده از محیط‌های مجازی: `python -m venv venv` +- به‌روزرسانی مرتب وابستگی‌ها +- توکن‌های GitHub باید حداقل مجوزهای لازم را داشته باشند -### دسترسی به مدل‌های GitHub +### دسترسی GitHub Models -- توکن‌های دسترسی شخصی (PAT) برای GitHub Models لازم است -- توکن‌ها باید به عنوان متغیر محیطی ذخیره شوند -- هرگز توکن یا اطلاعات ورود را کامیت نکنید +- توکن‌های دسترسی شخصی (PAT) برای GitHub Models مورد نیاز است +- توکن‌ها باید به صورت متغیرهای محیطی ذخیره شوند +- هرگز توکن یا اعتبارنامه‌ها را کامیت نکنید ## یادداشت‌های اضافی -### مخاطبان هدف +### مخاطب هدف - مبتدیان کامل در توسعه وب - دانشجویان و خودآموزها -- معلمانی که برنامه درسی را در کلاس درس استفاده می‌کنند -- محتوای طراحی شده برای دسترس‌پذیری و پیشرفت تدریجی مهارت‌ها +- معلمانی که این برنامه را در کلاس درس استفاده می‌کنند +- محتوا برای دسترسی‌پذیری و پیشرفت تدریجی مهارت طراحی شده است ### فلسفه آموزشی - رویکرد یادگیری مبتنی بر پروژه - بررسی‌های مکرر دانش (آزمون‌ها) -- تمرین‌های کدنویسی عملی -- مثال‌هایی از کاربردهای واقعی -- تمرکز بر اصول پایه قبل از فریم‌ورک‌ها +- تمرینات کدنویسی عملی +- مثال‌های کاربردی دنیای واقعی +- تمرکز بر اصول قبل از فریم‌ورک‌ها ### نگهداری مخزن -- وجود جامعه فعال از یادگیرندگان و مشارکت‌کنندگان -- به‌روزرسانی‌های منظم وابستگی‌ها و محتوا -- بررسی مسائل و بحث‌ها توسط نگهدارندگان -- به‌روزرسانی‌های ترجمه به‌صورت خودکار از طریق GitHub Actions +- جامعه فعالی از یادگیرندگان و همکاران +- به‌روزرسانی‌های مکرر وابستگی‌ها و محتوا +- نظارت بر مسائل و بحث‌ها توسط نگهدارندگان +- به‌روزرسانی ترجمه‌ها به صورت خودکار توسط GitHub Actions ### منابع مرتبط - [ماژول‌های Microsoft Learn](https://docs.microsoft.com/learn/) -- [منابع Student Hub](https://docs.microsoft.com/learn/student-hub/) -- [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) پیشنهادی برای یادگیرندگان -- دوره‌های اضافی: AI مولد، علم داده، یادگیری ماشین، برنامه‌های IoT موجود +- [منابع دانشجویان Student Hub](https://docs.microsoft.com/learn/student-hub/) +- [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) پیشنهاد شده برای یادگیرندگان +- دوره‌های اضافی: AI مولد، علوم داده، یادگیری ماشین، دوره‌های IoT موجود است ### کار با پروژه‌های خاص -برای دستورالعمل‌های دقیق پروژه‌های جداگانه به فایل‌های README در: -- `quiz-app/README.md` - برنامه آزمون Vue 3 -- `7-bank-project/README.md` - اپلیکیشن بانکی با احراز هویت +برای دستورالعمل‌های دقیق پروژه‌های جداگانه، به فایل‌های README در: +- `quiz-app/README.md` - اپلیکیشن آزمون Vue 3 +- `7-bank-project/README.md` - اپ بانکی با احراز هویت - `5-browser-extension/README.md` - توسعه افزونه مرورگر -- `6-space-game/README.md` - توسعه بازی مبتنی بر کانواس -- `9-chat-project/README.md` - پروژه دستیار چت هوش مصنوعی +- `6-space-game/README.md` - توسعه بازی مبتنی بر Canvas +- `9-chat-project/README.md` - پروژه دستیار چت AI -### ساختار مونو رپو +### ساختار مونو-ریپو -اگرچه یک مونو رپو سنتی نیست، این مخزن شامل چندین پروژه مستقل است: -- هر درس به‌صورت جداگانه +اگرچه این یک مونو-ریپو سنتی نیست، این مخزن شامل چند پروژه مستقل است: +- هر درس به صورت مستقل است - پروژه‌ها وابستگی مشترک ندارند -- کار روی پروژه‌های جداگانه بدون تأثیر بر سایرین -- کلون کل مخزن برای تجربه کامل برنامه درسی +- می‌توانید روی پروژه‌های جداگانه بدون تأثیر بر دیگران کار کنید +- برای تجربه کامل دوره، کل مخزن را کلون کنید --- **سلب مسئولیت**: -این سند با استفاده از سرویس ترجمه هوش مصنوعی [Co-op Translator](https://github.com/Azure/co-op-translator) ترجمه شده است. در حالی که ما برای دقت تلاش می‌کنیم، لطفاً توجه داشته باشید که ترجمه‌های خودکار ممکن است شامل خطاها یا نادرستی‌هایی باشند. سند اصلی به زبان بومی خود باید به عنوان منبع معتبر در نظر گرفته شود. برای اطلاعات حیاتی، ترجمه حرفه‌ای انسانی توصیه می‌شود. ما مسئول هیچ گونه سوء تفاهم یا تفسیر نادرستی که ناشی از استفاده از این ترجمه باشد، نمی‌باشیم. +این سند با استفاده از سرویس ترجمه خودکار [Co-op Translator](https://github.com/Azure/co-op-translator) ترجمه شده است. در حالی که ما برای دقت تلاش می‌کنیم، لطفاً توجه داشته باشید که ترجمه‌های خودکار ممکن است حاوی خطا یا نادقتی باشند. سند اصلی به زبان بومی خود باید به عنوان منبع معتبر در نظر گرفته شود. برای اطلاعات حیاتی، استفاده از ترجمه حرفه‌ای انسانی توصیه می‌شود. ما مسئول هیچ گونه سوءتفاهم یا سفسطه ناشی از استفاده از این ترجمه نیستیم. \ No newline at end of file diff --git a/translations/ur/.co-op-translator.json b/translations/ur/.co-op-translator.json index 292292565..80a117e3d 100644 --- a/translations/ur/.co-op-translator.json +++ b/translations/ur/.co-op-translator.json @@ -493,7 +493,7 @@ }, "AGENTS.md": { "original_hash": "a362efd06d64d4134a0cfe8515a86d34", - "translation_date": "2026-04-06T18:59:16+00:00", + "translation_date": "2026-04-20T16:00:15+00:00", "source_file": "AGENTS.md", "language_code": "ur" }, diff --git a/translations/ur/AGENTS.md b/translations/ur/AGENTS.md index 5676dc97d..ea3c64107 100644 --- a/translations/ur/AGENTS.md +++ b/translations/ur/AGENTS.md @@ -1,28 +1,28 @@ # AGENTS.md -## منصوبے کا جائزہ +## پروجیکٹ کا جائزہ -یہ ویب ڈویلپمنٹ کی بنیادی باتیں سکھانے کے لیے ابتدائیوں کے لیے ایک تعلیمی نصاب کا ذخیرہ ہے۔ نصاب ایک جامع ۱۲ ہفتوں کا کورس ہے جو Microsoft Cloud Advocates نے تیار کیا ہے، جس میں جاوا اسکرپٹ، CSS، اور HTML پر مشتمل ۲۴ عملی اسباق شامل ہیں۔ +یہ ویب ڈیولپمنٹ کے بنیادی اصولوں کی تعلیم کے لیے ایک تعلیمی نصاب کا ذخیرہ ہے جو مبتدیوں کے لیے ہے۔ یہ نصاب مائیکروسافٹ کلاؤڈ ایڈووکیٹس کے ذریعہ تیار کردہ ایک جامع 12 ہفتوں کا کورس ہے، جس میں 24 عملی اسباق شامل ہیں جو جاوا اسکرپٹ، CSS، اور HTML کا احاطہ کرتے ہیں۔ ### کلیدی اجزاء -- **تعلیمی مواد**: ۲۴ منظم اسباق جو پروجیکٹ پر مبنی ماڈیولز میں ترتیب دیے گئے ہیں -- **عملی پروجیکٹس**: ٹیریریم، ٹائپنگ گیم، براؤزر ایکسٹینشن، اسپیس گیم، بنکنگ ایپ، کوڈ ایڈیٹر، اور AI چیٹ اسسٹنٹ -- **انٹرایکٹو کوئزز**: ۴۸ کوئزز، ہر ایک میں ۳ سوالات (سبق کے پہلے اور بعد میں تشخیص) -- **کثیرالزبان معاونت**: GitHub Actions کے ذریعہ 50+ زبانوں میں خودکار ترجمے -- **ٹیکنالوجیز**: HTML، CSS، جاوا اسکرپٹ، Vue.js 3، Vite، Node.js، Express، Python (AI پروجیکٹس کے لیے) +- **تعلیمی مواد**: 24 منظم اسباق جو پروجیکٹ پر مبنی ماڈیولز میں ترتیب دیے گئے ہیں +- **عملی پروجیکٹس**: ٹیریریم، ٹائپنگ گیم، براؤزر ایکسٹینشن، اسپیس گیم، بینکنگ ایپ، کوڈ ایڈیٹر، اور AI چیٹ اسسٹنٹ +- **انٹرایکٹو کوئزز**: 48 کوئزز، ہر ایک میں 3 سوالات (سبق سے پہلے/بعد کے جائزے) +- **کثیر لسانی معاونت**: GitHub Actions کے ذریعے 50+ زبانوں کے لیے خودکار تراجم +- **تکنالوجیز**: HTML، CSS، JavaScript، Vue.js 3، Vite، Node.js، Express، Python (AI پروجیکٹس کے لیے) -### آرکیٹیکچر +### فن تعمیر -- سبق پر مبنی ڈھانچہ کے ساتھ تعلیمی ذخیرہ -- ہر سبق کے فولڈر میں README، کوڈ مثالیں، اور حل شامل ہیں -- الگ الگ ڈائریکٹریز میں اسٹینڈ الون پروجیکٹس (quiz-app، مختلف سبق کے پروجیکٹس) -- GitHub Actions استعمال کرتے ہوئے ترجمہ جات کا نظام (co-op-translator) -- Docsify کے ذریعے دستاویزات فراہم کی جاتی ہیں اور PDF کے طور پر دستیاب ہیں +- سبق کی بنیاد پر تعلیمی ذخیرہ +- ہر سبق فولڈر میں README، کوڈ کے نمونے اور حل شامل ہیں +- علیحدہ ڈائریکٹریز میں آزاد پروجیکٹس (quiz-app، مختلف سبق کے پروجیکٹس) +- ترجمہ کا نظام GitHub Actions (co-op-translator) استعمال کرتا ہے +- دستاویزات Docsify کے ذریعے فراہم کی جاتی ہیں اور PDF کے طور پر دستیاب ہیں ## سیٹ اپ کمانڈز -یہ ذخیرہ بنیادی طور پر تعلیمی مواد کے استعمال کے لیے ہے۔ مخصوص پروجیکٹس کے ساتھ کام کرنے کے لیے: +یہ ذخیرہ بنیادی طور پر تعلیمی مواد کے استعمال کے لیے ہے۔ مخصوص پروجیکٹس پر کام کرنے کے لیے: ### مرکزی ذخیرہ سیٹ اپ @@ -36,19 +36,19 @@ cd Web-Dev-For-Beginners ```bash cd quiz-app npm install -npm run dev # ڈویلپمنٹ سرور شروع کریں -npm run build # پیداوار کے لیے بنائیں +npm run dev # ڈیولپمنٹ سرور شروع کریں +npm run build # پروڈکشن کے لیے تیار کریں npm run lint # ESLint چلائیں ``` -### بنک پروجیکٹ API (Node.js + Express) +### بینک پروجیکٹ API (Node.js + Express) ```bash cd 7-bank-project/api npm install -npm start # اے پی آئی سرور شروع کریں -npm run lint # ای ایس لِنٹ چلائیں -npm run format # پریٹیئر کے ساتھ فارمیٹ کریں +npm start # API سرور شروع کریں +npm run lint # ESLint چلائیں +npm run format # Prettier کے ساتھ فارمیٹ کریں ``` ### براؤزر ایکسٹینشن پروجیکٹس @@ -56,7 +56,7 @@ npm run format # پریٹیئر کے ساتھ فارمیٹ کریں ```bash cd 5-browser-extension/solution npm install -# مخصوص براؤزر کی توسیع لوڈ کرنے کی ہدایات پر عمل کریں +# مخصوص براؤزر کے لیے ایکسٹینشن لوڈ کرنے کی ہدایات پر عمل کریں ``` ### اسپیس گیم پروجیکٹس @@ -64,15 +64,15 @@ npm install ```bash cd 6-space-game/solution npm install -# index.html کو براؤزر میں کھولیں یا Live Server استعمال کریں +# براؤزر میں index.html کھولیں یا Live Server استعمال کریں ``` -### چیٹ پروجیکٹ (Python بیک اینڈ) +### چیٹ پروجیکٹ (Python Backend) ```bash cd 9-chat-project/solution/backend/python pip install openai -# GITHUB_TOKEN ماحول کی متغیر مقرر کریں +# GITHUB_TOKEN ماحول کا متغیر سیٹ کریں python api.py ``` @@ -80,203 +80,203 @@ python api.py ### مواد فراہم کرنے والوں کے لیے -1. **ذخیرہ کو فورک کریں** اپنے GitHub اکاؤنٹ پر -2. **اپنے فورک کو لوکل کلون کریں** -3. **اپنی تبدیلیوں کے لیے ایک نیا برانچ بنائیں** -4. سبق کے مواد یا کوڈ مثالوں میں تبدیلی کریں -5. متعلقہ پروجیکٹ ڈائریکٹریز میں کسی بھی کوڈ تبدیلی کی جانچ کریں -6. تعاون کی ہدایتوں کے مطابق پل ریکویسٹ جمع کروائیں +1. اپنے GitHub اکاؤنٹ میں ذخیرہ کی فورک کریں +2. اپنی فورک کا کلون لوکل کریں +3. اپنی تبدیلیوں کے لیے نئی برانچ بنائیں +4. سبق کے مواد یا کوڈ کی مثالوں میں تبدیلی کریں +5. متعلقہ پروجیکٹ ڈائریکٹریز میں کوڈ کی تبدیلیوں کا ٹیسٹ کریں +6. تعاون کی رہنمائی کے مطابق پل ریکویسٹ جمع کروائیں ### سیکھنے والوں کے لیے -1. ذخیرہ فورک یا کلون کریں -2. سبق کی ڈائریکٹریز متواتر ملاحظہ کریں -3. ہر سبق کی README فائل پڑھیں -4. سبق سے پہلے کی کوئزز مکمل کریں https://ff-quizzes.netlify.app/web/ -5. سبق کے فولڈرز میں کوڈ مثالوں پر کام کریں -6. اسائنمنٹس اور چیلنجز مکمل کریں -7. سبق کے بعد کی کوئزز لیں +1. ذخیرہ کو فورک یا کلون کریں +2. سبق کی ڈائریکٹریز میں تسلسل کے ساتھ جائیں +3. ہر سبق کی README فائلز پڑھیں +4. سبق سے پہلے کے کوئزز پورے کریں https://ff-quizzes.netlify.app/web/ +5. سبق کے فولڈرز میں کوڈ کی مثالوں پر کام کریں +6. تفویضات اور چیلنجز مکمل کریں +7. سبق کے بعد کے کوئزز لیں -### لائیو ڈیولپمنٹ +### لائیو ترقی -- **دستاویزات**: جڑ فولڈر میں `docsify serve` چلائیں (پورٹ 3000) -- **کوئز ایپ**: کوئز ایپ فولڈر میں `npm run dev` چلائیں -- **پروجیکٹس**: HTML پروجیکٹس کے لیے VS Code Live Server ایکسٹینشن استعمال کریں -- **API پروجیکٹس**: متعلقہ API ڈائریکٹریز میں `npm start` چلائیں +- **دستاویزات**: روٹ میں `docsify serve` چلائیں (پورٹ 3000) +- **کوئز ایپ**: `quiz-app` ڈائریکٹری میں `npm run dev` چلائیں +- **پروجیکٹس**: HTML پروجیکٹس کے لیے VS Code Live Server ایکسٹینشن استعمال کریں +- **API پروجیکٹس**: متعلقہ API فولڈرز میں `npm start` چلائیں -## جانچ کے ہدایات +## ٹیسٹنگ کی ہدایات -### کوئز ایپ کی جانچ +### کوئز ایپ ٹیسٹنگ ```bash cd quiz-app -npm run lint # کوڈ اسٹائل کے مسائل کی جانچ کریں -npm run build # تصدیق کریں کہ بلڈ کامیاب ہوا +npm run lint # کوڈ کے انداز کے مسائل کی جانچ کریں +npm run build # تعمیری کامیابی کی تصدیق کریں ``` -### بنک API کی جانچ +### بینک API ٹیسٹنگ ```bash cd 7-bank-project/api -npm run lint # کوڈ اسٹائل کے مسائل کی جانچ کریں -node server.js # یقینی بنائیں کہ سرور بغیر غلطیوں کے شروع ہو رہا ہے +npm run lint # کوڈ کی طرز کے مسائل کی جانچ کریں +node server.js # تصدیق کریں کہ سرور بغیر کسی غلطی کے شروع ہوتا ہے ``` -### عمومی جانچ کا طریقہ +### عمومی ٹیسٹنگ کا طریقہ کار -- یہ تعلیمی ذخیرہ ہے، اس میں مکمل خودکار ٹیسٹ نہیں ہیں -- دستی جانچ پر توجہ مرکوز ہے: - - کوڈ مثالیں بغیر ایررز کے چلیں - - دستاویزات میں لنکس صحیح چلیں - - پروجیکٹ کامیابی سے تعمیر ہوں - - مثالیں بہترین طریقوں کی پیروی کریں +- یہ ایک تعلیمی ذخیرہ ہے جس میں مکمل خودکار ٹیسٹ نہیں ہیں +- دستی ٹیسٹنگ پر توجہ مرکوز ہے: + - کوڈ کی مثالیں بغیر غلطی کے چلیں + - دستاویزات میں لنکس صحیح کام کریں + - پروجیکٹ کی تعمیر کامیابی سے مکمل ہو + - مثالیں بہترین طریقے کار کی پیروی کریں -### سبمیشن سے پہلے کی جانچ +### پیشگی جانچ پڑتال -- `npm run lint` چلائیں ان فولڈرز میں جہاں package.json موجود ہو -- مارک ڈاؤن لنکس کی درستگی کی تصدیق کریں -- کوڈ مثالوں کو براؤزر یا Node.js میں ٹیسٹ کریں -- ترجمے کا ڈھانچہ صحیح برقرار رکھا گیا ہو +- وہ فولڈرز جہاں package.json ہو وہاں `npm run lint` چلائیں +- مارک ڈاؤن لنکس کی درستگی چیک کریں +- کوڈ کی مثالوں کو براؤزر یا Node.js میں ٹیسٹ کریں +- یقینی بنائیں کہ ترجمے صحیح ساخت برقرار رکھتے ہیں -## کوڈ اسلوب کی ہدایات +## کوڈ اسٹائل کی ہدایات ### جاوا اسکرپٹ -- جدید ES6+ نحو استعمال کریں -- پروجیکٹس میں مہیا کردہ معیاری ESLint کنفیگریشنز پر عمل کریں -- تعلیمی وضاحت کے لیے بامعنی متغیر اور فنکشن نام استعمال کریں -- سیکھنے والوں کے لیے مفاہیم کی وضاحت کے لیے تبصرے شامل کریں -- جہاں مقرر ہو پر Prettier کے ذریعے فارمیٹ کریں +- جدید ES6+ نحو استعمال کریں +- پروجیکٹس میں فراہم کردہ معیاری ESLint کنفیگریشن استعمال کریں +- تعلیمی وضاحت کے لیے بامعنی متغیر اور فنکشن کے نام رکھیں +- مفہوم وضاحت کے لیے تبصرے شامل کریں +- جہاں کنفیگر کیا گیا ہو وہاں Prettier سے فارمیٹنگ کریں ### HTML/CSS -- معنوی HTML5 عناصر -- جوابدہ ڈیزائن کے اصول -- واضح کلاس نامی کنونشنز +- معنوی HTML5 عناصر استعمال کریں +- جامع ریسپونسیو ڈیزائن اصول +- واضح کلاس ناموں کے اصول - CSS تکنیک کی وضاحت کے لیے تبصرے -### پائتھون +### پائتھن -- PEP 8 طرز کی ہدایات -- واضح، تعلیمی کوڈ مثالیں -- جہاں مددگار ہو، ٹائپ ہنٹس +- PEP 8 اسٹائل گائیڈ لائنز +- واضح، تعلیمی کوڈ کی مثالیں +- جہاں مددگار ہو وہاں ٹائپ ہنٹس ### مارک ڈاؤن دستاویزات -- واضح ہیڈنگ ہائیرارکی -- زبان کی وضاحت کے ساتھ کوڈ بلاکس -- اضافی وسائل کے لنکس -- `images/` فولڈرز میں اسکرین شاٹس اور تصاویر -- امیجز کی رسائی کے لیے Alt ٹیکسٹ +- واضح ہیڈنگ ہائیرارکی +- زبان کی تفصیل کے ساتھ کوڈ بلاکس +- اضافی وسائل کے لنکس +- `images/` ڈائریکٹریز میں اسکرین شاٹس اور تصاویر +- دستیابی کے لیے تصاویر کا alt متن -### فائل آرگنائزیشن +### فائل کا انتظام -- اسباق متواتر نمبروں کے ساتھ (1-getting-started-lessons، 2-js-basics وغیرہ) -- ہر پروجیکٹ میں `solution/` اور اکثر `start/` یا `your-work/` ڈائریکٹریز -- اسباق کے مخصوص `images/` فولڈرز میں تصاویر محفوظ -- ترجمے `translations/{language-code}/` ڈھانچے میں +- اسباق کی متواتر نمبرنگ (1-getting-started-lessons, 2-js-basics وغیرہ) +- ہر پروجیکٹ میں `solution/` اور اکثر `start/` یا `your-work/` ڈائریکٹریز +- تصاویر سبق کی مخصوص `images/` فولڈرز میں محفوظ +- تراجم `translations/{language-code}/` فولڈرز میں -## تعمیر اور تعیناتی +## بلڈ اور تعیناتی -### کوئز ایپ کی تعیناتی (Azure Static Web Apps) +### کوئز ایپ تعیناتی (Azure Static Web Apps) -کوئز ایپ Azure Static Web Apps تعیناتی کے لیے مرتب ہے: +کوئز ایپ Azure Static Web Apps تعیناتی کے لیے کنفیگر ہے: ```bash cd quiz-app -npm run build # فولڈر dist/ بناتا ہے -# مین پر پش ہونے پر GitHub Actions ورک فلو کے ذریعے تعینات کرتا ہے +npm run build # dist/ فولڈر بناتا ہے +# مرکزی شاخ پر push کرنے پر GitHub Actions ورک فلو کے ذریعے تعینات کرتا ہے ``` - -Azure Static Web Apps کی ترتیب: -- **ایپ مقام**: `/quiz-app` -- **آؤٹ پٹ مقام**: `dist` + +Azure Static Web Apps کی ترتیب: +- **ایپ لوکیشن**: `/quiz-app` +- **آؤٹ پٹ لوکیشن**: `dist` - **ورک فلو**: `.github/workflows/azure-static-web-apps-ashy-river-0debb7803.yml` -### دستاویزات کا PDF جنریشن +### دستاویزات PDF جنریشن ```bash npm install # docsify-to-pdf انسٹال کریں npm run convert # docs سے PDF بنائیں ``` - + ### Docsify دستاویزات ```bash npm install -g docsify-cli # دستاویزات کو عالمی سطح پر انسٹال کریں -docsify serve # localhost:3000 پر خدمت دیں +docsify serve # لوکل ہوسٹ:3000 پر خدمت کریں ``` - -### پروجیکٹ مخصوص بیلڈز -ہر پروجیکٹ ڈائریکٹری کا اپنا بنایا جا سکتا عمل ہو سکتا ہے: -- Vue پروجیکٹس: `npm run build` پروڈکشن بنڈلز بناتا ہے -- سٹیٹک پروجیکٹس: کوئی بلڈ اسٹیپ نہیں، فائلیں براہ راست سرور کی جاتی ہیں +### پروجیکٹ مخصوص بلڈز -## پل ریکویسٹ کی ہدایات +ہر پروجیکٹ فولڈر میں اپنا بلڈ عمل ہو سکتا ہے: +- Vue پروجیکٹس: `npm run build` پروڈکشن بنڈلز بناتا ہے +- سادہ پروجیکٹس: کوئی بلڈ مرحلہ نہیں، فائلز براہ راست فراہم کی جاتی ہیں -### عنوان کا انداز +## پل ریکویسٹ کی رہنمائی -صاف اور وضاحتی عنوانات استعمال کریں جو تبدیلی کے شعبے کی نشاندہی کریں: -- `[Quiz-app] سبق X کے لیے نیا کوئز شامل کریں` -- `[Lesson-3] ٹیریریم پروجیکٹ میں ٹائپ کی اصلاح کریں` -- `[Translation] سبق 5 کے لیے ہسپانوی ترجمہ شامل کریں` +### عنوان کی صورت + +صاف اور وضاحتی عنوانات استعمال کریں جو تبدیلی کے دائرہ کو ظاہر کریں: +- `[Quiz-app] سبق X کے لیے نیا کوئز شامل کریں` +- `[Lesson-3] ٹیریریم پروجیکٹ میں ٹائپو درست کریں` +- `[Translation] سبق 5 کے لیے ہسپانوی ترجمہ شامل کریں` - `[Docs] سیٹ اپ ہدایات کو اپ ڈیٹ کریں` ### ضروری چیکس -PR جمع کرانے سے پہلے: +پل ریکویسٹ جمع کرانے سے پہلے: -1. **کوڈ کوالٹی**: - - متعلقہ پروجیکٹ فولڈرز میں `npm run lint` چلائیں - - تمام لنٹنگ کی غلطیاں اور وارننگز درست کریں +1. **کوڈ کوالٹی**: + - متاثرہ پروجیکٹ فولڈرز میں `npm run lint` چلائیں + - تمام لنٹنگ کی غلطیاں اور وارننگز درست کریں -2. **بیلڈ کی تصدیق**: - - اگر ضرورت ہو تو `npm run build` چلائیں - - یقینی بنائیں کہ کوئی بلڈ ایررز نہ ہوں +2. **بلڈ کی تصدیق**: + - اگر قابل اطلاق ہو تو `npm run build` چلائیں + - یقینی بنائیں کہ کوئی بلڈ ایرر نہ ہو -3. **لنک کی تصدیق**: - - تمام مارک ڈاؤن لنکس ٹیسٹ کریں - - تصاویر کے حوالے کی تصدیق کریں +3. **لنک کی توثیق**: + - تمام مارک ڈاؤن لنکس ٹیسٹ کریں + - تصاویر کے ریفرنس درست ہوں -4. **مواد کا جائزہ**: - - املا اور گرامر کی تصحیح کریں - - کوڈ مثالیں درست اور تعلیمی ہوں +4. **مواد کا جائزہ**: + - ہجے اور گرائمر کی جانچ پڑتال کریں + - کوڈ کی مثالیں درست اور تعلیمی ہوں - ترجمے اصل معنی کو برقرار رکھیں -### تعاون کی ضروریات +### تعاون کی شرائط -- Microsoft CLA سے اتفاق کریں (پہلی PR پر خودکار چیک) -- [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/) کی پیروی کریں -- مفصل ہدایات کے لیے [CONTRIBUTING.md](./CONTRIBUTING.md) دیکھیں -- PR کی وضاحت میں مسئلہ نمبرات حوالہ دیں اگر ضروری ہو +- مائیکروسافٹ CLA سے اتفاق کریں (پہلے PR پر خودکار چیک) +- [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/) کی پیروی کریں +- تفصیلی رہنما خطوط کے لیے [CONTRIBUTING.md](./CONTRIBUTING.md) دیکھیں +- اگر قابل اطلاق ہو تو PR وضاحت میں ایشو نمبرز کا حوالہ دیں -### جائزہ کا عمل +### جائزے کا عمل -- PRs مینٹینرز اور کمیونٹی کے ذریعے جائزہ لیے جاتے ہیں -- تعلیمی وضاحت کو اولین ترجیح دی جاتی ہے -- کوڈ مثالیں حالیہ بہترین طریقوں کی پیروی کریں -- ترجمے درستگی اور ثقافتی مطابقت کے لیے دیکھے جاتے ہیں +- PRs دیکھ بھال کرنے والے اور کمیونٹی کی جانب سے جائزہ لیے جاتے ہیں +- تعلیمی وضاحت کو ترجیح دی جاتی ہے +- کوڈ کی مثالیں موجودہ بہترین طریقے کار کی پیروی کریں +- ترجمے درستگی اور ثقافتی مطابقت کے لیے جائزہ کے تابع ہیں -## ترجمے کا نظام +## ترجمہ کا نظام ### خودکار ترجمہ -- GitHub Actions کے ساتھ co-op-translator ورک فلو استعمال کرتا ہے -- 50+ زبانوں میں خودکار ترجمے -- ماخذ فائلیں مرکزی ڈائریکٹریز میں -- ترجمہ کی گئی فائلیں `translations/{language-code}/` میں +- GitHub Actions کو co-op-translator ورک فلو کے ساتھ استعمال کرتا ہے +- 50+ زبانوں میں خودکار طور پر ترجمہ کرتا ہے +- ماخذ فائلیں مرکزی ڈائریکٹریز میں ہیں +- ترجمہ شدہ فائلیں `translations/{language-code}/` ڈائریکٹریز میں -### دستی ترجمے میں بہتری شامل کرنا +### دستی ترجمہ کی بہتریاں شامل کرنا -1. `translations/{language-code}/` میں فائل تلاش کریں -2. ڈھانچہ برقرار رکھتے ہوئے بہتری کریں -3. یقینی بنائیں کہ کوڈ مثالیں فعال رہیں -4. کسی بھی مقامی کوئز مواد کی جانچ کریں +1. `translations/{language-code}/` میں فائل تلاش کریں +2. ساخت برقرار رکھتے ہوئے بہتریاں کریں +3. یقینی بنائیں کہ کوڈ کی مثالیں کارآمد رہیں +4. کسی مقامی کوئز مواد کو ٹیسٹ کریں -### ترجمے کا میٹا ڈیٹا +### ترجمہ مٹاداتا -ترجمہ شدہ فائلوں میں میٹا ڈیٹا ہیڈر شامل ہوتا ہے: +ترجمہ شدہ فائلوں میں مٹاداتا ہیڈر شامل ہوتا ہے: ```markdown ``` - -## خرابی تلاش اور مسئلہ حل کرنا + +## ڈیبگنگ اور مسئلہ حل کرنا ### عام مسائل -**کوئز ایپ شروع نہیں ہوتی**: -- Node.js کا ورژن چیک کریں (v14+ کی سفارش ہے) -- `node_modules` اور `package-lock.json` حذف کریں، پھر `npm install` چلائیں -- پورٹ ٹکراؤ چیک کریں (ڈیفالٹ: Vite پورٹ 5173 استعمال کرتا ہے) +**کوئز ایپ اسٹارٹ نہیں ہوتی**: +- Node.js ورژن چیک کریں (v14+ تجویز کردہ) +- `node_modules` اور `package-lock.json` حذف کریں، پھر `npm install` چلائیں +- پورٹ تنازعہ چیک کریں (ڈیفالٹ: Vite پورٹ 5173 استعمال کرتا ہے) -**API سرور شروع نہیں ہوتا**: -- Node.js ورژن کم از کم node >=10 ہونا چاہیے -- چیک کریں کہ پورٹ پہلے سے استعمال میں نہ ہو -- تمام dependencies `npm install` سے انسٹال ہوں +**API سرور اسٹارٹ نہیں ہوتا**: +- کم از کم Node.js ورژن تصدیق کریں (node >=10) +- چیک کریں کہ پورٹ پہلے سے استعمال میں نہ ہو +- یقینی بنائیں کہ تمام dependencies نصب ہیں `npm install` کے ذریعے -**براؤزر ایکسٹینشن لوڈ نہیں ہوتی**: -- manifest.json کی درست فارمیٹنگ چیک کریں -- براؤزر کنسول میں ایرر دیکھیں -- براؤزر مخصوص ایکسٹینشن انسٹال ہدایات پر عمل کریں +**براؤزر ایکسٹینشن لوڈ نہیں ہوتی**: +- manifest.json کی درست تشکیل چیک کریں +- براؤزر کے کنسول میں ایررز دیکھیں +- براؤزر مخصوص ایکسٹینشن انسٹالیشن ہدایات پر عمل کریں -**Python چیٹ پروجیکٹ کے مسائل**: -- OpenAI پیکج انسٹال ہے: `pip install openai` -- GITHUB_TOKEN ماحولیاتی ویریبل سیٹ ہے -- GitHub Models کی رسائی کی اجازتیں چیک کریں +**Python چیٹ پروجیکٹ کے مسائل**: +- یقینی بنائیں OpenAI پیکیج نصب ہے: `pip install openai` +- GITHUB_TOKEN ماحول کا متغیر سیٹ ہے +- GitHub Models کی رسائی کی اجازت چیک کریں -**Docsify دستاویزات سرور نہیں کر رہا**: -- docsify-cli عالمی طور پر انسٹال کریں: `npm install -g docsify-cli` -- ذخیرہ جڑ فولڈر سے چلائیں -- چیک کریں کہ `docs/_sidebar.md` موجود ہو +**Docsify دستاویزات فراہم نہیں کر رہا**: +- docsify-cli گلوبلی انسٹال کریں: `npm install -g docsify-cli` +- ذخیرہ کی روٹ ڈائریکٹری سے چلائیں +- چیک کریں کہ `docs/_sidebar.md` موجود ہے ### ترقیاتی ماحول کی تجاویز -- HTML پروجیکٹس کے لیے VS Code Live Server ایکسٹینشن استعمال کریں -- مستقل فارمیٹنگ کے لیے ESLint اور Prettier ایکسٹینشن انسٹال کریں -- جاوا اسکرپٹ کی خرابی تلاش کے لیے براؤزر ڈیولپر ٹولز استعمال کریں +- HTML پروجیکٹس کے لیے VS Code Live Server ایکسٹینشن استعمال کریں +- مستقل فارمیٹنگ کے لیے ESLint اور Prettier ایکسٹینشن انسٹال کریں +- JavaScript کی ڈیبگنگ کے لیے براؤزر DevTools استعمال کریں - Vue پروجیکٹس کے لیے Vue DevTools براؤزر ایکسٹینشن انسٹال کریں -### کارکردگی کے امور +### کارکردگی کے پہلو -- ترجمہ شدہ فائلوں کی بڑی تعداد (50+ زبانیں) کی وجہ سے پورے کلون بڑے ہوتے ہیں -- صرف مواد پر کام کرنے کے لیے shallow clone کریں: `git clone --depth 1` -- انگریزی مواد پر کام کرتے ہوئے ترجموں کو سرچ سے خارج کریں -- پہلی بار رن پر بلڈ عمل (npm install، Vite build) سست ہو سکتا ہے +- بڑی تعداد میں ترجمہ شدہ فائلیں (50+ زبانیں) مکمل کلون کو بڑا بناتی ہیں +- صرف مواد پر کام کے لیے shallow clone استعمال کریں: `git clone --depth 1` +- انگریزی مواد پر کام کرتے وقت سرچ سے تراجم کو خارج کریں +- بلڈ عمل پہلے رن پر سست ہو سکتا ہے (npm install, Vite build) -## سیکورٹی کے مسائل +## سیکیورٹی کے پہلو -### ماحولیاتی ویریبلز +### ماحول کے متغیرات -- API کیز کبھی بھی ذخیرہ میں جمع نہ کریں -- `.env` فائلیں استعمال کریں (جو پہلے ہی `.gitignore` میں شامل ہیں) -- ضروری ماحولیاتی ویریبلز کو README میں دستاویز کریں +- API کیز کو ذخیرہ میں کبھی جمع نہ کریں +- `.env` فائلز استعمال کریں (جو پہلے سے `.gitignore` میں ہیں) +- درکار ماحول کے متغیرات کو پروجیکٹ کی README میں دستاویز کریں -### پائتھون پروجیکٹس +### Python پروجیکٹس -- ورچوئل اینوائرنمنٹ استعمال کریں: `python -m venv venv` -- dependencies کو اپ ٹو ڈیٹ رکھیں -- GitHub ٹوکنز کو کم از کم ضروری اجازتیں دیں +- ورچوئل ماحول استعمال کریں: `python -m venv venv` +- dependencies کو اپ ٹو ڈیٹ رکھیں +- GitHub ٹوکنز کو کم سے کم درکار اجازتوں کے ساتھ رکھیں -### GitHub Models تک رسائی +### GitHub Models کی رسائی -- GitHub Models کے لیے Personal Access Tokens (PAT) ضروری ہیں -- ٹوکنز ماحولیاتی ویریبلز کی طرح محفوظ رکھیں -- ٹوکنز یا اسناد کبھی ذخیرہ میں جمع نہ کریں +- GitHub Models کے لیے ذاتی رسائی کے ٹوکن (PAT) ضروری ہیں +- ٹوکنز کو ماحول کے متغیرات کے طور پر محفوظ کریں +- ٹوکنز یا اسناد کو کبھی جمع نہ کریں -## اضافی نوٹس +## اضافی نوٹ ### ہدف سامعین -- ویب ڈویلپمنٹ کے مکمل ابتدائی -- طلباء اور خود سیکھنے والے -- معلمین جو نصاب کلاس روم میں استعمال کرتے ہیں -- مواد قابل رسائی اور تدریجی مہارت سازی کے لیے ڈیزائن کیا گیا ہے +- ویب ڈیولپمنٹ کے مکمل مبتدی +- طلباء اور خود آموز +- اساتذہ جو کلاس رومز میں نصاب استعمال کرتے ہیں +- مواد کو رسائی اور تدریجی مہارت سازی کے لیے ڈیزائن کیا گیا ہے ### تعلیمی فلسفہ -- پروجیکٹ پر مبنی سیکھنے کا طریقہ -- بار بار معلومات کی جانچ (کوئزز) -- عملی کوڈنگ مشقیں -- حقیقی دنیا کی درخواست کی مثالیں -- فریم ورکس سے پہلے بنیادی باتوں پر توجہ +- پروجیکٹ پر مبنی تعلیمی طریقہ +- بار بار علمی جانچ (کوئزز) +- عملی کوڈنگ مشقیں +- حقیقی دنیا کی ایپلیکیشن کی مثالیں +- فریم ورکس سے پہلے بنیادی اصولوں پر توجہ -### ذخیرہ کا نگہداشت +### ذخیرہ کا انتظام -- سیکھنے والوں اور تعاون کاروں کی فعال کمیونٹی -- dependencies اور مواد کی باقاعدہ اپ ڈیٹس -- مسائل اور مباحثے مینٹینرز کے زیر نگرانی -- ترجمے کی تازہ کاری خودکار طور پر GitHub Actions کے ذریعہ +- سیکھنے والوں اور تعاون کرنے والوں کی فعال کمیونٹی +- dependencies اور مواد کی باقاعدہ اپ ڈیٹس +- دیکھ بھال کرنے والوں کی جانب سے مسائل اور مباحثے کی نگرانی +- GitHub Actions کے ذریعے ترجمہ کی خودکار اپ ڈیٹس ### متعلقہ وسائل -- [Microsoft Learn modules](https://docs.microsoft.com/learn/) -- [Student Hub resources](https://docs.microsoft.com/learn/student-hub/) -- [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) جو سیکھنے والوں کے لیے تجویز کردہ ہے -- اضافی کورسز: جنریٹو AI، ڈیٹا سائنس، ML، IoT نصاب دستیاب ہیں +- [Microsoft Learn ماڈیولز](https://docs.microsoft.com/learn/) +- [Student Hub کے وسائل](https://docs.microsoft.com/learn/student-hub/) +- [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) سیکھنے والوں کے لیے تجویز کردہ +- اضافی کورسز: جنریٹو AI، ڈیٹا سائنس، ML، IoT نصاب دستیاب -### مخصوص پروجیکٹس کے ساتھ کام +### مخصوص پروجیکٹس کے ساتھ کام کرنا -انفرادی پروجیکٹس کی تفصیلی ہدایات کے لیے، README فائلیں دیکھیں: -- `quiz-app/README.md` - Vue 3 کوئز ایپلیکیشن -- `7-bank-project/README.md` - توثیق کے ساتھ بنکنگ ایپلیکیشن -- `5-browser-extension/README.md` - براؤزر ایکسٹینشن ڈیولپمنٹ -- `6-space-game/README.md` - کینوس پر مبنی گیم ڈیولپمنٹ +انفرادی پروجیکٹس کی تفصیلی ہدایات کے لیے درج ذیل README فائلز دیکھیں: +- `quiz-app/README.md` - Vue 3 کوئز ایپلیکیشن +- `7-bank-project/README.md` - بینکنگ ایپلیکیشن کے ساتھ توثیق +- `5-browser-extension/README.md` - براؤزر ایکسٹینشن ڈیولپمنٹ +- `6-space-game/README.md` - کینوس پر مبنی گیم کی تیاری - `9-chat-project/README.md` - AI چیٹ اسسٹنٹ پروجیکٹ -### مونو ریپو ڈھانچہ +### منوریپو ساخت -روایتی مونو ریپو تو نہیں، لیکن اس ذخیرے میں متعدد آزاد پروجیکٹس شامل ہیں: -- ہر سبق خود مختار ہے -- پروجیکٹس کی dependencies مشترک نہیں ہیں -- ایک دوسرے کو متاثر کیے بغیر انفرادی پروجیکٹس پر کام کریں -- مکمل نصاب کے لیے پورے ذخیرے کو کلون کریں +اگرچہ یہ روایتی monorepo نہیں ہے، مگر اس ذخیرے میں متعدد آزاد پروجیکٹس شامل ہیں: +- ہر سبق خود سے مکمل ہے +- پروجیکٹس ایک دوسرے کی dependencies شیئر نہیں کرتے +- ایک ساتھ دوسرے پروجیکٹس کو متاثر کیے بغیر الگ الگ کام کریں +- پورے نصاب کے تجربے کے لیے مکمل ذخیرہ کلون کریں --- -**ڈس کلیمر**: -یہ دستاویز AI ترجمہ خدمت [Co-op Translator](https://github.com/Azure/co-op-translator) استعمال کرتے ہوئے ترجمہ کی گئی ہے۔ اگرچہ ہم درستگی کے لیے کوشاں ہیں، براہ کرم آگاہ رہیں کہ خودکار تراجم میں غلطیاں یا عدم درستیاں ہو سکتی ہیں۔ اصل دستاویز اپنی مادری زبان میں مستند ماخذ سمجھی جانی چاہیے۔ اہم معلومات کے لیے پیشہ ور انسانی ترجمہ کی سفارش کی جاتی ہے۔ ہم اس ترجمے کے استعمال سے پیدا ہونے والی کسی بھی غلط فہمی یا غلط تعبیر کے ذمہ دار نہیں ہیں۔ +**دھرنا**: +یہ دستاویز AI ترجمہ سروس [Co-op Translator](https://github.com/Azure/co-op-translator) کے ذریعے ترجمہ کی گئی ہے۔ اگرچه ہم درستگی کے لیے کوشاں ہیں، براہ کرم نوٹ کریں کہ خودکار ترجموں میں غلطیاں یا عدم درستگیاں ہو سکتی ہیں۔ اصل دستاویز اپنی مادری زبان میں ہی مستند ماخذ سمجھی جانی چاہیے۔ اہم معلومات کے لیے پیشہ ور انسانی ترجمہ کی سفارش کی جاتی ہے۔ اس ترجمے کے استعمال سے پیدا ہونے والی کسی بھی غلط فہمی یا غلط تشریح کی ذمہ داری ہم پر نہیں ہوگی۔ \ No newline at end of file diff --git a/translations/zh-CN/.co-op-translator.json b/translations/zh-CN/.co-op-translator.json index 59b60b440..f9ccd78b6 100644 --- a/translations/zh-CN/.co-op-translator.json +++ b/translations/zh-CN/.co-op-translator.json @@ -493,7 +493,7 @@ }, "AGENTS.md": { "original_hash": "a362efd06d64d4134a0cfe8515a86d34", - "translation_date": "2026-04-06T19:00:10+00:00", + "translation_date": "2026-04-20T16:01:28+00:00", "source_file": "AGENTS.md", "language_code": "zh-CN" }, diff --git a/translations/zh-CN/AGENTS.md b/translations/zh-CN/AGENTS.md index 188e632e8..9c721fed9 100644 --- a/translations/zh-CN/AGENTS.md +++ b/translations/zh-CN/AGENTS.md @@ -2,53 +2,53 @@ ## 项目概述 -这是一个面向初学者教授网页开发基础的教学课程代码库。该课程由微软云推广者开发，是一个为期12周的综合课程，包括24个涵盖JavaScript、CSS和HTML的实践课程。 +这是一个面向初学者教授网页开发基础知识的教育课程仓库。该课程是一门由微软云宣传人员开发的为期12周的综合课程，包含24个涵盖JavaScript、CSS和HTML的实践课程。 -### 主要组成部分 +### 关键组成部分 -- 教学内容：24节结构化课程，组织成基于项目的模块 -- 实践项目：生态瓶、打字游戏、浏览器扩展、太空游戏、银行应用、代码编辑器和AI聊天助手 +- 教学内容：24个结构化课程，按项目模块组织 +- 实用项目：生态瓶、打字游戏、浏览器扩展、太空游戏、银行应用、代码编辑器和AI聊天助手 - 互动测验：48个测验，每个包含3个问题（课前/课后评估） - 多语言支持：通过GitHub Actions自动翻译50多种语言 - 技术栈：HTML、CSS、JavaScript、Vue.js 3、Vite、Node.js、Express、Python（用于AI项目） ### 架构 -- 基于课程结构的教育代码库 -- 每节课的文件夹包含README、代码示例和解决方案 -- 独立项目放在单独目录（quiz-app，各个课程项目） -- 使用GitHub Actions（co-op-translator）进行翻译系统 -- 文档通过Docsify服务并提供PDF版本 +- 教育仓库，基于课程结构 +- 每课文件夹包含README、代码示例和解决方案 +- 独立项目位于单独目录（quiz-app、各种课程项目） +- 使用GitHub Actions（co-op-translator）实现翻译系统 +- 文档通过Docsify提供，并可导出为PDF -## 安装命令 +## 设置命令 -该代码库主要用于学习内容浏览。若要使用特定项目： +此仓库主要用于教学内容的使用。若需使用具体项目： -### 主代码库设置 +### 主仓库设置 ```bash git clone https://github.com/microsoft/Web-Dev-For-Beginners.git cd Web-Dev-For-Beginners ``` -### Quiz App 设置（Vue 3 + Vite） +### 测验应用设置（Vue 3 + Vite） ```bash cd quiz-app npm install npm run dev # 启动开发服务器 -npm run build # 生成生产版本 +npm run build # 构建生产版本 npm run lint # 运行 ESLint ``` -### 银行项目API（Node.js + Express） +### 银行项目 API（Node.js + Express） ```bash cd 7-bank-project/api npm install -npm start # 启动API服务器 -npm run lint # 运行ESLint -npm run format # 使用Prettier格式化 +npm start # 启动 API 服务器 +npm run lint # 运行 ESLint +npm run format # 使用 Prettier 格式化 ``` ### 浏览器扩展项目 @@ -56,7 +56,7 @@ npm run format # 使用Prettier格式化 ```bash cd 5-browser-extension/solution npm install -# 遵循特定浏览器的扩展加载说明 +# 遵循浏览器特定的扩展加载说明 ``` ### 太空游戏项目 @@ -64,10 +64,10 @@ npm install ```bash cd 6-space-game/solution npm install -# 在浏览器中打开 index.html 或使用 Live Server +# 在浏览器中打开 index.html 或使用实时服务器 ``` -### 聊天项目（Python后端） +### 聊天项目（Python 后端） ```bash cd 9-chat-project/solution/backend/python @@ -76,42 +76,42 @@ pip install openai python api.py ``` -## 开发工作流程 +## 开发工作流 -### 内容贡献者指南 +### 内容贡献者 -1. Fork代码库到你的GitHub账号 -2. 克隆你的fork到本地 -3. 创建新分支进行修改 +1. Fork 仓库到你的GitHub账号 +2. **克隆你的 Fork** 到本地 +3. 创建新的分支 用于改动 4. 修改课程内容或代码示例 -5. 在相关项目目录测试代码更改 +5. 在相关项目目录中测试代码改动 6. 按贡献指南提交拉取请求 -### 学习者指引 +### 学习者 -1. Fork或克隆代码库 +1. Fork 或克隆仓库 2. 按顺序进入课程目录 -3. 阅读每节课的README文件 +3. 阅读每课的README文件 4. 在 https://ff-quizzes.netlify.app/web/ 完成课前测验 -5. 通过代码示例学习各课程内容 +5. 按课程学习代码示例 6. 完成作业和挑战 -7. 参与课后测验 +7. 参加课后测验 ### 实时开发 -- 文档：在根目录运行 `docsify serve`（端口3000） -- **Quiz App**：在 quiz-app 目录运行 `npm run dev` -- 项目：使用VS Code Live Server扩展运行HTML项目 -- **API项目**：在各API目录运行 `npm start` +- 文档：在根目录运行 `docsify serve` （端口3000） +- 测验应用：在quiz-app目录运行 `npm run dev` +- 项目：使用VS Code Live Server扩展打开HTML项目 +- **API项目**：分别在对应API目录运行 `npm start` -## 测试说明 +## 测试指南 -### Quiz App 测试 +### 测验应用测试 ```bash cd quiz-app npm run lint # 检查代码风格问题 -npm run build # 验证构建成功 +npm run build # 验证构建是否成功 ``` ### 银行API测试 @@ -122,73 +122,73 @@ npm run lint # 检查代码风格问题 node server.js # 验证服务器启动无错误 ``` -### 一般测试方法 +### 测试总体方法 -- 这是教育代码库，没有完整自动化测试 -- 手动测试重点： +- 这是一个没有完整自动测试的教学仓库 +- 手动测试关注点： - 代码示例无错误运行 - - 文档链接正常 - - 项目可成功构建 - - 示例遵循最佳实践 + - 文档中的链接正常 + - 项目构建成功完成 + - 示例符合最佳实践 ### 提交前检查 -- 在有 package.json 的目录运行 `npm run lint` -- 验证markdown链接有效 +- 在含package.json的目录运行 `npm run lint` +- 验证Markdown链接有效 - 在浏览器或Node.js中测试代码示例 -- 确认翻译保留正确结构 +- 检查翻译结构是否正确保持 ## 代码风格指南 ### JavaScript - 使用现代ES6+语法 -- 遵循项目中提供的ESLint标准配置 +- 遵循项目中的标准ESLint配置 - 使用有意义的变量和函数名，便于教学理解 - 添加注释解释概念 -- 在配置Prettier的地方格式化代码 +- 配置Prettier进行代码格式化 ### HTML/CSS -- 使用语义化HTML5元素 -- 采用响应式设计原则 -- 规范的类命名 -- 注释CSS技术以便教学 +- 语义化的HTML5元素 +- 响应式设计原则 +- 清晰的类命名规范 +- 注释说明CSS技术点 ### Python -- 遵循PEP 8风格指南 -- 清晰、教学友好的代码示例 -- 在有助于学习的地方使用类型提示 +- 遵循PEP 8规范 +- 清晰的教学示例代码 +- 适当添加类型提示，便于学习 ### Markdown文档 -- 清晰的标题层级结构 -- 指定语言的代码块 -- 额外资源链接 -- 放在 `images/` 目录内的截图和图片 -- 图片的替代文本，方便无障碍访问 +- 明确的标题层级结构 +- 代码块标明语言 +- 资源链接 +- 在`images/`目录下存放截图和图片 +- 图片含有Alt文本，方便无障碍访问 ### 文件组织 -- 课程编号有序，例如 1-getting-started-lessons，2-js-basics 等 -- 每个项目含有 `solution/` 文件夹，通常还有 `start/` 或 `your-work/` -- 图片存储在课程对应的 `images/` 文件夹 -- 翻译文件存放于 `translations/{language-code}/` 结构 +- 课程按顺序编号（1-getting-started-lessons、2-js-basics等） +- 每个项目包含`solution/`，通常还有`start/`或`your-work/`目录 +- 图片存放在对应课程的`images/`文件夹 +- 翻译文件在`translations/{language-code}/`结构下 ## 构建与部署 -### Quiz App 部署（Azure Static Web Apps） +### 测验应用部署（Azure Static Web Apps） -quiz-app 已配置为部署到 Azure Static Web Apps： +quiz-app配置为Azure静态网页应用部署： ```bash cd quiz-app npm run build # 创建 dist/ 文件夹 -# 在推送到 main 时通过 GitHub Actions 工作流进行部署 +# 在 push 到 main 时通过 GitHub Actions 工作流部署 ``` -Azure Static Web Apps 配置： +Azure静态网页应用配置： - 应用位置：`/quiz-app` - 输出位置：`dist` - 工作流：`.github/workflows/azure-static-web-apps-ashy-river-0debb7803.yml` @@ -200,78 +200,78 @@ npm install # 安装 docsify-to-pdf npm run convert # 从 docs 生成 PDF ``` -### Docsify 文档 +### Docsify文档 ```bash npm install -g docsify-cli # 全局安装 Docsify -docsify serve # 在 localhost:3000 上提供服务 +docsify serve # 在 localhost:3000 上启动服务 ``` -### 各项目特定构建 +### 项目专属构建 -每个项目目录可能有自己的构建流程： -- Vue项目：运行 `npm run build` 生成生产包 +各项目目录可能有自己的构建流程： +- Vue项目：运行`npm run build`生成生产包 - 静态项目：无构建步骤，直接提供文件 ## 拉取请求指南 ### 标题格式 -使用清晰且描述性标题说明修改区域： +使用清晰、描述性的标题，说明改动内容： - `[Quiz-app] 新增第X课测验` -- `[Lesson-3] 修正生态瓶项目中的拼写错误` -- `[Translation] 添加第5课西班牙语翻译` -- `[Docs] 更新安装说明` +- `[Lesson-3] 修复生态瓶项目拼写错误` +- `[Translation] 为第5课添加西班牙语翻译` +- `[Docs] 更新设置说明` -### 必须检查项 +### 必需检查 提交PR前： 1. 代码质量： - 在相关项目目录运行 `npm run lint` - - 解决所有lint错误和警告 + - 修复所有lint错误和警告 2. 构建验证： - - 若适用，运行 `npm run build` + - 如适用，运行`npm run build` - 确保无构建错误 -3. 链接有效性： - - 测试所有markdown链接 +3. 链接验证： + - 测试所有Markdown链接 - 确认图片引用正常 -4. 内容审查： - - 校对拼写和语法 - - 确认代码示例正确且适合教学 - - 确认翻译保持原意 +4. 内容校对： + - 拼写和语法检查 + - 确保代码示例正确且有教学价值 + - 翻译准确保持原意 ### 贡献要求 - 同意微软CLA（首次PR自动检查） - 遵守[微软开源行为准则](https://opensource.microsoft.com/codeofconduct/) -- 详规见 [CONTRIBUTING.md](./CONTRIBUTING.md) -- 若有，PR描述中引用issue编号 +- 请参阅[CONTRIBUTING.md](./CONTRIBUTING.md)了解详细指南 +- 若相关，请在PR描述中注明issue编号 ### 审核流程 -- 由维护者和社区审核PR -- 优先保证教学清晰度 -- 代码示例应遵循最新最佳实践 -- 翻译需审校准确且文化适配 +- PR由维护者和社区审核 +- 优先保证教育清晰度 +- 代码示例应遵循当前最佳实践 +- 翻译要求准确且文化适应 ## 翻译系统 ### 自动翻译 -- 使用GitHub Actions与co-op-translator工作流 -- 自动翻译成50多种语言 -- 源文件保存在主目录 -- 翻译文件在 `translations/{language-code}/` 目录 +- 使用GitHub Actions的co-op-translator工作流 +- 自动翻译50多种语言 +- 源文件位于主目录 +- 翻译文件存放于`translations/{language-code}/`目录 -### 添加人工翻译改进 +### 手动改进翻译 -1. 定位到 `translations/{language-code}/` 文件 -2. 在保留结构的前提下进行改进 -3. 确保代码示例仍然可用 +1. 在`translations/{language-code}/`找到文件 +2. 保持结构下做改进 +3. 确保代码示例依然可用 4. 测试本地化测验内容 ### 翻译元数据 @@ -289,120 +289,120 @@ CO_OP_TRANSLATOR_METADATA: --> ``` -## 调试与故障排除 +## 调试与排错 ### 常见问题 -**Quiz app 启动失败**： +测验应用启动失败： - 检查Node.js版本（建议v14+） -- 删除 `node_modules` 和 `package-lock.json`，重新运行 `npm install` +- 删除`node_modules`和`package-lock.json`，重新运行`npm install` - 检查端口冲突（默认Vite使用5173端口） **API服务器无法启动**： -- 确认Node.js版本符合最低要求（node >=10） +- 验证Node.js版本（node >=10） - 检查端口是否被占用 -- 确保运行了 `npm install` 安装所有依赖 +- 确认所有依赖已安装`npm install` -浏览器扩展加载失败： -- 验证 manifest.json 格式正确 -- 查看浏览器控制台是否有错误 -- 参考浏览器特定扩展安装说明 +浏览器扩展无法加载： +- 确认manifest.json格式正确 +- 检查浏览器控制台错误 +- 按浏览器扩展安装说明操作 **Python聊天项目问题**： -- 确保已安装OpenAI包：`pip install openai` -- 确认已设置 GITHUB_TOKEN 环境变量 -- 检查GitHub Models访问权限 +- 确认已安装OpenAI包：`pip install openai` +- 确认GITHUB_TOKEN环境变量已设置 +- 检查GitHub模型访问权限 -**Docsify不提供文档服务**： -- 全局安装 docsify-cli：`npm install -g docsify-cli` -- 从仓库根目录运行 -- 确认 `docs/_sidebar.md` 文件存在 +**Docsify未提供文档**： +- 全局安装docsify-cli：`npm install -g docsify-cli` +- 在仓库根目录运行 +- 检查`docs/_sidebar.md`是否存在 -### 开发环境建议 +### 开发环境提示 -- 使用带有Live Server扩展的VS Code处理HTML项目 -- 安装ESLint和Prettier扩展实现统一格式 -- 使用浏览器开发工具调试JavaScript +- HTML项目推荐使用VS Code Live Server扩展 +- 安装ESLint和Prettier扩展保持格式一致 +- 利用浏览器开发者工具调试JavaScript - Vue项目安装Vue DevTools浏览器扩展 ### 性能考虑 -- 有大量翻译文件（50+语言），完整克隆体积较大 -- 如只修改内容，建议使用浅克隆：`git clone --depth 1` -- 处理英语内容时排除翻译文件搜索 -- 构建流程首次运行可能较慢（npm安装、Vite构建） +- 多语言翻译文件众多（50+语言）导致完整克隆体积大 +- 仅工作内容时可使用浅克隆：`git clone --depth 1` +- 编辑英文内容时排除翻译文件搜索 +- 初次运行构建过程较慢（npm install，Vite构建） -## 安全注意事项 +## 安全考虑 ### 环境变量 - API密钥绝不可提交到仓库 -- 使用 `.env` 文件（已列入 `.gitignore`） -- 项目README中说明必要的环境变量 +- 使用`.env`文件（已包含在`.gitignore`中） +- 在项目README中注明所需环境变量 ### Python项目 - 使用虚拟环境：`python -m venv venv` - 保持依赖更新 -- GitHub令牌需最低权限原则 +- GitHub令牌应仅授予必要权限 -### GitHub Models访问 +### GitHub模型访问权限 -- 需要个人访问令牌（PAT） -- 将令牌存储为环境变量 -- 切勿提交令牌或凭据 +- 访问GitHub模型需要个人访问令牌（PAT） +- 令牌应存为环境变量 +- 严禁提交令牌或凭据 ## 其他说明 -### 目标群体 +### 目标受众 -- 完全初学者的网页开发学习者 +- 完全的网页开发初学者 - 学生和自学者 -- 在课堂上使用该课程的教师 -- 内容注重无障碍性和循序渐进技能建设 +- 教室中使用该课程的教师 +- 内容设计注重无障碍和渐进技能培养 ### 教学理念 - 基于项目的学习方法 - 频繁的知识检测（测验） -- 实践编码练习 -- 真实应用案例示范 -- 先掌握基础，再学框架 +- 实操编码练习 +- 真实应用示例 +- 先掌握基础再学框架 -### 代码库维护 +### 仓库维护 - 活跃的学习者和贡献者社区 -- 定期更新依赖和课程内容 -- 维护者监控issue和讨论 -- 通过GitHub Actions自动更新翻译 +- 定期更新依赖和内容 +- 维护者监控问题和讨论 +- 翻译更新自动化通过GitHub Actions ### 相关资源 -- [微软Learn学习模块](https://docs.microsoft.com/learn/) +- [Microsoft Learn模块](https://docs.microsoft.com/learn/) - [学生中心资源](https://docs.microsoft.com/learn/student-hub/) -- 推荐学习者使用 [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) -- 其他课程：生成式AI、数据科学、机器学习、物联网课程 +- 推荐学习者使用[GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) +- 额外课程：生成式AI、数据科学、机器学习、物联网课程等 -### 具体项目使用 +### 使用具体项目 -查看各项目 README 获取详细说明： +详见各项目README文件： - `quiz-app/README.md` - Vue 3测验应用 -- `7-bank-project/README.md` - 带身份验证的银行应用 +- `7-bank-project/README.md` - 带认证的银行应用 - `5-browser-extension/README.md` - 浏览器扩展开发 - `6-space-game/README.md` - 基于Canvas的游戏开发 - `9-chat-project/README.md` - AI聊天助手项目 ### Monorepo结构 -虽然不是传统monorepo，该代码库包含多个独立项目： -- 每节课内容独立完整 -- 各项目不共享依赖 -- 可独立开发各个项目，互不影响 -- 克隆整个代码库体验完整课程内容 +虽非传统monorepo，但此仓库包含多个独立项目： +- 每课内容自成体系 +- 项目不共享依赖 +- 可单独开发项目互不影响 +- 克隆整个仓库获得完整课程体验 --- **免责声明**： -本文件使用 AI 翻译服务 [Co-op Translator](https://github.com/Azure/co-op-translator) 翻译而成。虽然我们力求准确，但请注意自动翻译可能包含错误或不准确之处。原始语言的原始文件应被视为权威来源。对于关键信息，建议使用专业人工翻译。我们不对因使用本翻译而引起的任何误解或误释承担责任。 +本文件由 AI 翻译服务 [Co-op Translator](https://github.com/Azure/co-op-translator) 进行翻译。虽然我们力求准确，但请注意自动翻译可能包含错误或不准确之处。原文的母语版本应被视为权威来源。对于重要信息，建议使用专业人工翻译。我们不对因使用本翻译而产生的任何误解或误释承担责任。 \ No newline at end of file