Dictionary & Vocabulary Learning
Relevant source files
The following files were used as context for generating this wiki page:
- app/src/main/kotlin/dev/patrickgold/florisboard/ime/dictionary/DictionaryManager.kt
- app/src/main/kotlin/dev/patrickgold/florisboard/ime/dictionary/UserDictionary.kt
- app/src/main/kotlin/dev/patrickgold/florisboard/ime/nlp/latin/LatinLanguageProvider.kt
- app/src/main/kotlin/dev/patrickgold/florisboard/ime/nlp/NlpManager.kt
- app/src/main/kotlin/dev/patrickgold/florisboard/app/settings/dictionary/UserDictionaryScreen.kt
The Dictionary & Vocabulary Learning system in Ownkey Keyboard provides a robust framework for managing user-defined words, shortcuts, and personal language models. It enables the keyboard to offer personalized suggestions and autocorrection based on both system-wide and application-specific user data. This system acts as a primary source of truth for custom linguistic data, supplementing static frequency dictionaries.
Sources: app/src/main/kotlin/dev/patrickgold/florisboard/ime/dictionary/DictionaryManager.kt, app/src/main/kotlin/dev/patrickgold/florisboard/ime/nlp/latin/LatinLanguageProvider.kt
Dictionary Management Architecture
The architecture relies on a centralized DictionaryManager that orchestrates access to multiple dictionary sources. It abstracts the complexities of querying both internal (Floris) and external (System) user dictionaries.
Core Components
DictionaryManager: A singleton class that initializes and maintains database handles. it provides high-level APIs for querying words and shortcuts.UserDictionaryDao: A Data Access Object interface defining standard operations such asquery,insert,update, anddeletefor dictionary entries.FlorisUserDictionaryDatabase: A Room-based implementation for the keyboard's internal local storage.SystemUserDictionaryDatabase: A wrapper around the AndroidUserDictionaryContentProvider, allowing the keyboard to sync with the device's system dictionary.
Sources: app/src/main/kotlin/dev/patrickgold/florisboard/ime/dictionary/DictionaryManager.kt:33-40, app/src/main/kotlin/dev/patrickgold/florisboard/ime/dictionary/UserDictionary.kt:66-70
Dictionary Data Flow
The following diagram illustrates how the DictionaryManager handles queries from the NLP (Natural Language Processing) pipeline.
The DictionaryManager queries all enabled sources simultaneously and converts database entries into WordSuggestionCandidate objects, calculating confidence based on word frequency stored in the database.
Sources: app/src/main/kotlin/dev/patrickgold/florisboard/ime/dictionary/DictionaryManager.kt:62-100
User Dictionary Entry Structure
A UserDictionaryEntry represents a single linguistic unit. Every entry is locale-aware, allowing for language-specific personalization.
| Field | Type | Description |
|---|---|---|
id | Long | Unique identifier (Primary Key). |
word | String | The actual word string to be suggested or checked. |
freq | Int | Frequency/confidence value (Range: 1-255). |
locale | String? | Optional locale tag (e.g., "en-US") or null for all languages. |
shortcut | String? | Optional shortcut string that expands to the word. |
Sources: app/src/main/kotlin/dev/patrickgold/florisboard/ime/dictionary/UserDictionary.kt:47-64
Data Constraints and Defaults
- Minimum Frequency: 1
- Maximum Frequency: 255
- Default Frequency: 128
- Normalization: Frequency values are scaled by
255.0to generate a confidence score between 0.0 and 1.0 for the NLP engine.
Sources: app/src/main/kotlin/dev/patrickgold/florisboard/ime/dictionary/UserDictionary.kt:34-36, app/src/main/kotlin/dev/patrickgold/florisboard/ime/dictionary/DictionaryManager.kt:76
Vocabulary Learning & Promotion
Ownkey Keyboard dynamically learns from user input through a "promotion" mechanism. When a user explicitly accepts a suggestion or types a new word repeatedly, the system increases its frequency in the internal user dictionary.
Personal Vocabulary Promotion Logic
The promotion logic is primarily handled within the LatinLanguageProvider. When a suggestion is accepted:
- The system resolves the best locale for the word.
- It checks for an existing entry in the Floris User Dictionary.
- If the entry exists, its frequency is boosted based on the number of "confirmations" (successful usages).
- If it does not exist, a new entry is created with an initial frequency (defaulting to 160 + boost).
Import and Export Functionality
The UserDictionaryDatabase interface provides methods for importing and exporting personal dictionaries using a semi-colon delimited format. This allows users to back up their vocabulary or migrate it between devices.
File Format Specification
The exported file uses a key-value pair system:
- Header: Contains
dictionary,date,generated-by, andversion. - Entries: Prefixed with space, followed by
w=(word),f=(frequency),l=(locale), ands=(shortcut).
Example format:
dictionary=my-personal-dictionary.clb;date=1625000000000;generated-by=dev.patrickgold.florisboard;version=1
w=example;f=255;l=en-US;s=ex
w=helloworld;f=128;l=null
Sources: app/src/main/kotlin/dev/patrickgold/florisboard/ime/dictionary/UserDictionary.kt:133-195
Validation Rules
The UserDictionaryValidation object defines the strict rules applied when users manually add or edit dictionary entries through the Settings UI.
| Property | Rule / Logic | Error Message (Resource ID) |
|---|---|---|
| Word | Must not be blank; must match ^[^\s;,]+$ | settings__udm__dialog__word_error_invalid |
| Freq | Must be an integer between 1 and 255 | settings__udm__dialog__freq_error_invalid |
| Shortcut | Optional; if present, must match ^[^\s;,]+$ | settings__udm__dialog__shortcut_error_invalid |
| Locale | Optional; must be a valid BCP 47 locale tag | settings__udm__dialog__locale_error_invalid |
Sources: app/src/main/kotlin/dev/patrickgold/florisboard/ime/dictionary/UserDictionary.kt:398-450
NLP Integration
The NlpManager coordinates the LatinLanguageProvider and other providers to integrate user dictionary data into the suggestion pipeline.
- Spell Checking: The
DictionaryManager.spell()function is called to verify if a word exists in custom user dictionaries before flagging it as a typo. - Suggestion Generation: The
queryUserDictionarymethod is invoked to find matches. Shortcuts are prioritized as they often represent intentional user expansions. - Incognito Mode: Vocabulary learning is suppressed when
isIncognitoModeis active, ensuring sensitive or temporary input is not persisted to the dictionary databases.
Sources: app/src/main/kotlin/dev/patrickgold/florisboard/ime/nlp/NlpManager.kt:143-157, app/src/main/kotlin/dev/patrickgold/florisboard/ime/dictionary/DictionaryManager.kt:103-118
Summary
The Dictionary & Vocabulary Learning system is a critical component for keyboard personalization. By combining the device's system dictionary with a private, internal database, Ownkey Keyboard ensures that user-specific linguistic patterns are preserved. The dynamic learning promotion logic enables the keyboard to evolve alongside the user's typing habits, while robust validation and import/export tools provide transparency and control over this data.