Projects › BibleWeb › Commentaries › Dutch commentary translations
In Progress

Dutch commentary translations

Area: Commentaries Milestone: v2

Context

Problem: The Matthew Henry and John Gill commentaries are in English. Dutch-speaking users who prefer a Dutch UI would also prefer Dutch commentary text. While the Kanttekeningen are already in Dutch, the two English sources need translation.

Solution: An AI-powered translation pipeline using Claude Haiku to translate all English commentary entries to Dutch. The translations are stored in the existing text_nl column of the commentaries table. The commentary drawer already supports showing Dutch text when available.

Not included: Human-reviewed translations or professional translation services. These are AI-generated translations meant to provide accessible Dutch commentary — not publication-quality translations.

Functional

When the UI is set to Dutch and Dutch commentary translations are available, the commentary drawer shows the Dutch text instead of English. If a Dutch translation is not yet available for a verse, it shows the English text with a note "(Alleen beschikbaar in het Engels)".

User flow (after translations are run):

  1. User has UI language set to Dutch
  2. Opens commentary drawer on a verse
  3. Sees Dutch translated commentary text
  4. Can still switch to English by changing UI language

Current state:

  • The drawer already handles the Dutch/English fallback logic
  • The text_nl column exists but is empty — 0 out of 57,646 rows have been translated
  • The translation script is built but has never been run

UX & Design

No new UI needed — the CommentaryDrawer already handles the textNl field:

  • When lang === 'nl' and textNl exists → shows Dutch text
  • When lang === 'nl' and textNl is null → shows English with fallback note

Note about Kanttekeningen: The text column for Kanttekeningen already contains Dutch (it's a Dutch commentary). Running the translation script on Kanttekeningen entries would be redundant.

Technical

Database:

  • Column: commentaries.text_nl (TEXT, nullable) — added via scripts/migrate-commentary-nl.sql
  • Current state: all 57,646 rows have text_nl = NULL

Translation script: scripts/translate-commentaries.ts

  • Uses Claude Haiku (claude-haiku-4-5-20251001) via Anthropic SDK
  • Batches: 5 commentaries per API call, 5 concurrent calls
  • Retry logic: handles 429 (rate limit) and 529 (overloaded) with exponential backoff
  • Resumable: only processes WHERE text_nl IS NULL — can be stopped and restarted safely
  • Estimated cost: ~57,600 entries × ~500 tokens avg = ~28.8M tokens

Volumes by source:

Source Entries Notes
John Gill 28,300 English → Dutch translation needed
Kanttekeningen 25,223 Already Dutch — translation redundant
Matthew Henry 4,123 English → Dutch translation needed

Effective translation needed: ~32,423 entries (excluding Kanttekeningen)

Frontend handling (CommentaryDrawer.svelte):

  • Already checks textNl when lang === 'nl'
  • Fallback message: "(Alleen beschikbaar in het Engels)"
  • No code changes needed once translations are populated

Files:

  • scripts/migrate-commentary-nl.sql — column migration (already run)
  • scripts/translate-commentaries.ts — Claude Haiku translation script (built, not run)
  • apps/web/src/lib/components/bible/CommentaryDrawer.svelte — already handles text_nl

Status

Current: IN_PROGRESS Milestone: v2 Priority: Medium — enhances Dutch user experience

What's done:

  • text_nl column added to commentaries table
  • Translation script built with batching, concurrency, retry, and resumability
  • CommentaryDrawer already handles Dutch/English fallback

What remains:

  • Run the translation script (estimated: ~32,423 entries need translation)
  • Filter out Kanttekeningen rows from translation (already Dutch)
  • Verify translation quality on a sample
  • Consider cost implications (~28.8M tokens at Claude Haiku pricing)

History:

  • The text_nl column was added as part of the Dutch localization initiative
  • Translation script uses Claude Haiku for cost efficiency
  • CommentaryDrawer's fallback logic was implemented preemptively

Dependencies:

  • Requires: commentary data (DONE), text_nl column (DONE), Anthropic API key (DONE)
  • Blocks: nothing (English fallback works fine)
← Back to Commentaries features