FastMCP Todo Server

# Translation & Theme System ## 🎭 Multi-Personality Interface Framework The Omnispindle ecosystem includes a sophisticated translation and theme system that allows users to experience the same functionality through different personality interfaces - inspired by Facebook's classic "pirate mode". --- ## 🎯 Overview ### What It Does The translation system transforms the entire user interface personality while maintaining identical functionality. Users can switch between: 🧙‍♂️ **Mad Wizard** - Mystical laboratory terminology 💼 **Corporate Drone** - Business efficiency language 📝 **Standard** - Clean, neutral interface ### Key Features - **Real-time Theme Switching** - Instant personality changes - **localStorage Persistence** - Remembers user preference - **Fallback System** - Graceful degradation if translations missing - **Development Warnings** - Console alerts for missing keys - **Extensible Architecture** - Easy to add new themes/languages --- ## 🏗️ Architecture ### File Structure ``` src/ ├── locales/ │ ├── themes/ │ │ ├── mad-wizard.json # 🧙‍♂️ Mystical terminology │ │ ├── corporate-drone.json # 💼 Business language │ │ └── standard.json # 📝 Neutral interface │ ├── languages/ # 🌐 Future: actual languages │ └── index.js # Theme registry & metadata ├── contexts/ │ └── LanguageContext.jsx # React Context provider ├── hooks/ │ └── useTranslation.js # Translation hook └── utils/ └── i18n.js # Utility functions ``` ### Core Components #### 1. LanguageProvider (Context) ```jsx import { LanguageProvider } from './contexts/LanguageContext'; // Wrap your app <LanguageProvider> <App /> </LanguageProvider> ``` #### 2. useTranslation Hook ```jsx import useTranslation from './hooks/useTranslation'; function MyComponent() { const { t, currentTheme, switchTheme } = useTranslation(); return ( <div> <h1>{t('createProject.title')}</h1> <button onClick={() => switchTheme('mad-wizard')}> Switch to Mad Wizard </button> </div> ); } ``` #### 3. Translation Function ```jsx // Simple usage t('common.save') // "Save" | "Archive Findings" | "Optimize Data" // With variables t('welcome.message', { name: 'Dr. Tinker' }) // "Welcome, Dr. Tinker!" | "Greetings, Dr. Tinker!" | "Hello, Dr. Tinker" // Pluralization t('items.count', { count: 5 }) // Uses .zero, .one, .other forms automatically ``` --- ## 🎨 Theme Personalities ### 🧙‍♂️ Mad Wizard Theme **Personality**: Mystical scientist with arcane knowledge **Tone**: Academic, mysterious, slightly whimsical **Terminology**: Laboratory, experiments, apparatus, mystical **Examples**: - "Create Project" → "Archive New Endeavors" - "Todo List" → "Research Tasks" - "Settings" → "Laboratory Apparatus Configuration" - "Save" → "Archive Findings" - "Delete" → "Banish to Void" **Use Cases**: Creative professionals, researchers, anyone who enjoys personality in their tools ### 💼 Corporate Drone Theme **Personality**: Peak business efficiency optimization **Tone**: Professional, synergistic, corporate buzzwords **Terminology**: Leverage, optimize, deliverables, productivity **Examples**: - "Create Project" → "Initialize New Initiative" - "Todo List" → "Task Management Dashboard" - "Settings" → "System Optimization Parameters" - "Save" → "Commit Changes" - "Delete" → "Archive Resource" **Use Cases**: Business environments, corporate users, productivity-focused workflows ### 📝 Standard Theme **Personality**: Clean, neutral, straightforward **Tone**: Direct, simple, accessible **Terminology**: Standard UI language **Examples**: - "Create Project" → "Create Project" - "Todo List" → "Todos" - "Settings" → "Settings" - "Save" → "Save" - "Delete" → "Delete" **Use Cases**: Default option, accessibility-focused, minimal distraction preference --- ## 🛠️ Implementation Guide ### Adding Translation to a Component #### Step 1: Import the Hook ```jsx import useTranslation from '../../hooks/useTranslation'; ``` #### Step 2: Use in Component ```jsx function CreateProjectForm() { const { t } = useTranslation(); return ( <form> <h2>{t('createProject.title')}</h2> <input placeholder={t('createProject.namePlaceholder')} /> <button type="submit">{t('createProject.buttons.create')}</button> </form> ); } ``` #### Step 3: Add Keys to All Theme Files **mad-wizard.json**: ```json { "createProject": { "title": "Archive New Endeavors", "namePlaceholder": "Enter experiment designation...", "buttons": { "create": "Begin Investigation" } } } ``` **corporate-drone.json**: ```json { "createProject": { "title": "Initialize New Initiative", "namePlaceholder": "Enter project identifier...", "buttons": { "create": "Deploy Project" } } } ``` **standard.json**: ```json { "createProject": { "title": "Create Project", "namePlaceholder": "Enter project name...", "buttons": { "create": "Create Project" } } } ``` ### Key Naming Conventions ``` component.section.element ├── createProject.title ├── createProject.buttons.save ├── validation.nameRequired ├── common.loading ├── status.pending └── actions.delete ``` **Guidelines**: - Use camelCase for keys - Group by component/feature - Use common. for shared elements - Use validation. for form errors - Use status. for state indicators - Use actions. for user actions --- ## 🎮 User Experience ### Theme Selector Component ```jsx import ThemeSelector from './ThemeSelector'; // Compact version for headers <ThemeSelector compact={true} /> // Full version for settings <ThemeSelector /> ``` ### Switching Themes ```jsx const { switchTheme, currentTheme, availableThemes } = useTranslation(); // Programmatic switching switchTheme('mad-wizard'); // Check current theme console.log(currentTheme); // 'mad-wizard' // Get theme metadata const themeInfo = availableThemes['mad-wizard']; console.log(themeInfo.name); // 'Mad Wizard' console.log(themeInfo.icon); // '🧙‍♂️' ``` ### Persistence - User's theme choice is automatically saved to `localStorage` - Key: `madness-theme` - Persists across browser sessions and page refreshes - Falls back to 'mad-wizard' as default --- ## 🔧 Advanced Features ### Variable Interpolation ```jsx // Template with variables t('welcome.greeting', { name: user.name, projectCount: projects.length }); // In translation file: "welcome": { "greeting": "Welcome back, {{name}}! You have {{projectCount}} active experiments." } ``` ### Pluralization Support ```jsx // Automatic pluralization t('tasks.count', { count: taskCount }); // In translation file: "tasks": { "count": { "zero": "No mystical tasks", "one": "One arcane task", "other": "{{count}} mystical endeavors" } } ``` ### Conditional Content ```jsx // Different content based on user role t(user.isAdmin ? 'admin.dashboard.title' : 'user.dashboard.title'); ``` ### Loading States ```jsx const { isLoading, error, isReady } = useTranslation(); if (isLoading) return <div>Loading themes...</div>; if (error) return <div>Translation error: {error}</div>; if (!isReady) return <div>Initializing interface...</div>; ``` --- ## 🚀 Development Workflow ### Adding New Themes 1. **Create Theme File**: ```bash touch src/locales/themes/pirate-mode.json ``` 2. **Add to Registry**: ```javascript // src/locales/index.js export const AVAILABLE_THEMES = { // ... existing themes 'pirate-mode': { name: 'Pirate Mode', description: 'Ahoy! Seafaring terminology for the high seas', icon: '🏴‍☠️', data: pirateModeTheme } }; ``` 3. **Write Translations**: ```json { "createProject": { "title": "Chart New Voyages", "buttons": { "create": "Set Sail!" } } } ``` ### Testing Themes ```javascript // Development helper const { getAvailableKeys, hasTranslation } = useTranslation(); // Check for missing translations const allKeys = getAvailableKeys(); console.log('Available keys:', allKeys); // Verify specific key exists if (!hasTranslation('newFeature.title')) { console.warn('Missing translation for new feature'); } ``` ### Console Warnings In development mode, the system automatically warns about: - Missing translation keys - Invalid key formats - Theme loading failures - Fallback usage ```console 🎭 Mad Laboratory: Theme switched to 'corporate-drone' ⚠️ Translation key 'newFeature.title' not found in theme 'mad-wizard' ℹ️ Using fallback translation from standard theme for 'newFeature.title' ``` --- ## 🔗 Integration with Omnispindle ### MCP Tool Integration The translation system works seamlessly with Omnispindle's MCP tools: ```javascript // Tools can be theme-aware export const createTodoTool = { name: "create_todo_with_theme", description: "Create a todo with theme-appropriate language", handler: async (params, context) => { const theme = context.userPreferences?.theme || 'standard'; const messages = getThemeMessages(theme); return { success: true, message: messages.todoCreated }; } }; ``` ### API Integration REST endpoints can return theme-appropriate responses: ```javascript // API endpoint app.post('/api/todos', (req, res) => { const theme = req.headers['x-user-theme'] || 'standard'; const todo = createTodo(req.body); res.json({ todo, message: getThemedMessage('todo.created', theme) }); }); ``` ### Real-time Updates Theme changes propagate through MQTT for real-time synchronization: ```javascript // MQTT theme change notification mqtt.publish('user/theme/changed', { userId: user.id, newTheme: 'mad-wizard', timestamp: Date.now() }); ``` --- ## 📊 Performance Considerations ### Bundle Size - Each theme file: ~5-10KB - Total system overhead: ~50KB - Lazy loading: Only active theme in memory - Tree shaking: Unused themes excluded in production ### Runtime Performance - Translation lookup: O(1) hash table access - Variable interpolation: Regex-based, ~1ms per call - Theme switching: ~10ms full UI update - Memory usage: ~2MB for full system ### Optimization Strategies ```javascript // Lazy load themes const loadTheme = async (themeName) => { return import(`./themes/${themeName}.json`); }; // Memoize translation results const memoizedT = useMemo(() => { return createMemoizedTranslation(translations); }, [translations]); // Batch translation updates const batchUpdateTranslations = (updates) => { startTransition(() => { updates.forEach(update => applyTranslation(update)); }); }; ``` --- ## 🔮 Future Enhancements ### Planned Features - **Voice-to-Text Integration** - Speak commands in theme personality - **Dynamic Theme Generation** - AI-generated personality themes - **User-Contributed Themes** - Community theme marketplace - **Context-Aware Translations** - Smart suggestions based on usage - **A11y Enhancements** - Screen reader optimizations per theme ### Language Support The architecture supports real languages in addition to personality themes: ``` src/locales/ ├── themes/ # Personality variants (English-based) │ ├── mad-wizard.json │ └── corporate-drone.json └── languages/ # Actual languages ├── es.json # Spanish ├── fr.json # French └── de.json # German ``` ### API Evolution ```javascript // Future: Multi-dimensional translation t('createProject.title', { theme: 'mad-wizard', // Personality language: 'es', // Language formality: 'formal', // Tone audience: 'technical' // Context }); ``` --- ## 🎉 Conclusion The translation and theme system transforms Omnispindle from a functional tool into a personalized experience. Whether you're a mystical researcher, a corporate efficiency expert, or prefer clean simplicity, the interface adapts to match your personality while maintaining the same powerful functionality underneath. *Because why should productivity tools be boring?* 🎭✨ --- **Next Steps**: - [Theme Development Guide](./THEME_DEVELOPMENT.md) - [Integration Patterns](./INTEGRATION_PATTERNS.md) - [API Reference](./API_REFERENCE.md)