tractatus/GLOSSARY_TRANSLATION_ISSUES.md

Glossary Translation Issues - Documentation

Date: 2025-11-01

Problem Summary

The German and French glossary translations are displaying incorrectly on the website, despite being properly formatted in the database. The PDF download buttons are also not linking to the correct language-specific PDFs.

Current State

Database (✅ Working)

• Main glossary document (slug: 'glossary'):
  • Has embedded German translation at translations.de
  • Has embedded French translation at translations.fr
  • Each translation has:
    • title: Correct translated title
    • content_html: Properly formatted HTML (tested via API)
    • content_markdown: Source markdown with correct structure
    • toc: Table of contents
    • download_formats.pdf: Language-specific PDF path
      • DE: /downloads/glossary-of-terms-de.pdf (440 KB, accessible)
      • FR: /downloads/glossary-of-terms-fr.pdf (434 KB, accessible)

API Endpoint (✅ Working)

• GET /api/documents/glossary?lang=de returns correct German content
• GET /api/documents/glossary?lang=fr returns correct French content
• Response includes proper download_formats object with PDF path
• HTML content is properly formatted with headings, paragraphs, lists

Frontend Display (❌ BROKEN)

Issue 1: Text Display Problems

Symptoms:

• German text showing but appears to be missing formatting
• Sections are not properly separated
• Headings may not be styled correctly

What User Sees (from console output):

Tractatus Agentic Governance System - Glossary of Terms (Deutsch)

--- ## Kernkonzepte ### Agentic Governance Was es bedeutet: Ein System von Regeln...

Expected:

• Proper heading hierarchy (h1, h2, h3)
• Paragraphs separated with spacing
• Bold text for "Was es bedeutet:", "Warum es wichtig ist:", etc.
• Horizontal rules between sections

Issue 2: PDF Download Button

Symptoms:

• Download button not linking to language-specific PDF
• Button may be using English PDF path instead
• Or button may not be visible at all

Expected:

• When viewing ?doc=glossary&lang=de, download button should point to /downloads/glossary-of-terms-de.pdf
• When viewing ?doc=glossary&lang=fr, download button should point to /downloads/glossary-of-terms-fr.pdf

Investigation Findings

What Was Fixed

1. ✅ Markdown source files restored proper newlines
2. ✅ Database has correctly formatted HTML for all languages
3. ✅ API controller returns translation download_formats
4. ✅ PDF files exist and are accessible
5. ✅ Cache version updated (service worker v0.1.3)

What Might Be Wrong

Hypothesis 1: Frontend Not Using API Response Correctly

File: public/js/docs-app.js

The frontend may be:

• Not detecting the language parameter correctly
• Not using the translated content_html from API response
• Rendering markdown instead of HTML
• Not applying CSS styles to translated content

Lines to investigate:

• docs-app.js:618-789 - loadDocument() function
• docs-app.js:696-758 - Traditional view rendering
• How currentDocument.content_html is being rendered

Hypothesis 2: CSS Not Being Applied

The translated content HTML might be inserted into DOM but:

• Missing wrapper classes (e.g., prose, max-w-none)
• CSS not loaded or scoped incorrectly
• Content being escaped/sanitized incorrectly

Hypothesis 3: PDF Button Using Wrong Path

File: public/js/docs-app.js

Lines 700-714 show PDF path logic:

if (currentDocument.download_formats && currentDocument.download_formats.pdf) {
  pdfPath = currentDocument.download_formats.pdf;
  hasPDF = true;
} else {
  // Fallback logic...
  pdfPath = `/downloads/${currentDocument.slug}.pdf`;
}

For translations:

• currentDocument.slug is still 'glossary' (not 'glossary-de')
• So fallback creates /downloads/glossary.pdf instead of /downloads/glossary-of-terms-de.pdf

Issue: API response has correct path in download_formats.pdf, but frontend might not be reading it properly.

Hypothesis 4: Browser Cache

Despite cache-busting:

• Browser may still have old JavaScript cached
• Service worker may not have updated
• User needs hard refresh (Ctrl+Shift+R)

Technical Context

Document Structure in Database

