4. Data Management
The X-Ray plugin provides several settings to curate, customize, and maintain your book databases.
Sometimes the AI might extract the same character or location under slightly different names (e.g., "Dracula" and "Count Dracula"). You can merge these into a single profile to clean up your lists. The plugin uses AI to combine their descriptions into one cohesive summary while preserving all their mentions and timeline data.
You can perform merges manually from the Characters or Locations menu, or let the AI assist you:
-
AI Scan from the list: When characters (or locations) are loaded, a ⋈ Merge Duplicates… option appears at the top of the list. Tapping it opens a sub-dialog with two paths:
- ✦ AI Scan — sends the current list to the AI, which identifies likely duplicates and immediately opens the step-by-step review dialog.
- Manual Pick — lets you choose the primary and secondary entries yourself for a targeted merge.
- Automatic Duplicate Check: Under Tools Menu → X-Ray → Settings → Content & Fetch Settings → Auto X-Ray Settings → Duplicate Check, you can enable automatic duplicate detection. When enabled, the AI scans for duplicates after every data fetch. Background fetches save these suggestions for the next time you open the Characters/Locations lists, while manual fetches trigger the review dialog immediately.
For each suspected duplicate pair, you are shown a dialog with four choices:
| Action | What it does |
|---|---|
| Merge | AI combines both descriptions into one cohesive bio and removes the secondary entry. |
| Skip | Ignores this pair for the current session; it may surface again on the next scan. |
| Reject | Permanently marks this pair as not a duplicate for this book. The pair is saved to the book's cache and will never be suggested again, even across app restarts. |
| Stop | Ends the review walk immediately, keeping any merges already performed. |
| AI Duplicate Detected | AI Merging Descriptions |
|---|---|
 |
 |
You can control the verbosity of the AI-generated content in Tools Menu → X-Ray → Settings → Content & Fetch Settings → Description Length Settings. The plugin provides four distinct tiers of detail that can be configured independently for different types of data:
- Characters: Control how deep the character bios go.
- Locations: Adjust the detail for setting and place descriptions.
- Timeline: Change the length of individual plot summaries in the timeline.
- Historical Figures: Fine-tune the depth of real-world historical context.
- Glossary / Terms: Control the depth of definitions for setting-specific terminology or technical terms.
For each of these, you can choose between:
- Short: Quick, one-sentence summaries.
- Default: Balanced descriptions (the standard experience).
- Detailed: Longer bios and more context for complex entries.
- Very Detailed: Deep dives for those who want as much information as possible.
Linked Entries automatically connects characters, locations, and historical figures when they are mentioned in each other's descriptions.
- Smart Navigation: When viewing an entry (e.g., Abraham Van Helsing), you will see a "Linked Entries" button if other entities are mentioned in his bio (e.g., Dracula or Whitby).
Tip
You can enable or disable this feature under Tools Menu → X-Ray → Settings → Display & UI Settings → Linked Entries Settings. Disabling it will hide the button from detail dialogs for a cleaner interface.
The plugin interface and AI-generated content are fully localized into 14 languages: English, German, French, Spanish, Brazilian Portuguese, Russian, Ukrainian, Turkish, Simplified Chinese, Dutch, Hungarian, Polish, Indonesian, and Arabic.
You can configure the language settings under Tools Menu → X-Ray → Settings → Language:
- Automatic (Follow System): Matches KOReader's global UI language.
- Automatic (Follow Book): Matches the language of the book you are currently reading (ideal for bilingual readers).
- Manual Selection: Force a specific language for all menus and X-Ray data.
Smart Detection: If you open a book in a supported language that differs from your current X-Ray setting, the plugin will automatically ask if you want to switch languages to match the book.
If your language isn't supported yet, you can request it in the Github Issues or easily add it yourself! The plugin requires two separate translation files:
-
UI Strings (
languages/<lang>.po): This handles the buttons, menus, and messages. You can useen.poas a template and translate themsgstrvalues. -
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 Tools Menu → X-Ray → Language settings.
Under the Maintenance menu (Tools Menu → X-Ray → Maintenance), you'll find several useful utilities:
- Clear Cache: If the AI gets confused or returns weird data, hit this to wipe the saved file for your current book and start fresh.
-
View Log: Opens the plugin's
xray.logfile in a scrollable viewer directly inside KOReader — no file manager needed. The viewer automatically scrolls to the bottom so the most recent entries are immediately visible. This is the fastest way to see what the plugin is doing or to diagnose a problem. -
Clear Logs: Deletes both the current log (
xray.log) and its backup (xray.log.old). Useful if you want a clean slate before reproducing an issue. The log is also rotated automatically once it exceeds 512 KB, so it won't grow unbounded even if you never manually clear it. - Beta Channel: Opt into pre-release builds to test the latest features before they are officially released.