242 lines
No EOL
9.2 KiB
ReStructuredText
242 lines
No EOL
9.2 KiB
ReStructuredText
====================
|
||
Development Journal
|
||
====================
|
||
|
||
July 2, 2025
|
||
============
|
||
|
||
Token Estimator Implementation
|
||
-------------------------------
|
||
|
||
Built `token_estimator.js` - a simplified BPE-based token counter for translation ETA estimation.
|
||
|
||
**Not compatible with tiktoken** - this is estimation-only, ~85% accuracy. Good enough for progress bars, not for exact tokenization.
|
||
|
||
**NVIDIA 4090 Performance Metrics:**
|
||
- Prompt processing: 3,144 tokens/sec
|
||
- Generation: 121 tokens/sec
|
||
- Translation estimates: 1K tokens ≈ 11 seconds
|
||
|
||
The estimator uses real production metrics from our Hermes machine to provide realistic translation timing.
|
||
|
||
July 3, 2025
|
||
============
|
||
|
||
Complete Translation Infrastructure Overhaul
|
||
--------------------------------------------
|
||
|
||
**Modular Language System Implementation**
|
||
|
||
Restructured the entire translation system to use individual language files instead of one monolithic object. Each of the 19 supported languages now has its own dedicated JS file in `/src/languages/`.
|
||
|
||
**Language Coverage:**
|
||
- 🇺🇸 English (en.js) - 46 translation keys
|
||
- 🇨🇳 Chinese Simplified (zh.js)
|
||
- 🇹🇼 Chinese Traditional (zh-tw.js)
|
||
- 🇮🇳 Hindi (hi.js)
|
||
- 🇪🇸 Spanish (es.js)
|
||
- 🇫🇷 French (fr.js)
|
||
- 🇸🇦 Arabic (ar.js)
|
||
- 🇧🇩 Bengali (bn.js)
|
||
- 🇷🇺 Russian (ru.js)
|
||
- 🇧🇷 Portuguese (pt.js)
|
||
- 🇵🇰 Urdu (ur.js)
|
||
- 🇮🇩 Indonesian (id.js)
|
||
- 🇩🇪 German (de.js)
|
||
- 🇯🇵 Japanese (ja.js)
|
||
- 🇰🇪 Swahili (sw.js)
|
||
- 🇮🇳 Marathi (mr.js)
|
||
- 🇮🇳 Telugu (te.js)
|
||
- 🇹🇷 Turkish (tr.js)
|
||
- 🇰🇷 Korean (ko.js)
|
||
|
||
**Dynamic UI Refresh System**
|
||
|
||
Implemented `refreshUILanguage()` function that updates all UI text without requiring browser refresh:
|
||
|
||
- **Declarative translations**: Elements with `data-i18n` attributes automatically update
|
||
- **Parameter support**: `data-i18n-params` for dynamic text with variables like `{lang}` and `{error}`
|
||
- **Smart element detection**: Handles inputs, buttons, placeholders, and modal titles
|
||
- **Event system**: Dispatches `languageChanged` custom events for component integration
|
||
- **Backward compatibility**: Maintains `window.refreshUILanguage` for existing code
|
||
|
||
**Translation Verification System**
|
||
|
||
Created `verify-translations.js` - a Node.js script that ensures translation consistency:
|
||
|
||
- **Key extraction**: Parses JS files to extract translation object keys
|
||
- **Completeness verification**: Compares all languages against English reference
|
||
- **Missing/extra key detection**: Reports inconsistencies with colored console output
|
||
- **Exit codes**: Returns 0 for success, 1 for issues (CI/CD friendly)
|
||
|
||
**Adding New Languages - Workflow:**
|
||
|
||
1. **Before adding**: Run verification to ensure current state is clean
|
||
```bash
|
||
cd /home/fox/git/ai.unturf.com/src/languages
|
||
node verify-translations.js
|
||
```
|
||
Should show: "🎉 All languages have complete translations!"
|
||
|
||
2. **Create new language file**: Copy structure from `en.js`
|
||
```bash
|
||
cp en.js new-lang.js # Replace 'new-lang' with actual language code
|
||
```
|
||
|
||
3. **Translate all values**: Keep the same keys, translate only the string values
|
||
|
||
4. **Update index.js**: Add import and export for the new language
|
||
```javascript
|
||
import { newLang } from "./new-lang.js";
|
||
// Add to UI_TRANSLATIONS object
|
||
```
|
||
|
||
5. **Verify completeness**: Run script again to check for issues
|
||
```bash
|
||
node verify-translations.js
|
||
```
|
||
|
||
6. **Fix any issues**: Script will show missing/extra keys in red
|
||
- Missing keys: Add them with proper translations
|
||
- Extra keys: Remove them or add to English reference if needed
|
||
|
||
7. **Final verification**: Run until you see the success message again
|
||
|
||
**File Structure:**
|
||
```
|
||
src/languages/
|
||
├── index.js # Aggregates all translations
|
||
├── en.js # English reference (46 keys)
|
||
├── [18 other languages] # Complete translations
|
||
└── verify-translations.js # Sanity check script
|
||
```
|
||
|
||
**Benefits:**
|
||
- **Maintainability**: Each language isolated in its own file
|
||
- **Consistency**: 100% key coverage verified across all 19 languages
|
||
- **Real-time UX**: Language switching without page refresh
|
||
- **Developer experience**: Automated verification prevents translation drift
|
||
- **Scalability**: Easy to add new languages following the established pattern
|
||
|
||
This system supports the full user journey from language detection to dynamic interface updates, ensuring a seamless multilingual experience for all Hermes AI users.
|
||
|
||
July 9, 2025
|
||
============
|
||
|
||
Modal CSS Architecture Overhaul & Translation Page Fix
|
||
-------------------------------------------------------
|
||
|
||
**The Problem**
|
||
|
||
User feedback revealed that the PicoCSS version of the UncloseAI modal was filling the entire screen on large laptop displays, which users found jarring. Additionally, translated pages opened in new windows had broken CSS styling, making them unusable.
|
||
|
||
**Root Cause Analysis**
|
||
|
||
Two critical issues were identified:
|
||
|
||
1. **Inconsistent CSS Loading Logic**: Different modal files used different approaches:
|
||
- Some used ``window.UNCLOSEAI_CUSTOM_STYLING`` flag (fragile)
|
||
- Others used actual PicoCSS detection via ``document.querySelector('link[href*="pico"]')`` (robust)
|
||
- Mix of relative paths (``./src/``) and absolute URLs (``https://uncloseai.com/src/``)
|
||
|
||
2. **Modal Sizing Override Issues**: PicoCSS dialog defaults were overriding our modal sizing with ``!important`` declarations
|
||
|
||
**Solution Implementation**
|
||
|
||
**Phase 1: CSS Architecture Refactoring**
|
||
|
||
Moved all inline styles from JavaScript files into two dedicated CSS files:
|
||
|
||
- ``src/uncloseai-modal-builtin.css`` - Clean styles for blog versions without PicoCSS
|
||
- ``src/uncloseai-modal-pico.css`` - Override styles with ``!important`` declarations for PicoCSS sites
|
||
|
||
**Consolidated Modal Styles:**
|
||
- Hermes AI modal (main chat interface)
|
||
- Translation modal (text & page translation)
|
||
- TTS modal (text-to-speech interface)
|
||
- Widget library components (chat widgets, dropdowns)
|
||
|
||
**Phase 2: PicoCSS Override Strategy**
|
||
|
||
Used CSS specificity and ``!important`` declarations to override PicoCSS dialog defaults:
|
||
|
||
```css
|
||
/* Override PicoCSS positioning that sets top:0, left:0, right:0, bottom:0 */
|
||
dialog#uncloseai-embedded-modal[data-theme] {
|
||
position: fixed !important;
|
||
top: 50% !important;
|
||
left: 50% !important;
|
||
transform: translate(-50%, -50%) !important;
|
||
width: 70vw !important;
|
||
max-width: 800px !important;
|
||
height: 90vh !important;
|
||
}
|
||
```
|
||
|
||
**Phase 3: Consistent CSS Loading Pattern**
|
||
|
||
Standardized all modal files to use:
|
||
|
||
1. **PicoCSS Detection**: ``document.querySelector('link[href*="pico"]') !== null``
|
||
2. **Absolute URLs**: ``https://uncloseai.com/src/${cssFile}``
|
||
3. **Proper Mobile Handling**: 480px breakpoint instead of 768px
|
||
|
||
**Phase 4: Translation Page CSS Fix**
|
||
|
||
Fixed broken CSS in translated pages by:
|
||
|
||
1. **Base Tag Approach**: Added ``<base href="${baseUrl}">`` to resolve relative URLs
|
||
2. **Consistent Loading**: Updated translate-modal.js to use the same CSS loading pattern
|
||
3. **Cross-Window Compatibility**: Ensured CSS loads properly in new window contexts
|
||
|
||
**Technical Details**
|
||
|
||
**Files Modified:**
|
||
- ``src/uncloseai-embed-modal.js`` - Main modal CSS loading
|
||
- ``src/translate-modal.js`` - Translation modal CSS loading
|
||
- ``src/tts-modal.js`` - TTS modal CSS loading
|
||
- ``src/widget-library.js`` - Widget CSS loading
|
||
- ``src/translation.js`` - Base tag injection for new windows
|
||
|
||
**CSS Detection Logic:**
|
||
```javascript
|
||
// Detect if PicoCSS is actually present on the page
|
||
const hasPicoCSS = document.querySelector('link[href*="pico"]') !== null;
|
||
|
||
// Load appropriate CSS based on actual PicoCSS presence
|
||
const cssFile = hasPicoCSS ? 'uncloseai-modal-pico.css' : 'uncloseai-modal-builtin.css';
|
||
|
||
if (!document.querySelector(`link[href*="${cssFile}"]`)) {
|
||
const link = document.createElement('link');
|
||
link.rel = 'stylesheet';
|
||
link.href = `https://uncloseai.com/src/${cssFile}`;
|
||
document.head.appendChild(link);
|
||
}
|
||
```
|
||
|
||
**Mobile Responsiveness:**
|
||
- Desktop: Centered modal with 70vw width, 800px max-width
|
||
- Mobile (≤480px): Full-screen modal for touch interfaces
|
||
|
||
**Phase 5: Mobile Experience Restoration**
|
||
|
||
After initial deployment, discovered the mobile experience was broken - modals weren't filling the full screen on mobile devices. Fixed by:
|
||
|
||
1. **Added `!important` declarations** to mobile media query overrides in PicoCSS stylesheet
|
||
2. **Increased mobile breakpoint** from 480px to 768px to properly cover tablets and larger phones
|
||
3. **Updated JavaScript detection** to match CSS breakpoint (768px) for consistency
|
||
|
||
**Final Mobile Responsiveness:**
|
||
- Desktop (>768px): Centered modal with 70vw width, 800px max-width
|
||
- Mobile/Tablet (≤768px): Full-screen modal (100vw × 100vh) for optimal touch experience
|
||
|
||
**Results**
|
||
|
||
✅ **Modal Sizing Fixed**: No more full-screen modals on large displays
|
||
✅ **CSS Architecture Clean**: All inline styles moved to dedicated CSS files
|
||
✅ **Cross-Site Compatibility**: Consistent behavior on blog sites and PicoCSS sites
|
||
✅ **Translation Pages Fixed**: Proper CSS loading in new window contexts
|
||
✅ **Mobile Experience Restored**: Full-screen modals on phones and tablets
|
||
✅ **Developer Experience**: Maintainable CSS architecture with clear separation of concerns
|
||
|
||
This refactoring resolved the immediate user experience issues while establishing a robust, maintainable CSS architecture that prevents similar problems in the future. |