First Time Configuration Wizard¶

Status¶

Implemented

Date¶

2025-11-03

Context¶

OmegaT is a professional computer-assisted translation (CAT) tool that offers extensive configuration options. New users often face challenges during their initial experience:

Overwhelming Configuration: Multiple settings for themes, fonts, and interface preferences without clear guidance
Poor First Impression: Users must navigate complex menus to configure basic settings
Lack of Onboarding: No structured introduction to OmegaT’s philosophy and freedoms
Inconsistent Documentation Styling: Documentation lacks flexible CSS support for different presentation contexts

The application needed a way to:

Guide new users through essential initial configuration
Introduce OmegaT’s philosophy and user freedoms
Provide a welcoming, visually appealing first experience
Allow easy re-access to the wizard when needed

Decision¶

We will implement a First Time Configuration Wizard that addresses the onboarding needs through the following changes:

1. New Package: `org.omegat.gui.firsttime`¶

A dedicated package containing the wizard implementation with components for:

Theme Selection: Allowing users to choose their preferred Look and Feel
Font Configuration: Helping users select appropriate fonts for translation work
Greeting Message: Displaying welcome content and OmegaT philosophy
Philosophy Understanding: Presenting GPL v3.0 freedoms and first steps guide
Step Advice: Providing guidance for configuration steps

Implementation Strategy: The wizard will leverage existing dialog components from org.omegat.gui.dialogs (such as theme and font selection dialogs) to ensure consistency and reduce duplication. This approach provides:

Code Reuse: Proven dialog implementations with existing test coverage
Consistency: UI elements behave identically to their usage elsewhere in OmegaT
Reduced Maintenance: Changes to dialog components automatically benefit the wizard
Quality Assurance: Dialog components are already tested via DialogsTest.java

3. Enhanced Documentation Build System¶

Flexible CSS support for different documentation contexts:

Before: Fixed omegat.css for all documentation After: Parameterized CSS selection allowing:

greeting.css for wizard content (minimal, theme-adaptive)
omegat.css for user manual (comprehensive styling)
Future CSS variants for other contexts

4. Theme-Aware Greeting Styles¶

Introduction of greeting.css with unique characteristics:

No Fixed Colors: Colors are provided dynamically by the wizard View component
Streamlined Design: Minimal CSS focusing on layout and typography
Theme Integration: Adapts to user’s selected theme automatically
Separation of Concerns: Layout in CSS, colors from theme system

Technical Architecture¶

Component Integration¶

┌─────────────────────────────────────┐
│   Help Menu (IMainMenu)             │
│   └─ First Time Wizard MenuItem     │
└──────────────┬──────────────────────┘
               │
               ↓
┌─────────────────────────────────────┐
│   org.omegat.gui.firsttime          │
│   ├─ Wizard Controller              │
│   ├─ Theme Selection Step           │──→ UIDesignManager.setTheme()
│   ├─ Font Selection Step            │──→ FontUtil.createCompositeFont()
│   └─ Greeting Content Display       │
└──────────────┬──────────────────────┘
               │
               ↓
┌─────────────────────────────────────┐
│   Documentation System               │
│   ├─ First_Steps.xml                │
│   ├─ greeting.css (theme-adaptive)  │
│   └─ DocbookHtmlTask (enhanced)     │
└─────────────────────────────────────┘

Build System Enhancement¶

Modified files:

build-logic/src/main/groovy/org/omegat/documentation/DocbookHtmlTask.groovy
- Accepts CSS file parameter instead of hardcoded “omegat.css”
- Supports multiple CSS variants for different documentation types
build-logic/src/main/groovy/org.omegat.document-conventions.gradle
- Updated conventions to support CSS selection

Documentation Content¶

src_docs/greeting/en/First_Steps.xml: Contains welcome message, basic usage steps, and GPL freedoms
src_docs/style/greeting.css: Streamlined stylesheet for wizard display

Consequences¶

Positive¶

✅ Improved User Onboarding: New users receive guided setup for essential configurations

✅ Reusable Components: Leverages existing font and theme selection logic (FontSelectionController, UIDesignManager)

✅ Flexible Documentation System: CSS parameterization enables context-appropriate styling

✅ Philosophy Communication: GPL freedoms and OmegaT philosophy presented upfront

✅ Accessible Re-configuration: Users can revisit wizard via Help menu anytime

✅ Dialog Reuse: Wizard integrates existing dialogs from org.omegat.gui.dialogs, avoiding code duplication

