# 詳細な使い方

このガイドでは、一般的な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 ja` (日本語に設定)

### サポートされている言語:
- **英語:** `en`
- **スペイン語:** `es` (エイリアス: `--idioma`)
- **ドイツ語:** `de` (エイリアス: `--sprache`)
- **日本語:** `ja`

永続的な設定を変更せずに、単一のコマンドに対して特定の言語を強制することもできます。
- **英語:** `voxvera --lang en check`
- **日本語:** `voxvera --lang ja 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`

**保存場所:** すべてのエクスポートは、すべてのプラットフォームでユーザーのホームディレクトリにある `~/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の仕組み

各フライヤーには2つの異なるURLがあります。
- **切り取り用リンク** (自動生成): フライヤーがホストされている .onion アドレス。
- **コンテンツリンク** (ユーザー設定): ウェブサイト、動画、またはダウンロードを指す外部URL。

.onion アドレスを手動で入力する必要はありません。VoxVeraが `serve` フェーズ中に自動的に処理します。