Rosetta Magazine Researcher 📚

A fully offline-capable archive viewer with smart search, text formatting, and community catalogs to download magazines along with translations and transcriptions. Designed to seamlessly read scanned PDFs alongside transcribed text, translations, and rich metadata.

If this tool saved you some time and you'd like to support the project, feel free to buy me a beer! Translations and transcriptions cost money to generate so any support is greatly appreciated.

Other ways to support:

• Venmo: @Dustin-Hubbard-26
• PayPal: Donate via PayPal

Download the latest version for Windows, Mac, or Linux from our Releases Page.

• Windows users: Download the .exe file and double-click to run.
• Mac / Linux users: Download the .zip file, extract it, and run the executable inside.

Note for Mac Users - Because this app is not signed by an Apple Developer account, macOS may prevent it from opening. If you see an error saying the app is 'damaged' or 'from an unidentified developer,' open Terminal and run: xattr -cr /path/to/Rosetta_Magazine_Researcher.app

Prefer to run the app with your own Python (3.11+)? Clone or download this repository, then from the project folder:

pip install -r requirements.txt
python app.py

The app starts a local web server and opens in your browser. Re-run pip install -r requirements.txt after updating to a new version — dependencies change occasionally.

Transcriptions & translations in this program are generated by various Artificial Intelligence models. AIs can and do "hallucinate," miss cultural nuances, mistranslate, or transcribe incorrectly. Please do not rely on this for 100% academic or historical accuracy. Its main goal is to provide assistance in the research process, with the intent that specific excerpts should be validated by professional translators.

• Contribute: If you spot errors, use the ✏️ Edit button. If you fix an entire issue, consider sharing your corrections with the Discord community.

Use the Library button to download new issues from the cloud, or the Search tab to find specific content inside your downloaded magazines.

To safely close the application, simply close your browser tab! The background server notices and shuts itself down about 20 seconds later. As long as the app is open in any tab — even one in the background — the server keeps running.

Automatic Update Check: Once a day, the app checks GitHub for a newer release. If one exists, a banner appears with Download, Remind me later (snoozes it for 24 hours), and Skip this version buttons. You can disable the check entirely by setting security.update_check_enabled: false in config.yaml.

Rosetta features a spatial mapping engine. If an issue includes a coordinates JSON file, the text in the sidebar is linked directly to the scan.

• Interactive Hovering: Move your mouse over a translation in the sidebar to see the exact transcribed text light up in cyan on the scan.
• Reverse Lookup (Click-to-Scroll): Click any cyan box on the magazine image to automatically scroll the sidebar to that translation. Clicking again toggles between translation and transcription.
• 💬 Manga Mode: Paints over the original transcribed text and injects translations directly onto the page for a professional "scanlation" experience.
• 👁️ Zones Toggle: See a "heat map" of exactly where the AI detected text on the page.
• Native Zoom & Pan: Use the 🔍+ and 🔍- buttons, or hold Ctrl + Mouse Wheel to zoom toward your cursor. You can also type an exact percentage (30–500%) into the zoom box in the toolbar and press Enter, or press Ctrl + 0 to reset to 100%. The scan automatically re-renders at higher zoom levels so it stays sharp instead of getting blurry.
• ⊞ Page Grid: Click the ⊞ button next to the page arrows to open a thumbnail grid of every page — click any thumbnail to jump straight to that page. Fully keyboard navigable (arrow keys + Enter).
• Formatting: Click the MD button to toggle between formatted markdown and raw text.
• Font Size & Theme: Use the slider at the bottom to adjust text size, and the ☀️ button to switch between Dark and Light mode.
• Bookmarks: Click the ⭐ button to save your current page. You can add custom tags to your bookmarks to easily filter them in the Bookmarks sidebar tab!
• Customizable Toolbar: Grab the dotted handle (⋮⋮) on any section of the bottom toolbar to drag and reorder the controls to your liking. Your custom layout is saved automatically!
• Everything Remembers: Your theme, font size, zoom level, toolbar layout, and last-read page are all saved automatically — the app reopens right where you left off.

• Advanced Search: Use quotes for exact phrases ("action packed"), a minus sign to exclude words (-boring), or asterisks for wildcards (translat*).
• Filter by Section: Use the checkboxes in the sidebar to search only summaries or only translations.
• Spatial Highlights: When you click a search result, the app auto-scrolls the PDF to the exact location of the word and flashes a red box over the text.
• Library Management: You can Uninstall downloaded issues to save hard drive space, or use the 🔄 Update All button to batch download updates for all your installed magazines at once.
• 📄 Text Only Downloads: Save disk space by downloading just the transcriptions & translations without the large PDF scan. Text-only issues show a 📄 Text Only badge in your library, and the reader shows the text side without page images. Click ⬇️ Get Full Version later to add the scanned pages in place — no reinstall needed.
• Adult Content: In the library, magazines tagged as 18+/NSFW are hidden by default. Check the "18+ Content" box in the library to view them.