✅ Tested Components: Reused dialogs already have comprehensive test coverage in DialogsTest.java

✅ Professional First Impression: Polished welcome experience enhances brand perception

Negative¶

⚠️ Additional Maintenance: New UI components and package to maintain

⚠️ Build Complexity: Documentation build system now has additional parameterization

⚠️ Testing Overhead: Wizard flow, theme switching, and CSS rendering require testing

⚠️ Localization Burden: All wizard content needs translation for supported languages

⚠️ Potential Feature Creep: Risk of adding too many configuration steps over time

⚠️ Dialog Coupling: Wizard depends on stable APIs of existing dialogs in org.omegat.gui.dialogs

Neutral¶

🔄 First-Launch Detection: Requires tracking mechanism (preference flag)

🔄 CSS Duplication: Two CSS files (omegat.css, greeting.css) serve different purposes

🔄 Documentation Structure: First_Steps.xml serves dual purpose (wizard + standalone doc)

Design Principles¶

1. Minimal Configuration Footprint¶

Focus only on essential configurations:

Theme (visual comfort)
Font (readability for translation work)
Philosophy understanding (user rights and freedoms)

2. Theme-Adaptive Content¶

Greeting CSS has no color definitions
Colors injected from selected theme
Ensures visual consistency with chosen Look and Feel

3. Reusability¶

Leverages existing UIDesignManager.setTheme() for theme application
Uses FontUtil.createCompositeFont() for font configuration – Integrates existing dialogs from org.omegat.gui.dialogs for consistent UI behavior
Avoids code duplication

4. Discoverability¶

Permanent Help menu entry ensures users can always find it
First-launch trigger for new installations
No hidden or buried functionality

Implementation Details¶

Files Modified¶

Core Application:

IMainMenu.java: Add “First Time Wizard” entry to Help menu
New package: org.omegat.gui.firsttime.*

Reused Components:

Dialogs from org.omegat.gui.dialogs: Theme selection, font configuration, and other UI components
Existing controllers: FontSelectionController, theme management logic

Documentation:

src_docs/greeting/en/First_Steps.xml: Welcome content
src_docs/style/greeting.css: New minimal stylesheet

Build System:

build-logic/src/main/groovy/org/omegat/documentation/DocbookHtmlTask.groovy: CSS parameterization
build-logic/src/main/groovy/org.omegat.document-conventions.gradle: Build conventions update

Integration Points¶

Theme System: UIDesignManager.setTheme(String lafClassName)
Font System: FontUtil and FontSelectionController patterns
Documentation: DocBook XML + parameterized CSS
Preferences: Track wizard completion status

Alternatives Considered¶

1. ❌ Inline Configuration in Main Window¶

Approach: Show configuration prompts in the main window on first launch

Rejected: Clutters main UI, poor separation of concerns

2. ❌ Fixed CSS with Theme Overrides¶

Approach: Use single CSS with theme-specific overrides

Rejected: More complex, harder to maintain, conflicts between styles

3. ❌ Web-Based Welcome Page¶

Approach: External HTML page opened in browser

Rejected: Breaks integration, can’t configure application directly, requires internet

4. ❌ Wizard as Separate Application¶

Approach: Standalone wizard application that launches OmegaT

Rejected: Distribution complexity, can’t be re-invoked from Help menu

Migration Strategy¶

For New Users¶

First launch detects absence of configuration flag
Wizard launches automatically before main window
User completes configuration steps
Flag set in preferences: firsttime.wizard.completed=true

For Existing Users¶

Wizard does not auto-launch (flag already exists or migration sets it)
Available via Help → First Time Wizard if desired
No disruption to existing workflows

Future Enhancements¶

Additional wizard steps for advanced features (plugins, TM, dictionaries)
Analytics to track completion rates (if privacy-preserving metrics added)
Video or interactive tutorials within wizard
Theme previews before selection
Font samples with actual translation content

Notes¶

Key Innovation: CSS Parameterization¶

The build system enhancement to accept CSS files as parameters is particularly valuable:

Flexibility: Different documentation contexts can have appropriate styling
Maintainability: Clear separation between wizard styles and manual styles
Extensibility: Future documentation types can define their own CSS

Philosophy First¶

Presenting GPL freedoms in the first-time experience aligns with OmegaT’s Free Software values:

Users understand their rights immediately
Transparent about software freedoms
Builds trust and community alignment