Detection
Public API for language detection services.
DetectionConfig
Bases: BaseModel
Configuration options for the language detector.
Attributes:
| Name | Type | Description |
|---|---|---|
confidence_threshold |
float
|
Minimum confidence required to accept detection results. |
batch_size |
int
|
Maximum number of texts processed per batch. |
fallback_language |
str | None
|
Language code to return when detection confidence is insufficient. |
max_alternatives |
int
|
Maximum number of alternative detections to return. |
validate_fallback_language(value)
classmethod
Validate optional fallback language code format.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
value |
str | None
|
Optional fallback language code to validate. |
required |
Returns:
| Type | Description |
|---|---|
str | None
|
str | None: Validated fallback language code, or None if no fallback language is specified. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If fallback language code is invalid. |
DetectionResult
Bases: BaseModel
Represents a complete language detection result.
Attributes:
| Name | Type | Description |
|---|---|---|
language |
Language
|
Primary detected language candidate. |
alternatives |
list[Language]
|
Alternative detection candidates sorted by confidence descending. |
is_fallback |
bool
|
Indicates whether the result comes from fallback logic. |
validate_alternatives()
Validate alternative detections ordering, size, and confidence bounds.
Returns:
| Name | Type | Description |
|---|---|---|
DetectionResult |
'DetectionResult'
|
Validated detection result. |
Language
Bases: BaseModel
Represents a single language detection candidate.
Attributes:
| Name | Type | Description |
|---|---|---|
language_code |
str
|
ISO 639-1 language code (e.g., "en"). |
confidence |
float
|
Detection confidence score between 0.0 and 1.0. |
LanguageDetector(config=None, engine=None)
Orchestrates detection workflow using a pluggable DetectionEngine.
Attributes:
| Name | Type | Description |
|---|---|---|
config |
DetectionConfig
|
Detector configuration. |
Initialize the detector with optional configuration.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
config |
DetectionConfig | None
|
Detector configuration to use. Defaults to None. |
None
|
engine |
DetectionEngine | None
|
Detection engine instance. Defaults to None. |
None
|
config: DetectionConfig
property
Return the detector configuration.
Returns:
| Name | Type | Description |
|---|---|---|
DetectionConfig |
DetectionConfig
|
Current detector configuration. |
batch_detect(texts, fallback_language=None, confidence_threshold=None, config=None)
Detect languages for a batch of texts preserving order.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
texts |
list[str]
|
Input texts to evaluate. |
required |
fallback_language |
str | None
|
Fallback language code when detection confidence is low. Defaults to None. |
None
|
confidence_threshold |
float | None
|
Confidence threshold below which fallback is used. Defaults to None. |
None
|
config |
DetectionConfig | None
|
Explicit configuration overrides. Defaults to None. |
None
|
Returns:
| Type | Description |
|---|---|
list[DetectionResult]
|
list[DetectionResult]: Detection outcomes corresponding to the input texts. |
Raises:
| Type | Description |
|---|---|
TypeError
|
If |
ValueError
|
If configuration overrides are invalid. |
detect(text, fallback_language=None, confidence_threshold=None, config=None)
Detect language for a single text using provided overrides.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
text |
str
|
Input text to evaluate. |
required |
fallback_language |
str | None
|
Fallback language code when detection confidence is low. Defaults to None. |
None
|
confidence_threshold |
float | None
|
Confidence threshold below which fallback is used. Defaults to None. |
None
|
config |
DetectionConfig | None
|
Explicit configuration overrides. Defaults to None. |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
DetectionResult |
DetectionResult
|
Detection outcome for the provided text. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If configuration overrides are invalid. |
batch_detect_language(texts, engine='lingua', fallback_language=None, confidence_threshold=None, config=None)
Detect languages for multiple texts preserving input order.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
texts |
list[str]
|
Input texts to detect languages from. |
required |
engine |
str
|
Detection engine to use. Defaults to "lingua". |
'lingua'
|
fallback_language |
str | None
|
Fallback language code when detection confidence is low. Defaults to None. |
None
|
confidence_threshold |
float | None
|
Confidence threshold below which fallback is used. Defaults to None. |
None
|
config |
DetectionConfig | None
|
Detection configuration overriding defaults. Defaults to None. |
None
|
Returns:
| Type | Description |
|---|---|
list[DetectionResult]
|
list[DetectionResult]: Detection outcomes matching the input order. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If an unsupported engine is requested or configuration overrides are invalid. |
detect_language(text, engine='lingua', fallback_language=None, confidence_threshold=None, config=None)
Detect the language for a single text string.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
text |
str
|
Input text to detect language from. |
required |
engine |
str
|
Detection engine to use. Defaults to "lingua". |
'lingua'
|
fallback_language |
str | None
|
Fallback language code when detection confidence is low. Defaults to None. |
None
|
confidence_threshold |
float | None
|
Confidence threshold below which fallback is used. Defaults to None. |
None
|
config |
DetectionConfig | None
|
Detection configuration overriding defaults. Defaults to None. |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
DetectionResult |
DetectionResult
|
Detected language and associated metadata. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If an unsupported engine is requested or configuration overrides are invalid. |