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:
```javascript
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
```javascript
{
  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
```javascript
// 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`:
```javascript
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:
```javascript
// 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:
```javascript
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