الموقع

صفحة التعريف المبنية بـ Next.js في مجلد website/

3 دقائق قراءة7 أقسام

مجلد website/ يحتوي صفحة التعريف بـ CleanLens وصفحات التوثيق التي تعرض مجلد docs/ هذا. إنه تطبيق منفصل: لا يستورد كود الإضافة، وله package.json وملف قفل خاصان به، وليس جزءاً من حزمة الإضافة.

التقنيات

الجزء	النسخة / الاختيار
إطار العمل	Next.js 16 ‏(App Router)
الواجهة	React 19، وTailwind CSS 4
تعدد اللغات	i18next + react-i18next، و`accept-language`
الخلفية ثلاثية الأبعاد	Three.js
الحركة	GSAP ‏(`@gsap/react`)
عرض التوثيق	`marked` ‏(Markdown)، و`shiki` (تلوين الكود)، و`github-slugger` (معرّفات العناوين)
الخطوط	Alexandria وIBM Plex Sans Arabic وIBM Plex Sans وJetBrains Mono (عبر `next/font/google`)
Node	‏20.9 أو أحدث

التشغيل

bash

cd website
npm install
npm run dev     # http://localhost:3000 → redirects to /ar, /en or /tr
npm run build
npm start
npm run lint

next.config.ts يضبط turbopack.root على مجلد website/، لأن ملف القفل الخاص بالإضافة في المستوى الأعلى كان سيربك Next.js في تحديد جذر المشروع.

الهيكل

text

