Feature: Multi-Language Support
Relevant source files
The following files were used as context for generating this wiki page:
- app/src/main/assets/tessdata/README.md
- app/src/main/java/com/musagenius/ocrapp/domain/model/Language.kt
- app/src/main/java/com/musagenius/ocrapp/domain/usecase/GetAvailableLanguagesUseCase.kt
- app/src/main/java/com/musagenius/ocrapp/domain/usecase/CheckLanguageAvailabilityUseCase.kt
- app/src/main/java/com/musagenius/ocrapp/domain/usecase/DeleteLanguageUseCase.kt
- app/src/main/java/com/musagenius/ocrapp/data/ocr/OCRServiceImpl.kt
- app/src/main/java/com/musagenius/ocrapp/domain/model/OCRConfig.kt
- app/src/main/java/com/musagenius/ocrapp/presentation/viewmodel/OCRViewModel.kt
The multi-language support feature enables the application to perform Optical Character Recognition (OCR) on images containing text in various languages. This system is designed for offline use, relying on Tesseract's .traineddata files stored on the device. The architecture provides a clear separation of concerns, with services for core OCR operations, domain models for representing language data, and use cases for managing language files (checking availability, listing, and deleting).
The core of this feature is the OCRServiceImpl, which directly interacts with the Tesseract API. It manages the initialization of the OCR engine for a specific language and handles the on-demand installation of language packs from the app's assets. The domain layer abstracts these operations into clean, reusable use cases, which are then consumed by the presentation layer, such as the OCRViewModel, to drive the user interface.
Architecture and Core Components
The multi-language feature is built upon several key components that interact to provide language selection, processing, and management capabilities.
Component Overview
| Component | Description | Source File |
|---|---|---|
OCRServiceImpl | A singleton service that wraps the TessBaseAPI. It handles OCR engine initialization for a specific language, text recognition, and copying of language data files from assets. | app/src/main/java/com/musagenius/ocrapp/data/ocr/OCRServiceImpl.kt |
Language | A data class representing an OCR language. It includes the language code, a human-readable display name, installation status, and file size. | app/src/main/java/com/musagenius/ocrapp/domain/model/Language.kt |
OCRConfig | A configuration data class for an OCR job. It specifies the language to be used, among other settings like page segmentation mode. | app/src/main/java/com/musagenius/ocrapp/domain/model/OCRConfig.kt |
| Language Use Cases | A set of classes in the domain layer that encapsulate business logic for language management, such as getting, checking, and deleting languages. | app/src/main/java/com/musagenius/ocrapp/domain/usecase/ |
Class Diagram
This diagram illustrates the relationships between the main components of the language support system. The OCRViewModel depends on use cases, which in turn rely on the OCRService. The Language and OCRConfig models are used throughout the architecture to pass data.
Sources: app/src/main/java/com/musagenius/ocrapp/presentation/viewmodel/OCRViewModel.kt, app/src/main/java/com/musagenius/ocrapp/domain/usecase/GetAvailableLanguagesUseCase.kt, app/src/main/java/com/musagenius/ocrapp/data/ocr/OCRServiceImpl.kt, app/src/main/java/com/musagenius/ocrapp/domain/model/Language.kt, app/src/main/java/com/musagenius/ocrapp/domain/model/OCRConfig.kt
Data Models
Language Model
This data class is the primary model for representing a language within the application.
| Field | Type | Description |
|---|---|---|
code | String | The Tesseract language code (e.g., "eng", "fra"). |
displayName | String | The human-readable name of the language (e.g., "English", "French"). |
isInstalled | Boolean | true if the .traineddata file exists on the device. |
fileSize | Long | The size of the .traineddata file in bytes. |
| Source: app/src/main/java/com/musagenius/ocrapp/domain/model/Language.kt:7-16 |
A companion object provides a map of codes to display names and a helper function getDisplayName(code) to retrieve them.
Source: app/src/main/java/com/musagenius/ocrapp/domain/model/Language.kt:18-118
OCRConfig Model
This class holds the configuration for an OCR task. The language property is essential for multi-language support.
data class OCRConfig(
val language: String = "eng",
// ... other properties
) {
fun getTessdataFileName(): String = "$language.traineddata"
}
Source: app/src/main/java/com/musagenius/ocrapp/domain/model/OCRConfig.kt:6-14
Language Data Management
The system manages Tesseract's .traineddata files, which are required for OCR processing. This includes their storage location, installation, and deletion.
Storage
Language data files are stored in a tessdata subdirectory within the application's external files directory. The OCRServiceImpl and DeleteLanguageUseCase both construct this path dynamically.
- Path Logic:
context.getExternalFilesDir(null)+/tessdata/ - Example:
/storage/emulated/0/Android/data/com.musagenius.ocrapp/files/tessdata/eng.traineddata
Sources: app/src/main/java/com/musagenius/ocrapp/data/ocr/OCRServiceImpl.kt:41-44, app/src/main/java/com/musagenius/ocrapp/domain/usecase/DeleteLanguageUseCase.kt:18-21
Installation and Initialization
When an OCR task is initiated, the OCRServiceImpl ensures the required language file is available. If the file does not exist in the tessdata directory, the service attempts to copy it from the app's bundled assets.
This flow diagram shows the logic within OCRServiceImpl.initializeInternal.
The language files must be manually placed in app/src/main/assets/tessdata/ by the developer during development.
Source: app/src/main/assets/tessdata/README.md:3-10
Deletion
The DeleteLanguageUseCase provides the functionality to remove .traineddata files to free up storage.
- It can delete a single language file or multiple files.
- A critical safeguard prevents the deletion of the default English (
eng) language file to ensure baseline functionality.
// From DeleteLanguageUseCase.kt
if (languageCode == "eng") {
return@withContext Result.error(
IllegalArgumentException("Cannot delete default language (English)"),
"Cannot delete default language (English)"
)
}
Source: app/src/main/java/com/musagenius/ocrapp/domain/usecase/DeleteLanguageUseCase.kt:33-38
Domain Layer Use Cases
The business logic for language management is encapsulated in three primary use cases. These classes provide a clean API for the presentation layer to interact with the language system.
| Use Case | Primary Function | Description |
|---|---|---|
GetAvailableLanguagesUseCase | invoke() | Fetches a list of all installed Language objects, including their display name, code, and file size. |
CheckLanguageAvailabilityUseCase | invoke(code) | Checks if a single language's .traineddata file exists. Also provides methods for checking multiple languages. |
DeleteLanguageUseCase | invoke(code) | Deletes a specified language file. Also provides methods for calculating file sizes. |
Sources: app/src/main/java/com/musagenius/ocrapp/domain/usecase/GetAvailableLanguagesUseCase.kt, app/src/main/java/com/musagenius/ocrapp/domain/usecase/CheckLanguageAvailabilityUseCase.kt, app/src/main/java/com/musagenius/ocrapp/domain/usecase/DeleteLanguageUseCase.kt
Sequence Diagram: Getting Available Languages
This diagram shows the sequence of calls when the UI requests a list of installed languages.
Conclusion
The multi-language support in this OCR application is a robust, offline-first system centered around the Tesseract engine. It effectively manages language data files by providing clear logic for their storage, on-demand installation, and deletion. The clean architecture, with its separation into data services, domain use cases, and data models, ensures that language management is maintainable, testable, and easily extensible. The protection of the default English language pack guarantees a functional baseline, while the ability to add and remove other languages provides flexibility and efficient storage management.