deepl-christina/README.md

Scheer Enterprise Translation Tool

A web tool connecting to the DeepL API (Growth plan) for text, document and PDF translation, plus token-optimized JSON translation, with per-domain glossaries for Scheer Group, Scheer IDS, Scheer PAS, and Scheer IMC.

Supported languages everywhere in the tool: German, German (Swiss), English (British), English (American), and French.

Why there's a small server involved

DeepL's API blocks direct calls from browser JavaScript (CORS) and your key should never be embedded in public front-end code. server.js is a tiny zero-dependency Node proxy: it serves the UI and relays requests to DeepL using an API key configured only on the server. The key never touches the browser, localStorage, or any client-side code.

Local setup (single user, on your own machine)

1. Requires Node.js 18+ (uses built-in fetch/FormData/Blob — no npm install needed).
2. Get your DeepL Growth API key from your DeepL account (developer/API settings).
3. Copy .env.example to .env in this folder and set DEEPL_API_KEY=.... (Alternatively, export it as a real environment variable: DEEPL_API_KEY=xxx node server.js.)
4. Run:

   node server.js
   

5. Open http://localhost:3000. The usage indicator in the top-right corner of the header loads automatically (click the ↻ next to it to refresh anytime) and confirms the server is connected to DeepL.

Deploying for shared, multi-user access on a real domain

To make this available to everyone in the org at a URL like https://translate.yourcompany.com instead of just localhost, you need three things: a server to run it on, a domain pointed at that server, and a way to keep it running. None of this requires code changes — server.js already listens on all network interfaces, not just localhost.

1. Get a server. Any internal VM, cloud instance, or on-prem box that can stay running and is reachable from wherever your users are (office network, VPN, or the public internet, depending on your needs).
2. Point your domain at it. Create a DNS A/AAAA record for translate.yourcompany.com pointing at that server's IP.
3. Put a reverse proxy in front of it (e.g. Nginx or Caddy) to handle HTTPS and forward requests to the Node app on port 3000. Caddy is the simplest option — a Caddyfile with just:

   translate.yourcompany.com {
       reverse_proxy localhost:3000
   }
   

   gets you automatic HTTPS via Let's Encrypt with no extra config.
4. Keep the Node process running with a process manager or container instead of a terminal session — see the Docker option below, or use something like pm2 or a systemd service if you'd rather run it bare.
5. Configure .env and domains.json once, on that server — every user hitting the domain shares the same DeepL key and the same four domain glossaries. That's the intended design: one shared quota, one shared set of glossaries per Scheer entity, managed centrally.

Running it in Docker

docker build -t scheer-translation-tool .

# domains.json needs to exist before the bind mount below, otherwise Docker
# will create it as a directory instead of a file:
touch domains.json

docker run -d --name scheer-translation \
  -p 3000:3000 \
  --env-file .env \
  -v "$(pwd)/domains.json:/app/domains.json" \
  --restart unless-stopped \
  scheer-translation-tool

Then point your reverse proxy at localhost:3000 on that host as described above. --restart unless-stopped makes it survive reboots.

Important: this tool has no built-in login

Anyone who can reach the domain can translate documents (consuming your shared DeepL quota) and edit any domain's glossary — there's no user authentication built in. Depending on your needs:

• Restrict it to your internal network or VPN (don't expose it on the public internet), and/or
• Add HTTP Basic Auth at the reverse proxy layer (a couple of lines in Nginx or Caddy), and/or
• Put it behind whatever SSO/gateway your org already uses for internal tools.

Features

• Text Translation — free text in/out, placeholder protection ({{var}}, %s, {id} preserved verbatim), auto-detect or manual source language.
• Document Translation — upload .docx/.pptx/.xlsx/.pdf/.txt/.html, tracks DeepL's upload → poll → download flow, gives you a translated file to download.
• PDF Translation — same upload → poll → download flow, dedicated to PDFs, with the full language selection.
• JSON Translation — paste or upload JSON, only extracts and translates user-facing string values (skips keys, numbers, booleans, nulls, URLs, HTML/code, template tags, and key-like identifiers such as status_code_404), batches everything into as few DeepL requests as possible, and reconstructs the exact tree. Shows a stats panel (values scanned/sent/skipped, character savings).
• Domain glossaries — a domain bar at the top of every page (always visible, independent of which tab you're on) lets you pick one of the four Scheer entities: Scheer Group, Scheer IDS, Scheer PAS, Scheer IMC. Each domain stores two fixed-direction glossaries: German → English and English → German, each with its own list of exact term pairs, created via DeepL's glossary API. Click ⚙ Domain settings to manage the currently selected domain's two term lists. Every translate action (text, document, PDF, JSON) automatically applies the matching direction's glossary and shows a note confirming it was applied.

How glossaries are stored (and why everyone sees the same ones)

Glossary terms are not stored in the browser (no localStorage, no per-user data). Saving a term list calls DeepL's glossary API to create the actual glossary on DeepL's servers, and the server writes the resulting glossary ID plus a local copy of the terms to domains.json — a JSON file that lives next to server.js on whichever machine is running the server. Every request from every browser goes through that one server, which reads the same domains.json, so anyone visiting the site sees and edits the same shared German→English and English→German lists per domain. The settings modal also re-fetches from the server each time it's opened, so you'll see another teammate's most recent edits rather than a stale local copy.

For a small internal tool with a handful of admins editing glossaries occasionally, a flat JSON file is a reasonable, low-maintenance choice — there's no database to run or back up. If this ever needs to support many people editing glossaries concurrently, or an audit trail of who changed what, that would be the point to move domains.json into a real database.

Known limitations

• JSON skip rules are heuristic (regex-based). Always review the output panel before shipping translated JSON to production.
• Glossaries are recreated (not edited in place) on every save. DeepL's v2 glossaries are immutable, so saving a domain's German→English or English→German list deletes the old one and creates a new one with the full term list.
• Only these two directions are supported for glossaries. A glossary only applies to a translation when the request is going exactly German→English or English→German with an explicit (non-auto-detect) source language — the glossary API requires the source language to be set.

Files

• server.js — proxy server (no external dependencies), reads DEEPL_API_KEY from .env/environment
• index.html — the single-page UI (styled with the Scheer brand palette: red, black, greys, whitespace)
• domains.json — auto-created on first run; stores each domain's two glossary IDs/metadata (see storage section above)
• .env.example — copy to .env and fill in your key
• package.json — for npm start convenience (nothing to install)
• Dockerfile, .dockerignore — for containerized deployment (see above)