website/
├── app/
│   ├── [locale]/
│   │   ├── layout.tsx      fonts, <html lang/dir>, metadata, theme bootstrap
│   │   ├── page.tsx        renders HomePageContent for the locale
│   │   ├── docs/page.tsx   docs home (cards per group)
│   │   ├── docs/[slug]/page.tsx   one doc page
│   │   └── globals.css
│   ├── i18n/
│   │   ├── settings.js     languages, fallback, RTL list, cookie name
│   │   ├── index.js        server-side getTranslation()
│   │   └── locales/{ar,en,tr}/translation.json
│   └── icon.png
├── components/
│   ├── ForPages/Home/      one folder per page section (see below)
│   ├── ForPages/Docs/      DocsShell, DocsSidebar, DocArticle, DocToc, docs.css
│   └── Global/             Navbar, LanguageSwitcher, Footer, ThemeToggle,
│                           BackToTop, CopyCommandButton, RichText, Icons
├── lib/constants.ts        Marketplace URL, extension id, install command,
│                           EXTENSION_VERSION, theme storage key
├── lib/docs.ts             reads and renders docs/*.md (build time)
├── proxy.ts                locale redirect (Next.js 16 "proxy", formerly middleware)
└── public/images/

أقسام الصفحة

components/ForPages/Home/HomePageContent.tsx يعرض بالترتيب:

القسم	المجلد	المحتوى
الخلفية	`Scene/`	مشهد ثلاثي الأبعاد متحرك لشجرة Git ‏(Three.js)
الواجهة الرئيسية	`Hero/`	العنوان، وأمر التثبيت يُكتب تلقائياً، وبطاقة مائلة
Vibe coding	`VibeCoding/`	عرض لنتائج الفحص على كود مولَّد بالذكاء الاصطناعي
المشكلة	`Problem/`	لماذا النسب المبني على blame غير عادل (مثال ملف قديم)
خط التحليل	`Pipeline/`	مراحل التحليل
التقييم	`Scoring/`	معادلة الدرجة، وبطاقة مطوّر نموذجية
القواعد	`Rules/`	القواعد الأربع عشرة
الاستخدام	`Usage/`	تبويبات الإضافة مقابل سطر الأوامر
الجمهور	`Audience/`	لمن هذه الأداة
الخصوصية	`Privacy/`	ضمانات العمل المحلي فقط
القيود	`Limits/`	القيود بصراحة
الخطة القادمة	`Roadmap/`	العمل المخطط له
الدعوة الأخيرة	`FinalCta/`	دعوة للتثبيت

Motion/ScrollAnimations.tsx يضيف تأثيرات GSAP عند التمرير.

صفحات التوثيق

زر ملفات التوثيق في شريط التنقل يفتح /<locale>/docs. الصفحات تُبنى من مجلد docs/ في المستودع وقت البناء (ثابتة بالكامل).

المسار	المحتوى
`/<locale>/docs`	الصفحة الرئيسية للتوثيق: بطاقة بارزة لدليل الضبط، ثم بطاقة لكل ملف، مجمّعة كما في `docs/README.md`
`/<locale>/docs/<slug>`	ملف واحد: القائمة الجانبية، والمقال، و"في هذه الصفحة"، والسابق/التالي

الـ slug هو اسم الملف بدون رقمه: 08-scoring.md ← /ar/docs/scoring.

من أين يأتي المحتوى (lib/docs.ts):

القائمة والترتيب والمجموعات والعناوين والملخصات تُقرأ من الجداول في docs/README.md (أو docs/<locale>/README.md)، فإضافة سطر هناك تضيف صفحة.
/ar/... يقرأ من docs/ar/، و/tr/... من docs/tr/، و/en/... من docs/. الترجمة المفقودة تعود إلى الإنجليزية (وتُعرض من اليسار لليمين).
يُعثر على مجلد docs/ بجانب website/ سواء شُغّل الخادم من website/ أو من جذر المستودع. اضبط CLEANLENS_DOCS_DIR لتحديد مسار آخر. يجب أن تتضمن عمليات النشر مجلد docs/ وقت البناء.

العرض:

العناوين تأخذ معرّفات بـ github-slugger؛ والعناوين المترجمة تعيد استخدام المعرّفات الإنجليزية حسب موقعها (انظر 15).
الروابط إلى ملفات توثيق أخرى تصبح روابط داخل الموقع؛ والروابط إلى ملفات المستودع (الكود المصدري، وREADME الرئيسي) تُعرض كنص عادي لأن المستودع خاص.
كتل الكود تُلوَّن بـ shiki في السمتين الفاتحة والداكنة، ولكل منها زر نسخ. والجداول تتمرر أفقياً على الشاشات الصغيرة. والاقتباسات تظهر كصناديق تنبيه.

الواجهة: قائمة جانبية مع بحث (اضغط / أو Ctrl/Cmd+K؛ يطابق العناوين والملخصات وعناوين الأقسام)، وقائمة "في هذه الصفحة" تتبع التمرير، وروابط السابق/التالي، وقائمة منزلقة للجوال تحت 960 px، واتجاه من اليمين لليسار للعربية. نصوص الواجهة موجودة في مفاتيح docs.* في ملفات الترجمة.

اللغات

المدعومة: العربية (ar، الافتراضية والاحتياطية، من اليمين لليسار)، والإنجليزية (en)، والتركية (tr).
كل النصوص موجودة في app/i18n/locales/<lng>/translation.json.
dirFor(lng) يضبط dir="rtl" للعربية.
النص المنسّق في الترجمات يستخدم وسوماً معرّفة في components/Global/RichText/RichText.tsx: ‏<hl> (تمييز)، و<code>، و<kbd>، و<mk> (رابط المتجر)، وغيرها.

توجيه اللغة (`proxy.ts`)

لأي مسار ليس فيه بادئة لغة، يُحوَّل الزائر إلى لغة تُختار بالترتيب من: ملف تعريف الارتباط i18next ← ترويسة Accept-Language ← العربية. وعند زيارة صفحة تحت لغة ما، تُحفظ تلك اللغة في ملف تعريف الارتباط. الملفات الثابتة (_next وimages وassets وfavicon.ico، …) لا تُحوَّل.

إضافة لغة

أضف رمز اللغة إلى languages في app/i18n/settings.js (وإلى rtlLanguages إذا كانت من اليمين لليسار).
أنشئ app/i18n/locales/<code>/translation.json بنفس مفاتيح en.
أضف أسماءها إلى LABELS وSHORT في components/Global/Navbar/LanguageSwitcher.tsx (المبدّل يعرض كل عناصر languages).
أضف مجموعة الأحرف للخط في app/[locale]/layout.tsx إذا احتاجتها الكتابة.

السمة

الفاتحة هي الافتراضية. اختيار الزائر يُحفظ في localStorage تحت cleanlens-theme ‏(THEME_KEY) ويطبّقه الـ layout قبل الرسم، لتجنّب وميض السمة الخاطئة.

قائمة التحقق عند إصدار الموقع

حدّث EXTENSION_VERSION في lib/constants.ts ليطابق package.json.
إذا تغيّرت القواعد أو التقييم أو القيود، حدّث الأقسام المقابلة في ملفات الترجمة الثلاثة.

#التقنيات

#التشغيل

#الهيكل

#أقسام الصفحة

#صفحات التوثيق

#اللغات

#توجيه اللغة (proxy.ts)

#إضافة لغة

#السمة

#قائمة التحقق عند إصدار الموقع