VoxVera/docs/multi-language-support.md

Multi-Language Support Developer Plan

This document outlines the strategy for implementing a token-based multi-language system in VoxVera, covering the CLI, the generated landing page, and documentation.

1. Core Architecture: The Token System

All translatable strings will be centralized in JSON files located in voxvera/locales/. This allows for easy addition of new languages by simply dropping a new file.

• Storage: voxvera/locales/{lang_code}.json (e.g., en.json, es.json).
• Structure:

  {
    "meta": {
      "language_name": "English",
      "flag": "🇺🇸"
    },
    "cli": {
      "welcome": "Welcome to VoxVera Setup",
      "select_lang": "Select your preferred language",
      "folder_prompt": "Enter folder name for this flyer:"
    },
    "web": {
      "title": "VoxVera - Anonymous Flyers",
      "download_btn": "Download Flyer",
      "onion_link_desc": "Scan to view on Tor",
      "change_lang": "Change Language"
    }
  }
  

2. CLI Implementation (voxvera/cli.py)

The CLI will be updated to handle localization from the start of the user interaction.

Workflow:

1. Initial Detection: On startup, the CLI checks the system locale (LANG env var or locale module).
2. Language Selection: The first prompt in voxvera init will be a language selector, defaulting to the detected system locale.
3. Session Loading: Once selected, the CLI loads the corresponding JSON. All subsequent InquirerPy prompts will use these tokens.
4. Configuration: The chosen language code is saved in the flyer's config.json as a preference for that specific project.

3. Web Implementation (voxvera/src/index-master.html)

The landing page will support dynamic language switching without requiring server-side logic (essential for Tor-hidden services).

Detection Logic:

• Avoid IP-based Detection: Since VoxVera is hosted on Tor, IP lookups return the Tor Exit Node location, not the user's.
• Browser-based Detection: Use navigator.language to detect the user's browser preference.
• Persistence: Save the user's manual choice in localStorage.

Frontend Components:

1. Attributes: Use data-i18n="web.token_name" on HTML elements.
2. Language Switcher: A dropdown menu or text-link list (e.g., "EN | ES | FR") placed next to the Download button.
3. I18n Engine: A lightweight JavaScript snippet injected during the build process that:
   • Loads the bundled locale data.
   • Detects the best language (Manual Selection > Browser Setting > English Fallback).
   • Updates all data-i18n elements.

4. Build System Updates (voxvera/build.py)

The build process will be updated to bundle the necessary translations.

• Multi-bundle: By default, all available web tokens from all locale files will be injected into a single <script> tag in the final index.html. This ensures instant switching even when offline or on slow Tor connections.
• Asset Optimization: Minify the locale JSON data before injection to keep the HTML lightweight.

5. Portable & Viral Distribution Model

To ensure VoxVera is truly censorship-resistant, every generated flyer will serve as a mirror for the entire tool, including all supported languages and dependencies.

Key Requirements:

• Zero-Dependency Execution: All Python libraries (from requirements.txt) will be bundled into a voxvera/vendor/ directory. The CLI will be updated to prioritize this local path.
• Pre-Bundled Tor: The existing voxvera/resources/tor/ binaries for Linux, Mac, and Windows will be included in every distribution.
• Universal Language Bundle: Every voxvera-portable.zip will include the full voxvera/locales/ directory, ensuring that a user who downloads the tool from an English flyer can immediately switch it to Spanish, French, or any other supported language.

The "Mirror" Workflow:

1. Build Phase: When voxvera build is executed, it assembles a voxvera-portable.zip containing:
   • The full voxvera/ source code.
   • The vendor/ library directory.
   • All locales/*.json files.
   • Cross-platform Tor binaries.
   • A voxvera-run.sh / voxvera-run.bat entry point.
2. Injection: This ZIP is automatically placed in the voxvera/host/<folder_name>/download/ directory of the generated flyer.
3. User Access: The landing page's "Download" button is updated to explicitly offer the "Full Portable Tool & Source," allowing the recipient to become a new node in the distribution network.

6. Documentation (docs/)

Documentation will follow a subdirectory structure for maximum compatibility with GitHub/Markdown renderers.

• Structure:
  • docs/en/usage.md
  • docs/es/usage.md
• Maintenance: A master English file will serve as the source of truth for all translations.

6. Implementation Phases

1. Phase 1 (Audit): Extract all hardcoded strings from cli.py and index-master.html into en.json.
2. Phase 2 (CLI): Implement the language selector and token loader in cli.py.
3. Phase 3 (Web): Update the HTML template with data-i18n attributes and the JS switcher.
4. Phase 4 (Build): Update build.py to inject the locale bundle.
5. Phase 5 (Expansion): Add a second language (e.g., Spanish) to verify the system.