{
  slug: 'glossary',
  title: 'Tractatus Agentic Governance System - Glossary of Terms',
  content_html: '<h1>...</h1><p>...</p>', // English
  download_formats: { pdf: '/downloads/glossary-of-terms.pdf' },
  translations: {
    de: {
      title: '... (Deutsch)',
      content_html: '<h1>...</h1><p>...</p>', // German - PROPERLY FORMATTED
      content_markdown: '# Title\n\n...',    // German - PROPERLY FORMATTED
      toc: [...],
      download_formats: { pdf: '/downloads/glossary-of-terms-de.pdf' }
    },
    fr: {
      title: '... (Français)',
      content_html: '<h1>...</h1><p>...</p>', // French - PROPERLY FORMATTED
      content_markdown: '# Title\n\n...',     // French - PROPERLY FORMATTED
      toc: [...],
      download_formats: { pdf: '/downloads/glossary-of-terms-fr.pdf' }
    }
  }
}

API Response for Translation

// GET /api/documents/glossary?lang=de
{
  success: true,
  document: {
    slug: 'glossary',
    title: 'Tractatus Agentic Governance System - Glossary of Terms (Deutsch)',
    content_html: '<h1 id="...">...</h1><p>...</p>...', // Properly formatted
    download_formats: { pdf: '/downloads/glossary-of-terms-de.pdf' },
    language: 'de',
    sections: undefined, // Forced to use traditional view
    // ... other fields
  }
}

Debugging Steps Needed

1. Check Network Tab:

   • Is API request going to /api/documents/glossary?lang=de?
   • What is actual response body?

2. Check Console:

   • Any JavaScript errors?
   • What is value of currentDocument.content_html?
   • What is value of currentDocument.download_formats.pdf?

3. Check DOM:

   • View page source - is HTML properly inserted?
   • Inspect element - are styles being applied?
   • Look for class names: prose, max-w-none

4. Hard Refresh:

   • Clear browser cache completely
   • Hard refresh (Ctrl+Shift+R)
   • Try incognito mode

Recommended Fix Approach

Option 1: Debug Frontend JavaScript

Add console logging to docs-app.js:

async function loadDocument(slug, lang = null) {
  // ... existing code ...

  console.log('[DEBUG] Loading document:', slug, 'lang:', lang);
  console.log('[DEBUG] API URL:', apiUrl);
  console.log('[DEBUG] Response:', data);
  console.log('[DEBUG] content_html length:', currentDocument.content_html?.length);
  console.log('[DEBUG] download_formats:', currentDocument.download_formats);

  // ... rest of function
}

Option 2: Verify HTML Rendering

Check if content is being rendered vs. markdown:

// In traditional view section (line ~753)
contentEl.innerHTML = headerHTML + `
  <div class="prose max-w-none">
    ${contentHtml}
  </div>
`;

// Add debug:
console.log('[DEBUG] Rendering HTML:', contentHtml.substring(0, 200));

Option 3: Test PDF Button

Add logging for PDF path resolution:

if (currentDocument.download_formats && currentDocument.download_formats.pdf) {
  pdfPath = currentDocument.download_formats.pdf;
  console.log('[DEBUG] Using download_formats.pdf:', pdfPath);
} else {
  pdfPath = `/downloads/${currentDocument.slug}.pdf`;
  console.log('[DEBUG] Using fallback PDF path:', pdfPath);
}

Files Modified (for reference)

1. docs/markdown/GLOSSARY-DE.md - Fixed markdown formatting
2. docs/markdown/GLOSSARY-FR.md - Fixed markdown formatting
3. Database: documents collection, glossary document - Embedded translations
4. src/controllers/documents.controller.js - Added download_formats to translation response (line 127)
5. public/service-worker.js - Cache version updated
6. 16 HTML files - Cache-busting parameters

Next Steps

1. Get external debugging assistance to identify exact frontend issue
2. Add temporary console logging to track data flow
3. Verify browser cache is cleared
4. Test in incognito mode
5. Check browser developer tools Network and Console tabs

Contact for External Help

Please provide:

• Screenshot of rendered page showing formatting issues
• Browser console output (any errors?)
• Network tab showing API request/response
• DOM inspector showing actual HTML structure
• Browser version and OS