Advanced Usage

If you want to dig a bit deeper into what the plugin can do, here are a few extra features.

Gestures

You can tie the X-Ray menu to any of KOReader's gestures (like corner taps or edge swipes):

1. Go to Menu → Settings → Taps and Gestures → Gesture Manager.
2. Pick whatever gesture you prefer.
3. Look for X-Ray Quick Menu under General in the action list and assign it.

Manual Config Editing

While most settings are handled through the UI, you can manually enter your API keys by editing xray_config.lua in the plugin folder. It should look like this:

-- X-Ray API Configuration

return {
    -- Google Gemini API Key
    -- To get an API key: https://aistudio.google.com/
    gemini_api_key = "", 
    
    -- ChatGPT API Key 
    -- To get an API key: https://platform.openai.com/api-keys
    chatgpt_api_key = "",  

    -- DeepSeek API Key
    -- To get an API key: https://platform.deepseek.com/
    deepseek_api_key = "",

    -- Anthropic Claude API Key
    -- To get an API key: https://console.anthropic.com/
    claude_api_key = "",

    -- Custom API slot 1 (e.g., OpenRouter, any OpenAI-compatible endpoint)
    custom1_api_key  = "",   -- Your API key for this endpoint
    custom1_endpoint = "",   -- e.g., "https://openrouter.ai/api/v1/chat/completions"
    custom1_model    = "",   -- e.g., "google/gemini-2.5-pro"

    -- Custom API slot 2 (e.g., a local Ollama server)
    custom2_api_key  = "",
    custom2_endpoint = "",   -- e.g., "http://localhost:11434/v1/chat/completions"
    custom2_model    = "",   -- e.g., "llama3"
}

Note: Other settings like model selection and spoiler preferences are managed through the on-screen menu and stored in a separate settings.json file outside the plugin folder, so your settings will persist even if you uninstall and reinstall the plugin.

Maintenance Tools

Under the Maintenance menu, you'll find a few useful utilities:

• Clear Cache: Sometimes the AI gets confused or returns weird data. Hit this to wipe the saved file for your current book and start fresh.
• Beta Channel: Opt into pre-release builds to test the latest features before they are officially released.
• Troubleshooting: If things aren't working right, take a look at the xray.log file in the plugin folder. It usually points directly to whatever is going wrong.

Adding New Languages

The plugin natively supports 13 languages (English, German, French, Spanish, Brazilian Portuguese, Russian, Ukrainian, Turkish, Simplified Chinese, Dutch, Hungarian, Polish, and Indonesian). If your language isn't supported yet, you can request it in the Github Issues and we can add additional languages, or you can easily add it yourself! The plugin requires two separate translation files:

1. UI Strings (languages/<lang>.po): This handles the buttons, menus, and messages. You can use en.po as a template and translate the msgstr values.
2. AI Prompts (prompts/<lang>.lua): This is crucial because it tells the AI to provide descriptions and summaries in your language. Without this, the AI may respond in English even if the UI is localized.

Once you've created these files, the plugin will automatically detect them in the Menu → X-Ray → Language settings.