Plugin for PDF

Security Challenges in PDF Integration

Rybená faces significant technical barriers when trying to translate PDF content due to the security policies of modern browsers. These restrictions are essential for user protection but create specific challenges for accessibility solutions.

Same-Origin Policy and Iframes

Browsers implement the Same-Origin Policy, which prevents scripts from one origin (domain) from accessing content from another origin. This directly affects PDF translation because:

  • Standard PDF readers use iframes to render content
  • External scripts (like rybena.js) cannot access selection events within iframes from different origins
  • Text selection events are essential for identifying content to be translated

The Solution: Direct Integration in the Iframe

To overcome this security barrier, it's necessary to include the rybena.js directly within the iframe that renders the PDF. This file acts as a communication bridge between the PDF content and Rybená's translation servers.

Important

PDF integration follows the same rules and barriers as conventional iframe integration. For browser security reasons, it's not possible to detect selection events to perform translation without the rybena.js script being incorporated directly into the iframe.

Installing the Custom Plugin

To ensure that Rybená can correctly translate PDF texts, you need to install a customized PDF reading plugin created by Rybená.

Steps for integration

1. Download the Plugin

2. Unzip the file

3. Upload to HTTP Server

Questions about installation

If you have any questions or difficulties, they can be resolved in the official PDF.js documentation Our plugin has just one simple modification to insert Rybená into this plugin

How the Integration Works

The Rybená custom plugin modifies the standard PDF reader (based on PDF.js) to:

  1. Incorporate rybena.js directly into the iframe environment
  2. Capture selection events within the PDF document
  3. Communicate with Rybená servers for translation
  4. Display LIBRAS translation or voice synthesis

Detailed Installation Guide

Step 1: Download and Preparation

  1. Download the custom plugin:

    https://drive.google.com/file/d/1qJZ8iIe0MBzSYnQz9VV38YRsrjAf8sPq/view?usp=drive_link

  2. Unzip the file in a directory of your choice

  3. Check the structure - you should see something like:

    pdfjs-rybena/
├── web/
│   ├── index.html
│   ├── viewer.js
│   └── ...
└── build/
    └── pdf.js

Step 2: Server Configuration

  1. Upload the unzipped folder to your web server
  2. Check permissions - ensure the web server can read the files
  3. Test access by navigating to:
    https://yourserver.com/pdfjs-rybena/web/index.html

Step 3: PDF Integration

<!-- Basic example -->
<iframe
  src="https://yourserver.com/pdfjs-rybena/web/index.html?file=https://yourserver.com/documents/manual.pdf"
  width="100%"
  height="600px"
  style="border: 1px solid #ccc;"
>
</iframe>

<!-- Example with additional parameters -->
<iframe
  src="https://yourserver.com/pdfjs-rybena/web/index.html?file=https://yourserver.com/documents/manual.pdf#page=2&zoom=auto"
  width="100%"
  height="600px"
  style="border: 1px solid #ccc;"
  title="PDF Viewer with Rybená Accessibility"
>
</iframe>

<!-- Open in new tab -->
<a
  href="https://yourserver.com/pdfjs-rybena/web/index.html?file=https://yourserver.com/documents/manual.pdf"
  target="_blank"
  rel="noopener noreferrer"
>
  Open PDF with Accessibility
</a>

Step 4: Useful Parameters

You can use various parameters in the URL to control the visualization:

<!-- Specific page -->
?file=document.pdf#page=5

<!-- Specific zoom -->
?file=document.pdf#zoom=150

<!-- Search in document -->
?file=document.pdf#search=term

<!-- Specific position -->
?file=document.pdf#page=3&zoom=125&view=FitV

Practical Examples

Example 1: Institutional Website

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Documents with Accessibility</title>
    <style>
      .pdf-container {
        width: 100%;
        max-width: 1200px;
        margin: 0 auto;
      }
      .pdf-frame {
        width: 100%;
        height: 80vh;
        border: 1px solid #ddd;
        border-radius: 4px;
      }
    </style>
  </head>
  <body>
    <div class="pdf-container">
      <h1>Instruction Manual</h1>
      <p>This document is equipped with Rybená accessibility features.</p>

      <iframe
        src="https://yourserver.com/pdfjs-rybena/web/index.html?file=https://yourserver.com/manuals/instructions.pdf"
        class="pdf-frame"
        title="Instruction Manual with Accessibility"
      >
      </iframe>
    </div>
  </body>
</html>

Example 2: Management System

<!-- Document list with visualization -->
<div class="document-list">
  <h3>Available Documents</h3>

  <div class="document-item">
    <h4>Annual Report 2023</h4>
    <button onclick="openPDF('report2023.pdf')">View with Accessibility</button>
  </div>

  <div class="document-item">
    <h4>Privacy Policy</h4>
    <button onclick="openPDF('privacy-policy.pdf')">
      View with Accessibility
    </button>
  </div>
</div>

<!-- Container for PDF -->
<div id="pdf-container" style="display: none;">
  <iframe id="pdf-frame" width="100%" height="600px"></iframe>
</div>

<script>
  function openPDF(filename) {
    const container = document.getElementById("pdf-container");
    const frame = document.getElementById("pdf-frame");

    frame.src = `https://yourserver.com/pdfjs-rybena/web/index.html?file=https://yourserver.com/documents/${filename}`;
    container.style.display = "block";
    container.scrollIntoView({ behavior: "smooth" });
  }
</script>

Technical Requirements

  • Same domain: PDF.js and the PDF file must be on the same domain
  • HTTP Server: The plugin needs to be hosted on an accessible web server
  • HTTPS recommended: For better security and compatibility with modern browsers
  • Compatibility: Based on PDF.js Stable (v3.10.111)

PDF.js version: Stable (v3.10.111)

Troubleshooting

Problem: PDF doesn't load

  • Check: If the PDF URL is directly accessible in the browser
  • Confirm: If the PDF is on the same domain as the PDF.js

Problem: Accessibility doesn't work

  • Check: If the browser console shows any errors
  • Confirm: If the rybena.js script is being loaded in the iframe

Problem: CORS errors

  • Solution: Configure CORS headers on the server to allow PDF access
  • Example: Access-Control-Allow-Origin: *

Integration Alternatives

For specific platforms, there are dedicated plugins:

ATTENTION

When providing PDFs to users, you must choose the installed plugin. PDFs inserted in other ways **will not have** integration with Rybená

Modificado em: