mirror of
https://github.com/PR0M3TH3AN/VoxVera.git
synced 2026-10-27 09:40:40 +00:00
feat: Final global expansion to 14 languages including Portuguese, Chinese, Farsi, and Turkish
This commit is contained in:
thePR0M3TH3AN committed
1 parent
768b615317
commit
4e0bc20f88
35 files changed
+2103
-3
No files matched your search
@@ -0,0 +1,41 @@
|
||||
# AI Agent Instructions for VoxVera
|
||||
|
||||
This guide is for AI agents (like Gemini, Claude, or GPT) contributing to the VoxVera project. Follow these protocols to maintain the architectural integrity and multi-language support.
|
||||
|
||||
## Core Mandates
|
||||
|
||||
1. **Security-First**: VoxVera is a Tor-based tool. Never suggest features that leak IP addresses or use non-Tor external resources (CDNs, etc.).
|
||||
2. **Local-First**: All assets (fonts, dependencies, binaries) must be self-contained within the `voxvera/` package to support the Universal Mirroring model.
|
||||
3. **Tokenized UI**: Never hardcode user-facing strings. Always add them to `voxvera/locales/en.json` and use the `t('cli.token')` helper.
|
||||
4. **Markdown Redaction**: Use `~~text~~` in locale JSONs for strike-through effects. Both the build system and the JS engine handle the conversion to `<span class="redacted">` automatically.
|
||||
|
||||
## Localization Protocol
|
||||
|
||||
When adding a new language or updating an existing one:
|
||||
- **CLI/Flyers**: Update `voxvera/locales/{lang}.json`. Include `meta`, `cli`, `web`, and `landing` categories.
|
||||
- **Landing Page**:
|
||||
- Directly update the `const locales` object in `site/index.html`.
|
||||
- **Crucial**: Run `voxvera build-site` to generate the latest portable bundle and refresh the pre-rendered HTML.
|
||||
- **Documentation**:
|
||||
- Master templates live in `docs/templates/`.
|
||||
- Localized overrides live in `voxvera/locales/{lang}/docs/`.
|
||||
- **Crucial**: After any change to locales or templates, you MUST run `voxvera build-docs` to synchronize the output in `docs/{en,es,de}/`.
|
||||
|
||||
## Universal Mirroring
|
||||
|
||||
VoxVera propagates through its own flyers.
|
||||
- Every `voxvera build` and `voxvera build-site` generates `voxvera-portable.zip`.
|
||||
- If you modify the core source code, ensure the `bundle_portable` function in `voxvera/cli.py` still correctly captures all necessary directories (especially `vendor/`, `locales/`, and `resources/`).
|
||||
|
||||
## Verification Checklist
|
||||
|
||||
Before finishing a task, ensure you have:
|
||||
1. Run unit tests: `pytest tests/test_cli.py`.
|
||||
2. Verified the localization: `voxvera --lang {lang} check`.
|
||||
3. Rebuilt the documentation: `voxvera build-docs`.
|
||||
4. Synchronized the public site: `voxvera build-site`.
|
||||
5. Verified the portable bundle exists: `ls -l voxvera/host/*/download/voxvera-portable.zip` and `ls -l site/download/voxvera-portable.zip`.
|
||||
|
||||
---
|
||||
|
||||
Follow these rules to ensure VoxVera remains a robust, viral, and decentralized tool for truth.
|
||||
@@ -0,0 +1,42 @@
|
||||
# Contributing to VoxVera
|
||||
|
||||
Thank you for your interest in contributing to VoxVera! This project aims to be a global, censorship-resistant tool, and your help—especially with translations—is vital.
|
||||
|
||||
## Adding a New Language
|
||||
|
||||
VoxVera uses a centralized token system for the CLI and Web components, and a template-based system for Documentation. To add a new language (e.g., French/`fr`), follow this checklist:
|
||||
|
||||
### 1. The Token File
|
||||
Create a new JSON file in `voxvera/locales/{lang_code}.json`.
|
||||
- Use `en.json` as your master template.
|
||||
- **`meta`**: Include the native language name and a flag emoji.
|
||||
- **`cli`**: Translate all strings used in the terminal interface.
|
||||
- **`web`**: Translate strings used on the generated landing pages and flyers.
|
||||
- **`landing`**: Translate the specific content for the official VoxVera website.
|
||||
- **Formatting**: You can use Markdown-style strike-throughs (`~~redacted text~~`) in any of these strings; they will be automatically converted to the stylized "redacted" effect on the flyers.
|
||||
|
||||
### 2. The Landing Page
|
||||
The main landing page (`site/index.html`) must be synchronized to include your new language.
|
||||
- Open `site/index.html` and add your language to the `const locales` object in the `<script>` tag.
|
||||
- Run `voxvera build-site` to refresh the public assets and ensure the pre-rendered HTML matches your new locale.
|
||||
|
||||
### 3. Documentation
|
||||
VoxVera uses the **Doc-Sync Engine** to keep manuals in sync.
|
||||
- Create localized Markdown files in `voxvera/locales/{lang_code}/docs/`.
|
||||
- Use the templates in `docs/templates/` as your guide.
|
||||
- You can use `cli.token_name` to reference terminal commands automatically.
|
||||
|
||||
### 4. Build and Verify
|
||||
Run the following commands to verify your changes:
|
||||
- `voxvera --lang {lang_code} check` (Verify CLI translation)
|
||||
- `voxvera build-docs` (Generate localized manuals)
|
||||
- Open `site/index.html` in a browser and test the language switcher.
|
||||
|
||||
## Code Contributions
|
||||
- Ensure all tests pass: `pytest tests/test_cli.py`.
|
||||
- Follow the existing coding style (PEP 8 for Python).
|
||||
- If adding a new feature, update the master templates in `docs/templates/` and run `voxvera build-docs`.
|
||||
|
||||
---
|
||||
|
||||
Together, we can ensure that truth remains accessible to everyone, everywhere.
|
||||
@@ -0,0 +1,16 @@
|
||||
# Docker Usage
|
||||
|
||||
A prebuilt image containing Tor, OnionShare and the `voxvera` CLI is published to
|
||||
`ghcr.io/voxvera/voxvera`.
|
||||
|
||||
```bash
|
||||
# pull the image
|
||||
docker pull ghcr.io/voxvera/voxvera:latest
|
||||
|
||||
# run voxvera quickstart with flyers stored in ./flyers
|
||||
mkdir -p flyers
|
||||
docker run -it --rm -v "$(pwd)/flyers:/flyers" ghcr.io/voxvera/voxvera
|
||||
```
|
||||
|
||||
The container uses `/flyers` as the working directory and runs `voxvera quickstart`
|
||||
by default. All generated flyer files will appear in the mounted `flyers` folder.
|
||||
@@ -0,0 +1,14 @@
|
||||
# Flyer Templates
|
||||
|
||||
Pre-built flyer templates live in the `templates/` directory. Use the CLI to copy one with:
|
||||
|
||||
```bash
|
||||
voxvera init --template <name>
|
||||
```
|
||||
|
||||
This will create a new folder under `dist/` named `<name>-<YYYYMMDD>` containing the template files.
|
||||
|
||||
Available templates:
|
||||
|
||||
- **blank** – minimal placeholder files, also used when extracting fields from a PDF.
|
||||
- **voxvera** – example flyer showcasing the VoxVera project.
|
||||
@@ -0,0 +1,60 @@
|
||||
# Troubleshooting
|
||||
|
||||
This page collects common issues encountered when hosting or accessing flyers.
|
||||
|
||||
## Tor connectivity
|
||||
- Ensure Tor is allowed through your firewall. On systems using `ufw` you may need to run `sudo ufw allow tor`.
|
||||
- Some networks block Tor entirely. If you cannot reach onion services, try connecting over a different network or use a Tor bridge.
|
||||
|
||||
## Tor port detection
|
||||
|
||||
`voxvera serve` auto-detects Tor by probing common ports (9050/9150 for SOCKS, 9051/9151 for control). If detection fails -- for example when Tor runs on non-standard ports -- you can override with environment variables:
|
||||
|
||||
```bash
|
||||
TOR_SOCKS_PORT=19050 TOR_CONTROL_PORT=19051 voxvera serve
|
||||
```
|
||||
|
||||
If no running Tor is found, the defaults (9050/9051) are used and OnionShare will attempt to connect on those ports.
|
||||
|
||||
## Firewall rules
|
||||
- If `voxvera serve` fails to start OnionShare, verify that outbound connections on ports 9001 and 80 are permitted.
|
||||
- Corporate or university firewalls can block the hidden service ports required by Tor.
|
||||
|
||||
## SELinux
|
||||
- On SELinux-enabled distributions you may see `permission denied` errors when OnionShare writes to the `host` directory.
|
||||
- Run `sudo chcon -Rt svirt_sandbox_file_t host` or disable SELinux enforcement for the folder.
|
||||
|
||||
## OnionShare crashes
|
||||
If `voxvera serve` prints "OnionShare exited unexpectedly", check the log file
|
||||
`host/<folder_name>/onionshare.log` for details. Common causes:
|
||||
|
||||
- Tor is not running (`sudo systemctl start tor`)
|
||||
- A port conflict with another service
|
||||
- Missing `onionshare-cli` (run `voxvera check`)
|
||||
|
||||
## Onion URL changed unexpectedly
|
||||
The onion URL is tied to the Ed25519 keypair stored in
|
||||
`host/<folder_name>/.onionshare-session`. If this file is deleted, a new
|
||||
keypair (and URL) will be generated on the next `voxvera serve`. The
|
||||
`voxvera import` command preserves this file automatically, but manual
|
||||
deletion of the `host/` directory will destroy it.
|
||||
|
||||
## QR codes not generated
|
||||
If `voxvera build` reports "No URLs configured yet", this is expected before the first `voxvera serve`. QR codes for tear-off links are generated automatically once the .onion address is known. QR codes for the content link are generated if you provided a URL during `voxvera init`.
|
||||
|
||||
## Electron GUI
|
||||
If `npm start` fails with `spawn voxvera ENOENT`, the `voxvera` command is not in your `PATH`. Install it with `pipx install git+https://github.com/PR0M3TH3AN/VoxVera.git` or run `./install.sh` from the repository.
|
||||
|
||||
## Missing dependencies
|
||||
Run `voxvera check` to verify your setup. The command checks for required
|
||||
Python packages (`qrcode`, `Pillow`, `jsmin`, `htmlmin`, `pypdf`) and
|
||||
external tools (`onionshare-cli`), then prints a summary of anything
|
||||
missing. To install everything:
|
||||
|
||||
```bash
|
||||
# Recommended: use the install script (handles Tor + OnionShare too)
|
||||
curl -fsSL https://raw.githubusercontent.com/PR0M3TH3AN/VoxVera/main/install.sh | bash
|
||||
|
||||
# Or reinstall just the Python package
|
||||
pipx install --force 'voxvera@git+https://github.com/PR0M3TH3AN/VoxVera.git@main'
|
||||
```
|
||||
@@ -0,0 +1,130 @@
|
||||
# راهنمای استفاده تفصیلی
|
||||
|
||||
این راهنما جریانهای کاری معمول رابط سطر فرمان (CLI) را پوشش میدهد. برای دستورالعملهای داکر به `docs/docker.md` و برای قالبهای اعلامیه موجود به `docs/templates.md` مراجعه کنید.
|
||||
|
||||
## پیشنیازها
|
||||
|
||||
ووکسورا (VoxVera) به گونهای طراحی شده است که بسیار قابل حمل باشد و به حداقل وابستگیهای سیستم نیاز داشته باشد.
|
||||
|
||||
### ۱. فایلهای اجرایی مستقل (توصیه شده)
|
||||
میتوانید فایلهای اجرایی (Binary) مستقل و بدون نیاز به وابستگی را برای سیستمعامل خود دانلود کنید:
|
||||
- **لینوکس:** `voxvera-linux`
|
||||
- **ویندوز:** `voxvera-windows.exe`
|
||||
- **مک:** `voxvera-macos`
|
||||
|
||||
این فایلها شامل تمام موارد لازم برای اجرای ووکسورا هستند (به جز `onionshare-cli`).
|
||||
|
||||
### ۲. نصبکننده تکخطی
|
||||
همچنین میتوانید از طریق اسکریپت خودکار ما نصب را انجام دهید:
|
||||
|
||||
```bash
|
||||
curl -fsSL https://raw.githubusercontent.com/PR0M3TH3AN/VoxVera/main/install.sh | bash
|
||||
```
|
||||
|
||||
### ۳. نصب دستی پایتون
|
||||
اگر ترجیح میدهید از سورس کد استفاده کنید:
|
||||
|
||||
```bash
|
||||
pipx install 'voxvera@git+https://github.com/PR0M3TH3AN/VoxVera.git@main'
|
||||
sudo apt install tor onionshare-cli # دبیان/اوبونتو
|
||||
```
|
||||
|
||||
## گام به گام
|
||||
|
||||
۱. **راهاندازی:** دستور `voxvera init` را اجرا کرده و مراحل را دنبال کنید. در ابتدا از شما خواسته میشود زبان خود را انتخاب کنید.
|
||||
۲. **ساخت:** داراییهای اعلامیه را ایجاد کنید. هر بار که عملیات ساخت انجام میشود، یک فایل `voxvera-portable.zip` به طور خودکار در پوشه اعلامیه ساخته میشود که به دیگران اجازه میدهد ابزار کامل را مستقیماً از اعلامیه شما دانلود کنند.
|
||||
```bash
|
||||
voxvera build
|
||||
```
|
||||
۳. **میزبانی:** اعلامیه را روی شبکه تور منتشر کنید:
|
||||
```bash
|
||||
voxvera serve
|
||||
```
|
||||
این دستور به طور خودکار تور شما را شناسایی کرده، OnionShare را راهاندازی میکند و آدرس .onion تولید شده را در پیوندهای جداشونده اعلامیه مینویسد.
|
||||
|
||||
## پشتیبانی از زبانها
|
||||
|
||||
ووکسورا کاملاً بومیسازی شده است. میتوانید اولویت زبان خود را به طور دائم با استفاده از انتخابگر تعاملی یا میانبر مستقیم تغییر دهید:
|
||||
|
||||
- **انتخابگر تعاملی:** `voxvera lang`
|
||||
- **میانبر مستقیم:** `voxvera --lang fa` (تنظیم اولویت روی فارسی)
|
||||
|
||||
### زبانهای پشتیبانی شده:
|
||||
- **انگلیسی:** `en`
|
||||
- **اسپانیایی:** `es` (نام مستعار: `--idioma`)
|
||||
- **آلمانی:** `de` (نام مستعار: `--sprache`)
|
||||
- **فارسی:** `fa`
|
||||
|
||||
همچنین میتوانید بدون تغییر اولویت دائمی، یک زبان خاص را برای یک دستور واحد اجبار کنید:
|
||||
- **انگلیسی:** `voxvera --lang en check`
|
||||
- **فارسی:** `voxvera --lang fa check`
|
||||
|
||||
اعلامیههای تولید شده به طور خودکار زبان مرورگر بازدیدکننده را تشخیص داده و متن رابط کاربری را بر اساس آن تغییر میدهند.
|
||||
|
||||
## مدیریت سرورها
|
||||
|
||||
چندین اعلامیه و هویتهای تور آنها را از یک منوی تعاملی واحد مدیریت کنید:
|
||||
|
||||
```bash
|
||||
voxvera manage
|
||||
```
|
||||
|
||||
ویژگیها:
|
||||
- **--- ایجاد سایت/اعلامیه جدید ---**: شروع توالی کامل تنظیمات.
|
||||
- **--- اجرای همه سایتها ---**: راهاندازی یا توقف همزمان تمام اعلامیههای شما.
|
||||
- **وضعیت لحظهای**: مشاهده آدرسهای .onion فعال و نشانگرهای پیشرفت تور.
|
||||
- **کنترل فردی**: صدور به صورت زیپ سایتهای خاص به فرمت ZIP یا حذف آنها.
|
||||
|
||||
## آینهسازی همگانی (توزیع ویروسی)
|
||||
|
||||
برای اطمینان از اینکه ووکسورا حتی در صورت سانسور مخازن مرکزی در دسترس باقی میماند، هر اعلامیه به عنوان یک آینه برای این ابزار عمل میکند.
|
||||
|
||||
وقتی اعلامیهای را میزبانی میکنید، دکمه **"دانلود ابزار و کد منبع"** در صفحه فرود، یک فایل `voxvera-portable.zip` شامل موارد زیر ارائه میدهد:
|
||||
- سورس کد کامل و تمامی زبانهای پشتیبانی شده.
|
||||
- تمامی وابستگیهای پایتون (از پیش بستهبندی شده).
|
||||
- فایلهای اجرایی تور برای تمامی پلتفرمها.
|
||||
|
||||
این کار به هر کسی که اعلامیه شما را اسکن میکند اجازه میدهد تا به توزیعکننده جدیدی برای ابزار ووکسورا تبدیل شود.
|
||||
|
||||
## صدور و پشتیبانگیری
|
||||
|
||||
از هویتهای تور منحصر به فرد خود پشتیبان بگیرید (تا آدرس .onion شما هرگز تغییر نکند) یا اعلامیههای خود را به سیستم دیگری منتقل کنید.
|
||||
|
||||
- **صدور یک سایت واحد:** `voxvera export <folder_name>`
|
||||
- **صدور تمامی سایتها:** `voxvera export-all`
|
||||
|
||||
**محل ذخیرهسازی:** تمامی موارد صادر شده به صورت فایل ZIP در پوشهای به نام `voxvera-exports` در پوشه خانگی کاربر (`~/voxvera-exports/`) در تمامی پلتفرمها ذخیره میشوند.
|
||||
|
||||
## وارد کردن و بازیابی
|
||||
|
||||
با انتقال فایلهای ZIP خود به پوشه `~/voxvera-exports/` و اجرای دستور زیر، کل تنظیمات خود را در یک سیستم جدید بازیابی کنید:
|
||||
|
||||
```bash
|
||||
voxvera import-multiple
|
||||
```
|
||||
|
||||
## قابلیت حمل و استفاده آفلاین
|
||||
|
||||
اگر نیاز دارید ووکسورا را روی سیستمی بدون دسترسی به اینترنت اجرا کنید، میتوانید ابتدا وابستگیها را به صورت محلی ذخیره کنید:
|
||||
|
||||
```bash
|
||||
voxvera vendorize
|
||||
```
|
||||
|
||||
این دستور تمامی کتابخانههای پایتون مورد نیاز را در پوشه `voxvera/vendor/` دانلود میکند. ابزار سپس این فایلهای محلی را در اولویت قرار میدهد و اجازه میدهد بدون نیاز به `pip install` اجرا شود.
|
||||
|
||||
## وارد کردن گروهی (JSON)
|
||||
|
||||
برای تولید انبوه اعلامیهها از چندین فایل تنظیمات JSON، آنها را در پوشه `imports/` قرار داده و اجرا کنید:
|
||||
|
||||
```bash
|
||||
voxvera batch-import
|
||||
```
|
||||
|
||||
## آدرسهای URL چگونه کار میکنند
|
||||
|
||||
هر اعلامیه دارای دو آدرس URL جداگانه است:
|
||||
- **پیوند جداشونده** (تولید خودکار): آدرس .onion که اعلامیه در آن میزبانی میشود.
|
||||
- **پیوند محتوا** (تنظیم توسط کاربر): یک آدرس URL خارجی که به یک وبسایت، ویدیو یا فایل دانلود اشاره میکند.
|
||||
|
||||
نیازی نیست آدرس .onion را به صورت دستی وارد کنید؛ ووکسورا در مرحله میزبانی (`serve`) این کار را به طور خودکار انجام میدهد.
|
||||
@@ -0,0 +1,41 @@
|
||||
# AI Agent Instructions for VoxVera
|
||||
|
||||
This guide is for AI agents (like Gemini, Claude, or GPT) contributing to the VoxVera project. Follow these protocols to maintain the architectural integrity and multi-language support.
|
||||
|
||||
## Core Mandates
|
||||
|
||||
1. **Security-First**: VoxVera is a Tor-based tool. Never suggest features that leak IP addresses or use non-Tor external resources (CDNs, etc.).
|
||||
2. **Local-First**: All assets (fonts, dependencies, binaries) must be self-contained within the `voxvera/` package to support the Universal Mirroring model.
|
||||
3. **Tokenized UI**: Never hardcode user-facing strings. Always add them to `voxvera/locales/en.json` and use the `t('cli.token')` helper.
|
||||
4. **Markdown Redaction**: Use `~~text~~` in locale JSONs for strike-through effects. Both the build system and the JS engine handle the conversion to `<span class="redacted">` automatically.
|
||||
|
||||
## Localization Protocol
|
||||
|
||||
When adding a new language or updating an existing one:
|
||||
- **CLI/Flyers**: Update `voxvera/locales/{lang}.json`. Include `meta`, `cli`, `web`, and `landing` categories.
|
||||
- **Landing Page**:
|
||||
- Directly update the `const locales` object in `site/index.html`.
|
||||
- **Crucial**: Run `voxvera build-site` to generate the latest portable bundle and refresh the pre-rendered HTML.
|
||||
- **Documentation**:
|
||||
- Master templates live in `docs/templates/`.
|
||||
- Localized overrides live in `voxvera/locales/{lang}/docs/`.
|
||||
- **Crucial**: After any change to locales or templates, you MUST run `voxvera build-docs` to synchronize the output in `docs/{en,es,de}/`.
|
||||
|
||||
## Universal Mirroring
|
||||
|
||||
VoxVera propagates through its own flyers.
|
||||
- Every `voxvera build` and `voxvera build-site` generates `voxvera-portable.zip`.
|
||||
- If you modify the core source code, ensure the `bundle_portable` function in `voxvera/cli.py` still correctly captures all necessary directories (especially `vendor/`, `locales/`, and `resources/`).
|
||||
|
||||
## Verification Checklist
|
||||
|
||||
Before finishing a task, ensure you have:
|
||||
1. Run unit tests: `pytest tests/test_cli.py`.
|
||||
2. Verified the localization: `voxvera --lang {lang} check`.
|
||||
3. Rebuilt the documentation: `voxvera build-docs`.
|
||||
4. Synchronized the public site: `voxvera build-site`.
|
||||
5. Verified the portable bundle exists: `ls -l voxvera/host/*/download/voxvera-portable.zip` and `ls -l site/download/voxvera-portable.zip`.
|
||||
|
||||
---
|
||||
|
||||
Follow these rules to ensure VoxVera remains a robust, viral, and decentralized tool for truth.
|
||||
@@ -0,0 +1,42 @@
|
||||
# Contributing to VoxVera
|
||||
|
||||
Thank you for your interest in contributing to VoxVera! This project aims to be a global, censorship-resistant tool, and your help—especially with translations—is vital.
|
||||
|
||||
## Adding a New Language
|
||||
|
||||
VoxVera uses a centralized token system for the CLI and Web components, and a template-based system for Documentation. To add a new language (e.g., French/`fr`), follow this checklist:
|
||||
|
||||
### 1. The Token File
|
||||
Create a new JSON file in `voxvera/locales/{lang_code}.json`.
|
||||
- Use `en.json` as your master template.
|
||||
- **`meta`**: Include the native language name and a flag emoji.
|
||||
- **`cli`**: Translate all strings used in the terminal interface.
|
||||
- **`web`**: Translate strings used on the generated landing pages and flyers.
|
||||
- **`landing`**: Translate the specific content for the official VoxVera website.
|
||||
- **Formatting**: You can use Markdown-style strike-throughs (`~~redacted text~~`) in any of these strings; they will be automatically converted to the stylized "redacted" effect on the flyers.
|
||||
|
||||
### 2. The Landing Page
|
||||
The main landing page (`site/index.html`) must be synchronized to include your new language.
|
||||
- Open `site/index.html` and add your language to the `const locales` object in the `<script>` tag.
|
||||
- Run `voxvera build-site` to refresh the public assets and ensure the pre-rendered HTML matches your new locale.
|
||||
|
||||
### 3. Documentation
|
||||
VoxVera uses the **Doc-Sync Engine** to keep manuals in sync.
|
||||
- Create localized Markdown files in `voxvera/locales/{lang_code}/docs/`.
|
||||
- Use the templates in `docs/templates/` as your guide.
|
||||
- You can use `cli.token_name` to reference terminal commands automatically.
|
||||
|
||||
### 4. Build and Verify
|
||||
Run the following commands to verify your changes:
|
||||
- `voxvera --lang {lang_code} check` (Verify CLI translation)
|
||||
- `voxvera build-docs` (Generate localized manuals)
|
||||
- Open `site/index.html` in a browser and test the language switcher.
|
||||
|
||||
## Code Contributions
|
||||
- Ensure all tests pass: `pytest tests/test_cli.py`.
|
||||
- Follow the existing coding style (PEP 8 for Python).
|
||||
- If adding a new feature, update the master templates in `docs/templates/` and run `voxvera build-docs`.
|
||||
|
||||
---
|
||||
|
||||
Together, we can ensure that truth remains accessible to everyone, everywhere.
|
||||
@@ -0,0 +1,16 @@
|
||||
# Docker Usage
|
||||
|
||||
A prebuilt image containing Tor, OnionShare and the `voxvera` CLI is published to
|
||||
`ghcr.io/voxvera/voxvera`.
|
||||
|
||||
```bash
|
||||
# pull the image
|
||||
docker pull ghcr.io/voxvera/voxvera:latest
|
||||
|
||||
# run voxvera quickstart with flyers stored in ./flyers
|
||||
mkdir -p flyers
|
||||
docker run -it --rm -v "$(pwd)/flyers:/flyers" ghcr.io/voxvera/voxvera
|
||||
```
|
||||
|
||||
The container uses `/flyers` as the working directory and runs `voxvera quickstart`
|
||||
by default. All generated flyer files will appear in the mounted `flyers` folder.
|
||||
@@ -0,0 +1,14 @@
|
||||
# Flyer Templates
|
||||
|
||||
Pre-built flyer templates live in the `templates/` directory. Use the CLI to copy one with:
|
||||
|
||||
```bash
|
||||
voxvera init --template <name>
|
||||
```
|
||||
|
||||
This will create a new folder under `dist/` named `<name>-<YYYYMMDD>` containing the template files.
|
||||
|
||||
Available templates:
|
||||
|
||||
- **blank** – minimal placeholder files, also used when extracting fields from a PDF.
|
||||
- **voxvera** – example flyer showcasing the VoxVera project.
|
||||
@@ -0,0 +1,60 @@
|
||||
# Troubleshooting
|
||||
|
||||
This page collects common issues encountered when hosting or accessing flyers.
|
||||
|
||||
## Tor connectivity
|
||||
- Ensure Tor is allowed through your firewall. On systems using `ufw` you may need to run `sudo ufw allow tor`.
|
||||
- Some networks block Tor entirely. If you cannot reach onion services, try connecting over a different network or use a Tor bridge.
|
||||
|
||||
## Tor port detection
|
||||
|
||||
`voxvera serve` auto-detects Tor by probing common ports (9050/9150 for SOCKS, 9051/9151 for control). If detection fails -- for example when Tor runs on non-standard ports -- you can override with environment variables:
|
||||
|
||||
```bash
|
||||
TOR_SOCKS_PORT=19050 TOR_CONTROL_PORT=19051 voxvera serve
|
||||
```
|
||||
|
||||
If no running Tor is found, the defaults (9050/9051) are used and OnionShare will attempt to connect on those ports.
|
||||
|
||||
## Firewall rules
|
||||
- If `voxvera serve` fails to start OnionShare, verify that outbound connections on ports 9001 and 80 are permitted.
|
||||
- Corporate or university firewalls can block the hidden service ports required by Tor.
|
||||
|
||||
## SELinux
|
||||
- On SELinux-enabled distributions you may see `permission denied` errors when OnionShare writes to the `host` directory.
|
||||
- Run `sudo chcon -Rt svirt_sandbox_file_t host` or disable SELinux enforcement for the folder.
|
||||
|
||||
## OnionShare crashes
|
||||
If `voxvera serve` prints "OnionShare exited unexpectedly", check the log file
|
||||
`host/<folder_name>/onionshare.log` for details. Common causes:
|
||||
|
||||
- Tor is not running (`sudo systemctl start tor`)
|
||||
- A port conflict with another service
|
||||
- Missing `onionshare-cli` (run `voxvera check`)
|
||||
|
||||
## Onion URL changed unexpectedly
|
||||
The onion URL is tied to the Ed25519 keypair stored in
|
||||
`host/<folder_name>/.onionshare-session`. If this file is deleted, a new
|
||||
keypair (and URL) will be generated on the next `voxvera serve`. The
|
||||
`voxvera import` command preserves this file automatically, but manual
|
||||
deletion of the `host/` directory will destroy it.
|
||||
|
||||
## QR codes not generated
|
||||
If `voxvera build` reports "No URLs configured yet", this is expected before the first `voxvera serve`. QR codes for tear-off links are generated automatically once the .onion address is known. QR codes for the content link are generated if you provided a URL during `voxvera init`.
|
||||
|
||||
## Electron GUI
|
||||
If `npm start` fails with `spawn voxvera ENOENT`, the `voxvera` command is not in your `PATH`. Install it with `pipx install git+https://github.com/PR0M3TH3AN/VoxVera.git` or run `./install.sh` from the repository.
|
||||
|
||||
## Missing dependencies
|
||||
Run `voxvera check` to verify your setup. The command checks for required
|
||||
Python packages (`qrcode`, `Pillow`, `jsmin`, `htmlmin`, `pypdf`) and
|
||||
external tools (`onionshare-cli`), then prints a summary of anything
|
||||
missing. To install everything:
|
||||
|
||||
```bash
|
||||
# Recommended: use the install script (handles Tor + OnionShare too)
|
||||
curl -fsSL https://raw.githubusercontent.com/PR0M3TH3AN/VoxVera/main/install.sh | bash
|
||||
|
||||
# Or reinstall just the Python package
|
||||
pipx install --force 'voxvera@git+https://github.com/PR0M3TH3AN/VoxVera.git@main'
|
||||
```
|
||||
@@ -0,0 +1,130 @@
|
||||
# Uso Detalhado
|
||||
|
||||
Este guia cobre os fluxos de trabalho comuns da CLI. Veja `docs/docker.md` para instruções do Docker e `docs/templates.md` para modelos de panfletos disponíveis.
|
||||
|
||||
## Pré-requisitos
|
||||
|
||||
O VoxVera foi projetado para ser altamente portátil e requer dependências mínimas do sistema.
|
||||
|
||||
### 1. Binários Independentes (Recomendado)
|
||||
Você pode baixar binários independentes e sem dependências para o seu sistema operacional:
|
||||
- **Linux:** `voxvera-linux`
|
||||
- **Windows:** `voxvera-windows.exe`
|
||||
- **macOS:** `voxvera-macos`
|
||||
|
||||
Estes binários incluem tudo o que é necessário para executar o VoxVera (exceto o `onionshare-cli`).
|
||||
|
||||
### 2. Instalador de Linha Única
|
||||
Alternativamente, instale através do nosso script automatizado:
|
||||
|
||||
```bash
|
||||
curl -fsSL https://raw.githubusercontent.com/PR0M3TH3AN/VoxVera/main/install.sh | bash
|
||||
```
|
||||
|
||||
### 3. Instalação Manual via Python
|
||||
Se preferir executar a partir do código-fonte:
|
||||
|
||||
```bash
|
||||
pipx install 'voxvera@git+https://github.com/PR0M3TH3AN/VoxVera.git@main'
|
||||
sudo apt install tor onionshare-cli # Debian/Ubuntu
|
||||
```
|
||||
|
||||
## Passo a Passo
|
||||
|
||||
1. **Inicializar:** Execute `voxvera init` e siga as instruções. Você será solicitado a selecionar seu idioma primeiro.
|
||||
2. **Construir:** Gere os arquivos do panfleto. Cada construção cria automaticamente um `voxvera-portable.zip` na pasta do panfleto, permitindo que outros baixem a ferramenta completa diretamente do seu panfleto.
|
||||
```bash
|
||||
voxvera build
|
||||
```
|
||||
3. **Servir:** Publique o panfleto via Tor:
|
||||
```bash
|
||||
voxvera serve
|
||||
```
|
||||
Isso detecta automaticamente sua instância do Tor, inicia o OnionShare e escreve o endereço .onion gerado nos links destacáveis do panfleto.
|
||||
|
||||
## Suporte a Idiomas
|
||||
|
||||
O VoxVera é totalmente localizado. Você pode alterar sua preferência de idioma permanentemente usando o seletor interativo ou um atalho direto:
|
||||
|
||||
- **Seletor Interativo:** `voxvera lang`
|
||||
- **Atalho Direto:** `voxvera --lang pt` (define a preferência para português)
|
||||
|
||||
### Idiomas Suportados:
|
||||
- **Inglês:** `en`
|
||||
- **Espanhol:** `es` (alias: `--idioma`)
|
||||
- **Alemão:** `de` (alias: `--sprache`)
|
||||
- **Português:** `pt`
|
||||
|
||||
Você também pode forçar um idioma específico para um único comando sem alterar sua preferência permanente:
|
||||
- **Inglês:** `voxvera --lang en check`
|
||||
- **Português:** `voxvera --lang pt check`
|
||||
|
||||
Os panfletos gerados detectam automaticamente o idioma do navegador do visitante e alteram o texto da interface adequadamente.
|
||||
|
||||
## Gerenciamento de Servidores
|
||||
|
||||
Gerencie vários panfletos e suas identidades Tor a partir de um único menu interativo:
|
||||
|
||||
```bash
|
||||
voxvera manage
|
||||
```
|
||||
|
||||
Recursos:
|
||||
- **--- Criar Novo Site/Panfleto ---**: Inicia a sequência completa de configuração.
|
||||
- **--- Iniciar Todos os Sites ---**: Inicia ou encerra todos os panfletos da sua frota de uma só vez.
|
||||
- **Status em Tempo Real**: Visualize URLs .onion ativas e indicadores de progresso de inicialização do Tor.
|
||||
- **Controle Individual**: Exportar para Zip sites específicos para ZIP ou exclua-os.
|
||||
|
||||
## Espelhamento Universal (Distribuição Viral)
|
||||
|
||||
Para garantir que o VoxVera permaneça acessível mesmo se os repositórios centrais forem censurados, cada panfleto atua como um espelho para a ferramenta.
|
||||
|
||||
Quando você hospeda um panfleto, o botão **"Baixar Ferramenta e Código"** na página inicial fornece um `voxvera-portable.zip` contendo:
|
||||
- O código-fonte completo e todos os idiomas suportados.
|
||||
- Todas as dependências Python (pré-vendidas).
|
||||
- Binários Tor multiplataforma.
|
||||
|
||||
Isso permite que qualquer pessoa que escaneie seu panfleto se torne um novo distribuidor da ferramenta VoxVera.
|
||||
|
||||
## Exportação e Backup
|
||||
|
||||
Faça backup de suas identidades Tor exclusivas (para que sua URL .onion nunca mude) ou mova seus panfletos para outra máquina.
|
||||
|
||||
- **Exportar um único site**: `voxvera export <nome_da_pasta>`
|
||||
- **Exportar todos os sites**: `voxvera export-all`
|
||||
|
||||
**Local de armazenamento:** Todas as exportações são salvas como arquivos ZIP em uma pasta chamada `voxvera-exports` no diretório inicial do usuário (`~/voxvera-exports/`) em todas as plataformas.
|
||||
|
||||
## Importação e Recuperação
|
||||
|
||||
Restaure toda a sua configuração em uma nova máquina movendo seus arquivos ZIP para `~/voxvera-exports/` e executando:
|
||||
|
||||
```bash
|
||||
voxvera import-multiple
|
||||
```
|
||||
|
||||
## Portabilidade e Uso Offline
|
||||
|
||||
Se precisar executar o VoxVera em uma máquina sem acesso à internet, você pode "venderizar" as dependências primeiro:
|
||||
|
||||
```bash
|
||||
voxvera vendorize
|
||||
```
|
||||
|
||||
Isso baixa todas as bibliotecas Python necessárias para `voxvera/vendor/`. A ferramenta priorizará esses arquivos locais, permitindo que ela funcione sem `pip install`.
|
||||
|
||||
## Importação em Lote (JSON)
|
||||
|
||||
Para gerar panfletos em massa a partir de vários arquivos de configuração JSON, coloque-os no diretório `imports/` e execute:
|
||||
|
||||
```bash
|
||||
voxvera batch-import
|
||||
```
|
||||
|
||||
## Como as URLs Funcionam
|
||||
|
||||
Cada panfleto tem duas URLs separadas:
|
||||
- **Link destacável** (gerado automaticamente): O endereço .onion onde o panfleto está hospedado.
|
||||
- **Link de conteúdo** (configurado pelo usuário): Uma URL externa apontando para um site, vídeo ou download.
|
||||
|
||||
Você não precisa inserir manualmente o endereço .onion; o VoxVera lida com isso automaticamente durante a fase de `serve`.
|
||||
@@ -0,0 +1,41 @@
|
||||
# AI Agent Instructions for VoxVera
|
||||
|
||||
This guide is for AI agents (like Gemini, Claude, or GPT) contributing to the VoxVera project. Follow these protocols to maintain the architectural integrity and multi-language support.
|
||||
|
||||
## Core Mandates
|
||||
|
||||
1. **Security-First**: VoxVera is a Tor-based tool. Never suggest features that leak IP addresses or use non-Tor external resources (CDNs, etc.).
|
||||
2. **Local-First**: All assets (fonts, dependencies, binaries) must be self-contained within the `voxvera/` package to support the Universal Mirroring model.
|
||||
3. **Tokenized UI**: Never hardcode user-facing strings. Always add them to `voxvera/locales/en.json` and use the `t('cli.token')` helper.
|
||||
4. **Markdown Redaction**: Use `~~text~~` in locale JSONs for strike-through effects. Both the build system and the JS engine handle the conversion to `<span class="redacted">` automatically.
|
||||
|
||||
## Localization Protocol
|
||||
|
||||
When adding a new language or updating an existing one:
|
||||
- **CLI/Flyers**: Update `voxvera/locales/{lang}.json`. Include `meta`, `cli`, `web`, and `landing` categories.
|
||||
- **Landing Page**:
|
||||
- Directly update the `const locales` object in `site/index.html`.
|
||||
- **Crucial**: Run `voxvera build-site` to generate the latest portable bundle and refresh the pre-rendered HTML.
|
||||
- **Documentation**:
|
||||
- Master templates live in `docs/templates/`.
|
||||
- Localized overrides live in `voxvera/locales/{lang}/docs/`.
|
||||
- **Crucial**: After any change to locales or templates, you MUST run `voxvera build-docs` to synchronize the output in `docs/{en,es,de}/`.
|
||||
|
||||
## Universal Mirroring
|
||||
|
||||
VoxVera propagates through its own flyers.
|
||||
- Every `voxvera build` and `voxvera build-site` generates `voxvera-portable.zip`.
|
||||
- If you modify the core source code, ensure the `bundle_portable` function in `voxvera/cli.py` still correctly captures all necessary directories (especially `vendor/`, `locales/`, and `resources/`).
|
||||
|
||||
## Verification Checklist
|
||||
|
||||
Before finishing a task, ensure you have:
|
||||
1. Run unit tests: `pytest tests/test_cli.py`.
|
||||
2. Verified the localization: `voxvera --lang {lang} check`.
|
||||
3. Rebuilt the documentation: `voxvera build-docs`.
|
||||
4. Synchronized the public site: `voxvera build-site`.
|
||||
5. Verified the portable bundle exists: `ls -l voxvera/host/*/download/voxvera-portable.zip` and `ls -l site/download/voxvera-portable.zip`.
|
||||
|
||||
---
|
||||
|
||||
Follow these rules to ensure VoxVera remains a robust, viral, and decentralized tool for truth.
|
||||
@@ -0,0 +1,42 @@
|
||||
# Contributing to VoxVera
|
||||
|
||||
Thank you for your interest in contributing to VoxVera! This project aims to be a global, censorship-resistant tool, and your help—especially with translations—is vital.
|
||||
|
||||
## Adding a New Language
|
||||
|
||||
VoxVera uses a centralized token system for the CLI and Web components, and a template-based system for Documentation. To add a new language (e.g., French/`fr`), follow this checklist:
|
||||
|
||||
### 1. The Token File
|
||||
Create a new JSON file in `voxvera/locales/{lang_code}.json`.
|
||||
- Use `en.json` as your master template.
|
||||
- **`meta`**: Include the native language name and a flag emoji.
|
||||
- **`cli`**: Translate all strings used in the terminal interface.
|
||||
- **`web`**: Translate strings used on the generated landing pages and flyers.
|
||||
- **`landing`**: Translate the specific content for the official VoxVera website.
|
||||
- **Formatting**: You can use Markdown-style strike-throughs (`~~redacted text~~`) in any of these strings; they will be automatically converted to the stylized "redacted" effect on the flyers.
|
||||
|
||||
### 2. The Landing Page
|
||||
The main landing page (`site/index.html`) must be synchronized to include your new language.
|
||||
- Open `site/index.html` and add your language to the `const locales` object in the `<script>` tag.
|
||||
- Run `voxvera build-site` to refresh the public assets and ensure the pre-rendered HTML matches your new locale.
|
||||
|
||||
### 3. Documentation
|
||||
VoxVera uses the **Doc-Sync Engine** to keep manuals in sync.
|
||||
- Create localized Markdown files in `voxvera/locales/{lang_code}/docs/`.
|
||||
- Use the templates in `docs/templates/` as your guide.
|
||||
- You can use `cli.token_name` to reference terminal commands automatically.
|
||||
|
||||
### 4. Build and Verify
|
||||
Run the following commands to verify your changes:
|
||||
- `voxvera --lang {lang_code} check` (Verify CLI translation)
|
||||
- `voxvera build-docs` (Generate localized manuals)
|
||||
- Open `site/index.html` in a browser and test the language switcher.
|
||||
|
||||
## Code Contributions
|
||||
- Ensure all tests pass: `pytest tests/test_cli.py`.
|
||||
- Follow the existing coding style (PEP 8 for Python).
|
||||
- If adding a new feature, update the master templates in `docs/templates/` and run `voxvera build-docs`.
|
||||
|
||||
---
|
||||
|
||||
Together, we can ensure that truth remains accessible to everyone, everywhere.
|
||||
@@ -0,0 +1,16 @@
|
||||
# Docker Usage
|
||||
|
||||
A prebuilt image containing Tor, OnionShare and the `voxvera` CLI is published to
|
||||
`ghcr.io/voxvera/voxvera`.
|
||||
|
||||
```bash
|
||||
# pull the image
|
||||
docker pull ghcr.io/voxvera/voxvera:latest
|
||||
|
||||
# run voxvera quickstart with flyers stored in ./flyers
|
||||
mkdir -p flyers
|
||||
docker run -it --rm -v "$(pwd)/flyers:/flyers" ghcr.io/voxvera/voxvera
|
||||
```
|
||||
|
||||
The container uses `/flyers` as the working directory and runs `voxvera quickstart`
|
||||
by default. All generated flyer files will appear in the mounted `flyers` folder.
|
||||
@@ -0,0 +1,14 @@
|
||||
# Flyer Templates
|
||||
|
||||
Pre-built flyer templates live in the `templates/` directory. Use the CLI to copy one with:
|
||||
|
||||
```bash
|
||||
voxvera init --template <name>
|
||||
```
|
||||
|
||||
This will create a new folder under `dist/` named `<name>-<YYYYMMDD>` containing the template files.
|
||||
|
||||
Available templates:
|
||||
|
||||
- **blank** – minimal placeholder files, also used when extracting fields from a PDF.
|
||||
- **voxvera** – example flyer showcasing the VoxVera project.
|
||||
@@ -0,0 +1,60 @@
|
||||
# Troubleshooting
|
||||
|
||||
This page collects common issues encountered when hosting or accessing flyers.
|
||||
|
||||
## Tor connectivity
|
||||
- Ensure Tor is allowed through your firewall. On systems using `ufw` you may need to run `sudo ufw allow tor`.
|
||||
- Some networks block Tor entirely. If you cannot reach onion services, try connecting over a different network or use a Tor bridge.
|
||||
|
||||
## Tor port detection
|
||||
|
||||
`voxvera serve` auto-detects Tor by probing common ports (9050/9150 for SOCKS, 9051/9151 for control). If detection fails -- for example when Tor runs on non-standard ports -- you can override with environment variables:
|
||||
|
||||
```bash
|
||||
TOR_SOCKS_PORT=19050 TOR_CONTROL_PORT=19051 voxvera serve
|
||||
```
|
||||
|
||||
If no running Tor is found, the defaults (9050/9051) are used and OnionShare will attempt to connect on those ports.
|
||||
|
||||
## Firewall rules
|
||||
- If `voxvera serve` fails to start OnionShare, verify that outbound connections on ports 9001 and 80 are permitted.
|
||||
- Corporate or university firewalls can block the hidden service ports required by Tor.
|
||||
|
||||
## SELinux
|
||||
- On SELinux-enabled distributions you may see `permission denied` errors when OnionShare writes to the `host` directory.
|
||||
- Run `sudo chcon -Rt svirt_sandbox_file_t host` or disable SELinux enforcement for the folder.
|
||||
|
||||
## OnionShare crashes
|
||||
If `voxvera serve` prints "OnionShare exited unexpectedly", check the log file
|
||||
`host/<folder_name>/onionshare.log` for details. Common causes:
|
||||
|
||||
- Tor is not running (`sudo systemctl start tor`)
|
||||
- A port conflict with another service
|
||||
- Missing `onionshare-cli` (run `voxvera check`)
|
||||
|
||||
## Onion URL changed unexpectedly
|
||||
The onion URL is tied to the Ed25519 keypair stored in
|
||||
`host/<folder_name>/.onionshare-session`. If this file is deleted, a new
|
||||
keypair (and URL) will be generated on the next `voxvera serve`. The
|
||||
`voxvera import` command preserves this file automatically, but manual
|
||||
deletion of the `host/` directory will destroy it.
|
||||
|
||||
## QR codes not generated
|
||||
If `voxvera build` reports "No URLs configured yet", this is expected before the first `voxvera serve`. QR codes for tear-off links are generated automatically once the .onion address is known. QR codes for the content link are generated if you provided a URL during `voxvera init`.
|
||||
|
||||
## Electron GUI
|
||||
If `npm start` fails with `spawn voxvera ENOENT`, the `voxvera` command is not in your `PATH`. Install it with `pipx install git+https://github.com/PR0M3TH3AN/VoxVera.git` or run `./install.sh` from the repository.
|
||||
|
||||
## Missing dependencies
|
||||
Run `voxvera check` to verify your setup. The command checks for required
|
||||
Python packages (`qrcode`, `Pillow`, `jsmin`, `htmlmin`, `pypdf`) and
|
||||
external tools (`onionshare-cli`), then prints a summary of anything
|
||||
missing. To install everything:
|
||||
|
||||
```bash
|
||||
# Recommended: use the install script (handles Tor + OnionShare too)
|
||||
curl -fsSL https://raw.githubusercontent.com/PR0M3TH3AN/VoxVera/main/install.sh | bash
|
||||
|
||||
# Or reinstall just the Python package
|
||||
pipx install --force 'voxvera@git+https://github.com/PR0M3TH3AN/VoxVera.git@main'
|
||||
```
|
||||
@@ -0,0 +1,130 @@
|
||||
# Detaylı Kullanım
|
||||
|
||||
Bu kılavuz, yaygın CLI iş akışlarını kapsar. Docker talimatları için `docs/docker.md` ve mevcut ilan şablonları için `docs/templates.md` dosyalarına bakın.
|
||||
|
||||
## Ön Koşullar
|
||||
|
||||
VoxVera, yüksek taşınabilirlik için tasarlanmıştır ve minimum sistem bağımlılığı gerektirir.
|
||||
|
||||
### 1. Bağımsız İkililer (Önerilen)
|
||||
İşletim sisteminiz için bağımsız, bağımlılık gerektirmeyen ikili dosyaları (binaries) indirebilirsiniz:
|
||||
- **Linux:** `voxvera-linux`
|
||||
- **Windows:** `voxvera-windows.exe`
|
||||
- **macOS:** `voxvera-macos`
|
||||
|
||||
Bu dosyalar, VoxVera'yı çalıştırmak için gereken her şeyi içerir (`onionshare-cli` hariç).
|
||||
|
||||
### 2. Tek Satırlık Kurulum
|
||||
Alternatif olarak, otomatik betiğimiz aracılığıyla kurulum yapın:
|
||||
|
||||
```bash
|
||||
curl -fsSL https://raw.githubusercontent.com/PR0M3TH3AN/VoxVera/main/install.sh | bash
|
||||
```
|
||||
|
||||
### 3. Manuel Python Kurulumu
|
||||
Kaynaktan çalıştırmayı tercih ederseniz:
|
||||
|
||||
```bash
|
||||
pipx install 'voxvera@git+https://github.com/PR0M3TH3AN/VoxVera.git@main'
|
||||
sudo apt install tor onionshare-cli # Debian/Ubuntu
|
||||
```
|
||||
|
||||
## Adım Adım
|
||||
|
||||
1. **Başlatma:** `voxvera init` komutunu çalıştırın ve istemleri takip edin. Önce dilinizi seçmeniz istenecektir.
|
||||
2. **Oluşturma:** İlan varlıklarını oluşturun. Her oluşturma işlemi, ilan klasöründe otomatik olarak bir `voxvera-portable.zip` oluşturur; bu sayede başkaları tam aracı doğrudan ilanınızdan indirebilir.
|
||||
```bash
|
||||
voxvera build
|
||||
```
|
||||
3. **Sunma:** İlanı Tor üzerinden yayınlayın:
|
||||
```bash
|
||||
voxvera serve
|
||||
```
|
||||
bu komut mevcut Tor örneğinizi otomatik olarak algılar, OnionShare'i başlatır ve oluşturulan .onion adresini ilandaki yırtılabilir bağlantılara yazar.
|
||||
|
||||
## Dil Desteği
|
||||
|
||||
VoxVera tamamen yerelleştirilmiştir. Dil tercihinizi etkileşimli seçiciyi veya doğrudan kısayolu kullanarak kalıcı olarak değiştirebilirsiniz:
|
||||
|
||||
- **Etkileşimli Seçici:** `voxvera lang`
|
||||
- **Doğrudan Kısayol:** `voxvera --lang tr` (tercihi Türkçe olarak ayarlar)
|
||||
|
||||
### Desteklenen Diller:
|
||||
- **İngilizce:** `en`
|
||||
- **İspanyolca:** `es` (takma ad: `--idioma`)
|
||||
- **Almanca:** `de` (takma ad: `--sprache`)
|
||||
- **Türkçe:** `tr`
|
||||
|
||||
Kalıcı tercihinizi değiştirmeden tek bir komut için belirli bir dili de zorlayabilirsiniz:
|
||||
- **İngilizce:** `voxvera --lang en check`
|
||||
- **Türkçe:** `voxvera --lang tr check`
|
||||
|
||||
Oluşturulan ilanlar, ziyaretçinin tarayıcı dilini otomatik olarak algılar ve kullanıcı arayüzü metnini buna göre değiştirir.
|
||||
|
||||
## Sunucu Yönetimi
|
||||
|
||||
Tek bir etkileşimli menüden birden fazla ilanı ve Tor kimliklerini yönetin:
|
||||
|
||||
```bash
|
||||
voxvera manage
|
||||
```
|
||||
|
||||
Özellikler:
|
||||
- **--- Yeni Site/İlan Oluştur ---**: Tam kurulum dizisini başlatın.
|
||||
- **--- Tüm Siteleri Başlat ---**: Filonuzdaki tüm ilanları tek seferde başlatın veya kapatın.
|
||||
- **Gerçek Zamanlı Durum**: Aktif .onion URL'lerini ve Tor başlatma ilerleme göstergelerini görüntüleyin.
|
||||
- **Bireysel Kontrol**: Belirli siteleri ZIP olarak Zip Olarak Dışa Aktar veya silin.
|
||||
|
||||
## Evrensel Aynalama (Viral Dağıtım)
|
||||
|
||||
Merkezi depolar sansürlense bile VoxVera'nın erişilebilir kalmasını sağlamak için her ilan, araç için bir ayna görevi görür.
|
||||
|
||||
Bir ilanı barındırdığınızda, açılış sayfasındaki **"Aracı ve Kaynak Kodunu İndir"** düğmesi şunları içeren bir `voxvera-portable.zip` sunar:
|
||||
- Tam kaynak kodu ve desteklenen tüm diller.
|
||||
- Tüm Python bağımlılıkları (önceden paketlenmiş).
|
||||
- Platformlar arası Tor ikilileri.
|
||||
|
||||
Bu, ilanınızı tarayan herkesin VoxVera aracının yeni bir dağıtıcısı olmasını sağlar.
|
||||
|
||||
## Dışa Aktarma ve Yedekleme
|
||||
|
||||
Benzersiz Tor kimliklerinizi yedekleyin (.onion URL'nizin hiç değişmemesi için) veya ilanlarınızı başka bir makineye taşıyın.
|
||||
|
||||
- **Tek bir siteyi dışa aktar**: `voxvera export <klasör_adı>`
|
||||
- **Tüm siteleri dışa aktar**: `voxvera export-all`
|
||||
|
||||
**Depolama konumu:** Tüm dışa aktarmalar, tüm platformlarda kullanıcının ana dizinindeki `~/voxvera-exports/` klasörüne ZIP dosyası olarak kaydedilir.
|
||||
|
||||
## İçe Aktarma ve Kurtarma
|
||||
|
||||
ZIP dosyalarınızı `~/voxvera-exports/` dizinine taşıyıp şu komutu çalıştırarak tüm kurulumunuzu yeni bir makinede geri yükleyin:
|
||||
|
||||
```bash
|
||||
voxvera import-multiple
|
||||
```
|
||||
|
||||
## Taşınabilirlik ve Çevrimdışı Kullanım
|
||||
|
||||
VoxVera'yı internet erişimi olmayan bir makinede çalıştırmanız gerekirse, önce bağımlılıkları yerelleştirebilirsiniz:
|
||||
|
||||
```bash
|
||||
voxvera vendorize
|
||||
```
|
||||
|
||||
Bu, gerekli tüm Python kütüphanelerini `voxvera/vendor/` dizinine indirir. Araç daha sonra bu yerel dosyalara öncelik vererek `pip install` olmadan çalışmasına olanak tanır.
|
||||
|
||||
## Toplu İçe Aktarma (JSON)
|
||||
|
||||
Birden fazla JSON yapılandırma dosyasından toplu ilan oluşturmak için bunları `imports/` dizinine yerleştirin ve çalıştırın:
|
||||
|
||||
```bash
|
||||
voxvera batch-import
|
||||
```
|
||||
|
||||
## URL'ler Nasıl Çalışır?
|
||||
|
||||
Her ilanın iki ayrı URL'si vardır:
|
||||
- **Yırtılabilir bağlantı** (otomatik oluşturulur): İlanın barındırıldığı .onion adresi.
|
||||
- **İçerik bağlantısı** (kullanıcı tarafından yapılandırılır): Bir web sitesine, videoya veya indirmeye işaret eden harici bir URL.
|
||||
|
||||
.onion adresini manuel olarak girmenize gerek yoktur; VoxVera `serve` aşamasında bunu otomatik olarak halleder.
|
||||
@@ -0,0 +1,41 @@
|
||||
# AI Agent Instructions for VoxVera
|
||||
|
||||
This guide is for AI agents (like Gemini, Claude, or GPT) contributing to the VoxVera project. Follow these protocols to maintain the architectural integrity and multi-language support.
|
||||
|
||||
## Core Mandates
|
||||
|
||||
1. **Security-First**: VoxVera is a Tor-based tool. Never suggest features that leak IP addresses or use non-Tor external resources (CDNs, etc.).
|
||||
2. **Local-First**: All assets (fonts, dependencies, binaries) must be self-contained within the `voxvera/` package to support the Universal Mirroring model.
|
||||
3. **Tokenized UI**: Never hardcode user-facing strings. Always add them to `voxvera/locales/en.json` and use the `t('cli.token')` helper.
|
||||
4. **Markdown Redaction**: Use `~~text~~` in locale JSONs for strike-through effects. Both the build system and the JS engine handle the conversion to `<span class="redacted">` automatically.
|
||||
|
||||
## Localization Protocol
|
||||
|
||||
When adding a new language or updating an existing one:
|
||||
- **CLI/Flyers**: Update `voxvera/locales/{lang}.json`. Include `meta`, `cli`, `web`, and `landing` categories.
|
||||
- **Landing Page**:
|
||||
- Directly update the `const locales` object in `site/index.html`.
|
||||
- **Crucial**: Run `voxvera build-site` to generate the latest portable bundle and refresh the pre-rendered HTML.
|
||||
- **Documentation**:
|
||||
- Master templates live in `docs/templates/`.
|
||||
- Localized overrides live in `voxvera/locales/{lang}/docs/`.
|
||||
- **Crucial**: After any change to locales or templates, you MUST run `voxvera build-docs` to synchronize the output in `docs/{en,es,de}/`.
|
||||
|
||||
## Universal Mirroring
|
||||
|
||||
VoxVera propagates through its own flyers.
|
||||
- Every `voxvera build` and `voxvera build-site` generates `voxvera-portable.zip`.
|
||||
- If you modify the core source code, ensure the `bundle_portable` function in `voxvera/cli.py` still correctly captures all necessary directories (especially `vendor/`, `locales/`, and `resources/`).
|
||||
|
||||
## Verification Checklist
|
||||
|
||||
Before finishing a task, ensure you have:
|
||||
1. Run unit tests: `pytest tests/test_cli.py`.
|
||||
2. Verified the localization: `voxvera --lang {lang} check`.
|
||||
3. Rebuilt the documentation: `voxvera build-docs`.
|
||||
4. Synchronized the public site: `voxvera build-site`.
|
||||
5. Verified the portable bundle exists: `ls -l voxvera/host/*/download/voxvera-portable.zip` and `ls -l site/download/voxvera-portable.zip`.
|
||||
|
||||
---
|
||||
|
||||
Follow these rules to ensure VoxVera remains a robust, viral, and decentralized tool for truth.
|
||||
@@ -0,0 +1,42 @@
|
||||
# Contributing to VoxVera
|
||||
|
||||
Thank you for your interest in contributing to VoxVera! This project aims to be a global, censorship-resistant tool, and your help—especially with translations—is vital.
|
||||
|
||||
## Adding a New Language
|
||||
|
||||
VoxVera uses a centralized token system for the CLI and Web components, and a template-based system for Documentation. To add a new language (e.g., French/`fr`), follow this checklist:
|
||||
|
||||
### 1. The Token File
|
||||
Create a new JSON file in `voxvera/locales/{lang_code}.json`.
|
||||
- Use `en.json` as your master template.
|
||||
- **`meta`**: Include the native language name and a flag emoji.
|
||||
- **`cli`**: Translate all strings used in the terminal interface.
|
||||
- **`web`**: Translate strings used on the generated landing pages and flyers.
|
||||
- **`landing`**: Translate the specific content for the official VoxVera website.
|
||||
- **Formatting**: You can use Markdown-style strike-throughs (`~~redacted text~~`) in any of these strings; they will be automatically converted to the stylized "redacted" effect on the flyers.
|
||||
|
||||
### 2. The Landing Page
|
||||
The main landing page (`site/index.html`) must be synchronized to include your new language.
|
||||
- Open `site/index.html` and add your language to the `const locales` object in the `<script>` tag.
|
||||
- Run `voxvera build-site` to refresh the public assets and ensure the pre-rendered HTML matches your new locale.
|
||||
|
||||
### 3. Documentation
|
||||
VoxVera uses the **Doc-Sync Engine** to keep manuals in sync.
|
||||
- Create localized Markdown files in `voxvera/locales/{lang_code}/docs/`.
|
||||
- Use the templates in `docs/templates/` as your guide.
|
||||
- You can use `cli.token_name` to reference terminal commands automatically.
|
||||
|
||||
### 4. Build and Verify
|
||||
Run the following commands to verify your changes:
|
||||
- `voxvera --lang {lang_code} check` (Verify CLI translation)
|
||||
- `voxvera build-docs` (Generate localized manuals)
|
||||
- Open `site/index.html` in a browser and test the language switcher.
|
||||
|
||||
## Code Contributions
|
||||
- Ensure all tests pass: `pytest tests/test_cli.py`.
|
||||
- Follow the existing coding style (PEP 8 for Python).
|
||||
- If adding a new feature, update the master templates in `docs/templates/` and run `voxvera build-docs`.
|
||||
|
||||
---
|
||||
|
||||
Together, we can ensure that truth remains accessible to everyone, everywhere.
|
||||
@@ -0,0 +1,16 @@
|
||||
# Docker Usage
|
||||
|
||||
A prebuilt image containing Tor, OnionShare and the `voxvera` CLI is published to
|
||||
`ghcr.io/voxvera/voxvera`.
|
||||
|
||||
```bash
|
||||
# pull the image
|
||||
docker pull ghcr.io/voxvera/voxvera:latest
|
||||
|
||||
# run voxvera quickstart with flyers stored in ./flyers
|
||||
mkdir -p flyers
|
||||
docker run -it --rm -v "$(pwd)/flyers:/flyers" ghcr.io/voxvera/voxvera
|
||||
```
|
||||
|
||||
The container uses `/flyers` as the working directory and runs `voxvera quickstart`
|
||||
by default. All generated flyer files will appear in the mounted `flyers` folder.
|
||||
@@ -0,0 +1,14 @@
|
||||
# Flyer Templates
|
||||
|
||||
Pre-built flyer templates live in the `templates/` directory. Use the CLI to copy one with:
|
||||
|
||||
```bash
|
||||
voxvera init --template <name>
|
||||
```
|
||||
|
||||
This will create a new folder under `dist/` named `<name>-<YYYYMMDD>` containing the template files.
|
||||
|
||||
Available templates:
|
||||
|
||||
- **blank** – minimal placeholder files, also used when extracting fields from a PDF.
|
||||
- **voxvera** – example flyer showcasing the VoxVera project.
|
||||
@@ -0,0 +1,60 @@
|
||||
# Troubleshooting
|
||||
|
||||
This page collects common issues encountered when hosting or accessing flyers.
|
||||
|
||||
## Tor connectivity
|
||||
- Ensure Tor is allowed through your firewall. On systems using `ufw` you may need to run `sudo ufw allow tor`.
|
||||
- Some networks block Tor entirely. If you cannot reach onion services, try connecting over a different network or use a Tor bridge.
|
||||
|
||||
## Tor port detection
|
||||
|
||||
`voxvera serve` auto-detects Tor by probing common ports (9050/9150 for SOCKS, 9051/9151 for control). If detection fails -- for example when Tor runs on non-standard ports -- you can override with environment variables:
|
||||
|
||||
```bash
|
||||
TOR_SOCKS_PORT=19050 TOR_CONTROL_PORT=19051 voxvera serve
|
||||
```
|
||||
|
||||
If no running Tor is found, the defaults (9050/9051) are used and OnionShare will attempt to connect on those ports.
|
||||
|
||||
## Firewall rules
|
||||
- If `voxvera serve` fails to start OnionShare, verify that outbound connections on ports 9001 and 80 are permitted.
|
||||
- Corporate or university firewalls can block the hidden service ports required by Tor.
|
||||
|
||||
## SELinux
|
||||
- On SELinux-enabled distributions you may see `permission denied` errors when OnionShare writes to the `host` directory.
|
||||
- Run `sudo chcon -Rt svirt_sandbox_file_t host` or disable SELinux enforcement for the folder.
|
||||
|
||||
## OnionShare crashes
|
||||
If `voxvera serve` prints "OnionShare exited unexpectedly", check the log file
|
||||
`host/<folder_name>/onionshare.log` for details. Common causes:
|
||||
|
||||
- Tor is not running (`sudo systemctl start tor`)
|
||||
- A port conflict with another service
|
||||
- Missing `onionshare-cli` (run `voxvera check`)
|
||||
|
||||
## Onion URL changed unexpectedly
|
||||
The onion URL is tied to the Ed25519 keypair stored in
|
||||
`host/<folder_name>/.onionshare-session`. If this file is deleted, a new
|
||||
keypair (and URL) will be generated on the next `voxvera serve`. The
|
||||
`voxvera import` command preserves this file automatically, but manual
|
||||
deletion of the `host/` directory will destroy it.
|
||||
|
||||
## QR codes not generated
|
||||
If `voxvera build` reports "No URLs configured yet", this is expected before the first `voxvera serve`. QR codes for tear-off links are generated automatically once the .onion address is known. QR codes for the content link are generated if you provided a URL during `voxvera init`.
|
||||
|
||||
## Electron GUI
|
||||
If `npm start` fails with `spawn voxvera ENOENT`, the `voxvera` command is not in your `PATH`. Install it with `pipx install git+https://github.com/PR0M3TH3AN/VoxVera.git` or run `./install.sh` from the repository.
|
||||
|
||||
## Missing dependencies
|
||||
Run `voxvera check` to verify your setup. The command checks for required
|
||||
Python packages (`qrcode`, `Pillow`, `jsmin`, `htmlmin`, `pypdf`) and
|
||||
external tools (`onionshare-cli`), then prints a summary of anything
|
||||
missing. To install everything:
|
||||
|
||||
```bash
|
||||
# Recommended: use the install script (handles Tor + OnionShare too)
|
||||
curl -fsSL https://raw.githubusercontent.com/PR0M3TH3AN/VoxVera/main/install.sh | bash
|
||||
|
||||
# Or reinstall just the Python package
|
||||
pipx install --force 'voxvera@git+https://github.com/PR0M3TH3AN/VoxVera.git@main'
|
||||
```
|
||||
@@ -0,0 +1,130 @@
|
||||
# 详细用法
|
||||
|
||||
本指南涵盖了常用的 CLI 工作流程。有关 Docker 指令请参阅 `docs/docker.md`，有关可用传单模板请参阅 `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 zh`（将偏好设置为简体中文）
|
||||
|
||||
### 支持的语言：
|
||||
- **英语：** `en`
|
||||
- **西班牙语：** `es`（别名：`--idioma`）
|
||||
- **德语：** `de`（别名：`--sprache`）
|
||||
- **简体中文：** `zh`
|
||||
|
||||
您也可以在不更改永久偏好的情况下，为单个命令强制指定特定语言：
|
||||
- **英语：** `voxvera --lang en check`
|
||||
- **简体中文：** `voxvera --lang zh check`
|
||||
|
||||
生成的传单会自动检测访问者的浏览器语言并相应地切换 UI 文本。
|
||||
|
||||
## 服务器管理
|
||||
|
||||
通过单一的交互式菜单管理多个传单及其 Tor 身份：
|
||||
|
||||
```bash
|
||||
voxvera manage
|
||||
```
|
||||
|
||||
功能：
|
||||
- **--- 创建新站点/传单 ---**：开始完整的设置序列。
|
||||
- **--- 启动所有站点 ---**：一次性启动或关闭您旗下的所有传单。
|
||||
- **实时状态**：查看活跃的 .onion URL 和 Tor 引导进度指示器。
|
||||
- **个人控制**：将特定站点 导出为 Zip 到 ZIP 或删除它们。
|
||||
|
||||
## 通用镜像（病毒式传播）
|
||||
|
||||
为了确保即使中央仓库被审查，VoxVera 仍然可用，每张传单都充当该工具的镜像。
|
||||
|
||||
当您托管传单时，落地页上的 **“下载工具与源码”** 按钮会提供一个 `voxvera-portable.zip`，其中包含：
|
||||
- 完整的源代码和所有支持的语言。
|
||||
- 所有 Python 依赖项（预先打包）。
|
||||
- 跨平台的 Tor 二进制文件。
|
||||
|
||||
这允许任何扫描您传单的人成为 VoxVera 工具的新分发者。
|
||||
|
||||
## 导出与备份
|
||||
|
||||
备份您独特的 Tor 身份（这样您的 .onion URL 就永远不会改变）或将您的传单移动到另一台机器。
|
||||
|
||||
- **导出单个站点**：`voxvera export <文件夹名称>`
|
||||
- **导出所有站点**：`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
|
||||
```
|
||||
|
||||
## URL 如何工作
|
||||
|
||||
每张传单都有两个独立的 URL：
|
||||
- **撕下链接**（自动生成）：托管传单的 .onion 地址。
|
||||
- **内容链接**（用户配置）：指向网站、视频或下载的外部 URL。
|
||||
|
||||
您无需手动输入 .onion 地址；VoxVera 会在 `serve` 阶段自动处理。
|
||||
Reference in new issue
Block a user