# الاستخدام التفصيلي

يغطي هذا الدليل سير عمل واجهة سطر الأوامر (CLI) الشائعة. راجع `docs/docker.md` للحصول على تعليمات Docker و `docs/templates.md` لقوالب المنشورات المتاحة.

## المتطلبات الأساسية

تم تصميم VoxVera ليكون سهل النقل للغاية ويتطلب الحد الأدنى من تبعيات النظام.

### 1. الملفات الثنائية المستقلة (موصى به)
يمكنك تنزيل ملفات ثنائية مستقلة بدون تبعيات لنظام التشغيل الخاص بك:
- **Linux:** `voxvera-linux`
- **Windows:** `voxvera-windows.exe`
- **macOS:** `voxvera-macos`

تتضمن هذه الملفات الثنائية كل ما يلزم لتشغيل VoxVera (باستثناء `onionshare-cli`).

### 2. المثبت بنقرة واحدة
بدلاً من ذلك، قم بالتثبيت عبر البرمجية النصية المؤتمتة الخاصة بنا:

```bash
curl -fsSL https://raw.githubusercontent.com/PR0M3TH3AN/VoxVera/main/install.sh | bash
```

### 3. تثبيت Python اليدوي
إذا كنت تفضل التشغيل من المصدر:

```bash
pipx install 'voxvera@git+https://github.com/PR0M3TH3AN/VoxVera.git@main'
sudo apt install tor onionshare-cli   # Debian/Ubuntu
```

## خطوة بخطوة

1. **التهيئة:** قم بتشغيل `voxvera init` واتبع المطالبات. سيُطلب منك اختيار لغتك أولاً.
2. **البناء:** قم بإنشاء أصول المنشور. ينشئ كل بناء تلقائياً ملف `voxvera-portable.zip` في مجلد المنشور، مما يسمح للآخرين بتنزيل الأداة الكاملة مباشرة من منشورك.
   ```bash
   voxvera build
   ```
3. **الخدمة:** انشر المنشور عبر Tor:
   ```bash
   voxvera serve
   ```
   يكتشف هذا تلقائياً نسخة Tor الخاصة بك، ويبدأ OnionShare، ويكتب عنوان .onion الناتج في روابط المنشور القابلة للنزع.

## دعم اللغة

VoxVera مترجم بالكامل. يمكنك تغيير تفضيل اللغة الخاص بك بشكل دائم باستخدام المبدل التفاعلي أو اختصار مباشر:

- **المبدل التفاعلي:** `voxvera lang`
- **اختصار مباشر:** `voxvera --lang ar` (يضبط التفضيل على العربية)

### اللغات المدعومة:
- **الإنجليزية:** `en`
- **الإسبانية:** `es` (اسم مستعار: `--idioma`)
- **الألمانية:** `de` (اسم مستعار: `--sprache`)
- **العربية:** `ar`

يمكنك أيضاً فرض لغة معينة لأمر واحد دون تغيير تفضيلك الدائم:
- **الإنجليزية:** `voxvera --lang en check`
- **العربية:** `voxvera --lang ar check`

تكتشف المنشورات الناتجة تلقائياً لغة متصفح الزائر وتبدل نص واجهة المستخدم وفقاً لذلك.

## إدارة الخوادم

إدارة منشورات متعددة وهويات Tor الخاصة بها من قائمة تفاعلية واحدة:

```bash
voxvera manage
```

الميزات:
- **--- إنشاء موقع/منشور جديد ---**: ابدأ تسلسل الإعداد الكامل.
- **--- تشغيل جميع المواقع ---**: تشغيل أو إيقاف جميع المنشورات في أسطولك دفعة واحدة.
- **الحالة في الوقت الفعلي**: عرض روابط .onion النشطة ومؤشرات تقدم تمهيد Tor.
- **التحكم الفردي**: تصدير إلى Zip مواقع معينة إلى ZIP أو حذفها.

## مراجة شاملة (التوزيع الفيروسي)

لضمان بقاء VoxVera متاحاً حتى لو تم فرض رقابة على المستودعات المركزية، يعمل كل منشور كمرآة للأداة.

عندما تستضيف منشوراً، يوفر زر **"تحميل الأداة والكود"** في الصفحة المقصودة ملف `voxvera-portable.zip` يحتوي على:
- كود المصدر الكامل وجميع اللغات المدعومة.
- جميع تبعيات Python (مضمنة مسبقاً).
- ملفات Tor الثنائية لجميع الأنظمة.

يتيح ذلك لأي شخص يقوم بمسح منشورك أن يصبح موزعاً جديداً لأداة VoxVera.

## التصدير والنسخ الاحتياطي

قم بنسخ هويات Tor الفريدة الخاصة بك احتياطياً (حتى لا يتغير رابط .onion الخاص بك أبداً) أو انقل منشوراتك إلى جهاز آخر.

- **تصدير موقع واحد**: `voxvera export <folder_name>`
- **تصدير جميع المواقع**: `voxvera export-all`

**مكان التخزين:** يتم حفظ جميع الصادرات كملفات ZIP في مجلد يسمى `voxvera-exports` في دليل الصفحة الرئيسية للمستخدم (`~/voxvera-exports/`) على جميع الأنظمة.

## الاستيراد والاستعادة

استعد إعدادك بالكامل على جهاز جديد بنقل ملفات ZIP الخاصة بك إلى `~/voxvera-exports/` وتشغيل:

```bash
voxvera import-multiple
```

## النقل والتشغيل بدون إنترنت

إذا كنت بحاجة إلى تشغيل VoxVera على جهاز لا يتوفر فيه اتصال بالإنترنت، يمكنك "تضمين" التبعيات أولاً:

```bash
voxvera vendorize
```

يقوم هذا بتنزيل جميع مكتبات Python المطلوبة في `voxvera/vendor/`. ستعطي الأداة بعد ذلك الأولوية لهذه الملفات المحلية، مما يسمح لها بالعمل بدون `pip install`.

## استيراد جماعي (JSON)

لإنشاء منشورات بشكل جماعي من ملفات تكوين JSON متعددة، ضعها في مجلد `imports/` وشغل:

```bash
voxvera batch-import
```

## كيف تعمل الروابط

يحتوي كل منشور على رابطين منفصلين:
- **رابط قابل للنزع** (يتم إنشاؤه تلقائياً): عنوان .onion حيث يتم استضافة المنشور.
- **رابط المحتوى** (يتم تكوينه بواسطة المستخدم): URL خارجي يشير إلى موقع ويب أو فيديو أو تنزيل.

لا تحتاج إلى إدخال عنوان .onion يدوياً؛ يتولى VoxVera ذلك تلقائياً خلال مرحلة `serve`.