GitHub - duhubz/Rosetta-Magazine-Researcher: Python based application for viewing/searching retro gaming magazines alongside transcriptions/translations in multiple languages.

11 min read Original article ↗

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.

Buy me a beer

Other ways to support:

Discord Link

📥 Download & Installation

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"

Notice on AI Translations

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.

🚀 Getting Started

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 will automatically shut down after 20 seconds to save memory.

🎮 Viewer Controls & Interactive Reading

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. Ctrl + 0 resets zoom to 100%.
  • 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!

🔍 Search & Library Tips

  • 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.
  • 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.

Advanced Date Searching

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.

⌨️ Keyboard Shortcuts

  • Left / Right Arrows: Previous / Next Page.
  • Page Up / Down: Scroll the translation/transcription boxes.
  • Ctrl + (Plus/Minus): Zoom In / Out.
  • Ctrl + 0: Reset zoom to 100%.
  • Escape: Close any open editor or modal window.

🛠️ Editing

Click the ✏️ Edit button in the toolbar to begin improving a page. 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.

📝 Content & Metadata

  • 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.

⚙️ Magazine Metadata

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.

🎨 Spatial Box Manipulation

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.

📁 Adding Local Magazines

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]]
...

📚 The Library Catalog (catalog.json)

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.

⚙️ Configuration (config.yaml)

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: 20   # Auto-exit when browser tab is closed
  check_interval_seconds: 5

🛠️ Developer Notes

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:

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.

Credits

License (AGPLv3)

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