Search using years, months, or specific days:

• Type 1999 to search the entire year.
• Type 1999/10 or 10-1999 for a specific month.
• Type 10-31-99 or 1999-10-31 for a specific day.

The entire app can be driven from the keyboard: the library grid, search results, and page-thumbnail grid all support arrow-key navigation, every dialog traps focus and closes with Escape, and screen readers receive live announcements for search results and download progress.

Click the ✏️ Edit button in the toolbar to begin improving a page. If you prefer to edit files manually on your computer (instead of using the Editor), navigate to the Magazines subfolder and edit the txt file of the magazine with your text editor of choice.

• Sections: Each page has Transcription (Original), Translation, and Summary you can quickly edit.
• Visual Editor: Click the Open Editor button on any section for a full-screen Markdown experience with a live preview side-by-side of that section.
• Markdown: Supports tables, bolding, and lists. Ensure the MD button is enabled (Default behavior) to see the final formatted result.
• Magazine Metadata: Click Edit Metadata at the bottom of the content area to update searchable fields (Publisher, Date, Tags) or add Scanner/Editor credits and URLs.

Metadata applies to the entire magazine. It's main use case is to improve searchability as things in it such as publisher, date, and subject tags are used by the search engine. The file is optional, if it doesn't exist, the app will simply use the magazine's folder name as its title and leave all other metadata fields blank.

Schema (metadata.txt) This file sits on your local hard drive next to the PDF (or inside its .zip). All the fields are optional.

Magazine Name: Game Magazine Publisher: Nintendo Date: 1992-10-01 Issue Name: Volume 1 Region: Japan Translation: English Version: 1.1 Tags: action, nes, mario Scanner: John Doe Scanner URL: www.whatever.com Editor: Billy Bob Editor URL: www.whatever.com Notes: Missing pages 12-14.

Transcriptions/Translations downloaded from the Library often come with a coordinates JSON file that maps the exact location of each line of text on the original magazine scan. If you find any misalignments, you can edit these boxes directly in the app!

• Resize/Move: Click a box to select it, then drag the edges to resize or move it.
• Split Box: Creates a new box directly below the current one. This is useful when a text string or block is spread across multiple areas on the page. Simply draw the new box over the next area of text and both boxes will highlight when clicked or hovered over in the viewer.
• Delete Box: Click an existing box and then click the delete button.
• Add Box: Click the Add New Box button and copy/paste the proper transcription text into it in order to link it.

You do not have to use the Cloud Library! You can easily add your own personal PDFs to the viewer. The app reads magazines from its Magazines subfolder.

1. Open the Magazines subfolder located in the application folder.
2. Create a new folder for your magazine (e.g., My Custom Mag).
3. Drop your .pdf file inside that new folder.
4. Drop the .txt or .zip file containing the transcription and/or a metadata.txt into that same folder! (As long as it's the only ZIP in the folder, or shares the exact same name as the PDF, the app will automatically link them).
5. Restart the app (or just refresh the page), and it will automatically appear in your Search dropdown!

Here is how your folder should look (You can also use multiple subfolders if you want to organize by year or publisher, just make sure the PDF and its text/metadata files are in the same folder):

📁 Magazines
  └── 📁 Super Mario Magazine
       ├── Super_Mario_01.pdf           <-- The scanned magazine
       ├── Super_Mario_01.zip           <-- (Optional) ZIP containing files below
       ├── Super_Mario_01_COMPLETE.txt  <-- Recommended: Master translation file
       ├── Super_Mario_01_COORDINATES.json <-- Spatial mapping data
       └── metadata.txt                 <-- Magazine details (Optional)

Text File (_COMPLETE.txt) format:

[[PAGE_001]]
#GA-TRANSCRIPTION
(Transcription text goes here)

#GA-TRANSLATION
(Translation text goes here)

#GA-SUMMARY
(Summary text goes here)

[[PAGE_002]]
...

While metadata.txt handles your local files, the Library tab populates its list of downloadable magazines using a master catalog.json file.

Official Automatic Updates: When you open the Library, the app automatically fetches the latest official catalog from the web. If an official magazine receives a new translation or fix, the app compares the cloud version to your local file and displays an 🔄 Update Available badge! If you are offline, it safely falls back to reading your local catalog.json file.

Adding Custom Catalogs: You can also add third-party magazine lists created by the community!

1. Create a folder named Catalogs in the same folder as this application.
2. Place any community .json catalog files inside it.
3. The app will automatically merge them into your Library!

Creating Your Own Catalog: There are two ways to format a custom catalog:

Format A: Simple Array Best for offline sharing or static lists. It is just a raw list of magazines.

• Pros: Super simple, no web hosting needed.
• Cons: Does not auto-update if the creator adds new magazines.

[
  {
    "id": "smm_01",
    "magazine_name": "Super Mario Magazine",
    "date": "1992-10",
    "version": "1.0",
    "pdf_filename": "Super_Mario_Mag_01.pdf",
    "pdf_sources":["https://link-to-pdf.com/file.pdf"]
  }
]

Format B: Auto-Updating Object Best for translation groups or creators who continuously release updates.

• Pros: Automatically downloads the newest list from the web. Syncs "Update Available" badges!
• Cons: Requires you to host the JSON file on a website.

{
  "update_url": "https://yourwebsite.com/catalog.json",
  "items":[
    {
      "id": "smm_01",
      "magazine_name": "Super Mario Magazine",
      "version": "1.1",
      "pdf_filename": "Super_Mario_Mag_01.pdf",
      "pdf_sources":["https://link-to-pdf.com/file.pdf"]
    }
  ]
}

Catalog Field Breakdown:

• id: (Required) Unique identifier.
• pdf_filename: (Required) Exact file name the PDF saves as.
• pdf_sources: (Required) Array of direct download URLs for the PDF.
• zip_filename & zip_sources: (Optional) Filename and array of URLs for the transcription/metadata ZIP. If omitted, defaults to {pdf_stem}_Data.zip.
• version: Controls the "🔄 Update Available" badge. Compared against local metadata.txt.
• tags: Comma-separated list ("action, retro").
• scanner & editor: (Optional) Credits for the community members.
• scanner_url & editor_url: (Optional) Links for the credits.
• notes: (Optional) Special warnings or notes about the issue.
• adult_content: true or false. Hides issue unless "18+ Content" is checked.
• original_language & translated_language: Uses 2-letter codes (JP, EN) to generate flags.

The PDFs and ZIPs are downloaded from the URLs in pdf_sources and zip_sources (defined in the catalog by the publisher). If either are empty or missing, the app skips them. The app tries each URL in order until one succeeds, so catalog authors can list backup mirrors.

Text-only downloads: The app offers a per-magazine Text Only download that fetches only the zip_sources/zip_filename data ZIP; no new catalog fields are needed. A text-only install is the data ZIP without its PDF, and the app writes a Pdf Filename: line into the ZIP's metadata.txt to key the install. Downloading the full version later upgrades it in place.

Public Mega file links are also supported in pdf_sources and zip_sources:

"pdf_sources": ["https://mega.nz/file/FILE_ID#DECRYPTION_KEY"]

Mega downloads are handled natively (anonymous public shares only — no account, no Mega SDK): the app fetches the file through Mega's public API, decrypts it on the fly, and verifies the file's integrity checksum before installing it. The decryption key is part of the share URL, so treat catalog files containing Mega links as sensitive. Mega's API and storage hosts ship in the default security.allowed_fetch_hosts; remove them there to disable Mega downloads.

You can customize the app by placing a config.yaml file next to the application (or executable). If the file is missing, sensible defaults are used. All paths are relative to the app root.

server:
  port: 18028              # Port for the local web server

paths:
  data_dir: Magazines      # Folder for downloaded magazines
  bookmarks_file: bookmarks.json
  catalog_file: catalog.json
  catalogs_dir: Catalogs
  covers_dir: Covers

catalog:
  urls:                    # Official catalog URLs (tried in order)
    - https://www.gamingalexandria.com/ga-researcher/catalog.json
    - https://archive.org/download/ga-researcher-files/catalog.json

download:
  timeout_seconds: 60      # Timeout for PDF/ZIP downloads
  catalog_fetch_timeout: 10
  cover_fetch_timeout: 5

heartbeat:
  shutdown_after_idle_seconds: 180  # Failsafe: exit if nothing has pinged for this long (browser crash)
  check_interval_seconds: 5
  close_grace_seconds: 20  # Exit this soon after the last tab closes cleanly

For local development, you can create a config.local.yaml next to config.yaml. The app loads config.yaml first, then overlays any values from config.local.yaml.

For example:

server:
  dev_mode: true

When server.dev_mode is true, the app runs with Flask's development reloader. Python and template changes are picked up automatically, and static files are served without cache so a normal browser refresh is enough to see CSS/JS changes. Dev mode also skips the idle auto-shutdown behavior.

• App Creator: Dustin Hubbard (Hubz) - (https://www.gamingalexandria.com)
• Powered by: Python, Flask, PyMuPDF (fitz), and Marked.js

Copyright (c) 2026 Gaming Alexandria LLC.

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

If you modify this software or use it over a network (SaaS), you must release your source code under the same AGPLv3 license. For the full license text, visit: https://www.gnu.org/licenses/agpl-3.0.html