Skip to main content

arolariu.Backend.Domain.Invoices.Brokers.TranslatorBroker

arolariu.Backend.Domain.Invoices​

arolariu.Backend.Domain.Invoices.Brokers.TranslatorBroker Namespace​

Classes​

AzureTranslatorBroker Class​

Azure AI Translation concrete broker that provides best‑effort text translation and language detection services for upstream enrichment pipelines (naming, categorization, UI localization).

public class AzureTranslatorBroker : arolariu.Backend.Domain.Invoices.Brokers.TranslatorBroker.ITranslatorBroker

Inheritance System.Object 🡒 AzureTranslatorBroker

Implements ITranslatorBroker

Remarks​

Role (Broker Standard): Implements ITranslatorBroker by delegating to Azure.AI.Translation.Text.TextTranslationClient. Performs ONLY external service invocation + minimal projection. NO responsibility for: domain validation, caching, throttling, retry / circuit breaker policy, authorization, logging, metrics, or batching.

Authentication: Uses Azure.AzureKeyCredential sourced from CognitiveServicesKey in application options. The Cognitive Services translator API does not support managed identity through the standard Azure.AI.Translation.Text.TextTranslationClient constructor path; a static API key credential is therefore used.

Determinism: Translation output may change over time as underlying models evolve; callers SHOULD NOT rely on exact string stability for idempotent storage decisions (store original text + target locale if persistence required).

Throughput: Each call is a network round trip. High-volume translation SHOULD be centralized in an orchestration layer that batches, parallelizes, and introduces resilience policies (retry with jitter, adaptive rate limiting).

Backlog: Cancellation token support, glossary / custom terminology injection, multi-target fan‑out translation, profanity masking, HTML mode, telemetry decorators (latency, failure classification), and output quality scoring.

Constructors​

AzureTranslatorBroker(IOptionsManager) Constructor​

Initialises the broker with application configuration and builds a Azure.AI.Translation.Text.TextTranslationClient using an API key credential.

public AzureTranslatorBroker(arolariu.Backend.Common.Options.IOptionsManager optionsManager);

Parameters​

optionsManager arolariu.Backend.Common.Options.IOptionsManager

Options source providing CognitiveServicesKey (required) and CognitiveServicesEndpoint.

Exceptions​

System.ArgumentNullException
Thrown when optionsManager is null.

Remarks​

Construction is side‑effect free (no network calls). The client is thread-safe; the broker instance is suitable for scoped or singleton lifetimes depending on broader DI design.

AzureTranslatorBroker(IOptionsManager, HttpClient) Constructor​

Initializes the broker with a custom System.Net.Http.HttpClient transport (primarily for testing or advanced pipeline customization).

public AzureTranslatorBroker(arolariu.Backend.Common.Options.IOptionsManager optionsManager, System.Net.Http.HttpClient httpClient);

Parameters​

optionsManager arolariu.Backend.Common.Options.IOptionsManager

Options source (MUST NOT be null).

httpClient System.Net.Http.HttpClient

Pre-configured HTTP client instance (MUST NOT be null). Caller owns its lifecycle.

Exceptions​

System.ArgumentNullException
Thrown when any dependency is null.

Remarks​

Allows injection of a fake or instrumented HTTP pipeline (e.g. for deterministic integration tests, chaos experiments, or distributed tracing enrichment). All other semantics match the primary constructor.

Methods​

AzureTranslatorBroker.DetectLanguage(string) Method​

Infers the most probable language of the supplied text.

public System.Threading.Tasks.Task<string> DetectLanguage(string text);

Parameters​

text System.String

Text whose language should be identified.

Implements DetectLanguage(string)

Returns​

System.Threading.Tasks.Task<System.String>
Detected BCP‑47 language code (e.g. "en", "ro").

Remarks​

Mechanism: Performs a translation call (target English) and inspects the detected language metadata returned with the translation batch.

Limitations: Very short or mixed-language inputs may yield low-confidence or generic results; confidence score is not currently exposed.

AzureTranslatorBroker.Translate(string, string) Method​

Translates source text into a target locale (default: English).

public System.Threading.Tasks.Task<string> Translate(string text, string language="en");

Parameters​

text System.String

Source text to translate.

language System.String

Target BCP‑47 language code (e.g. "en", "ro", "de").

Implements Translate(string, string)

Returns​

System.Threading.Tasks.Task<System.String>
Translated text or empty string if none returned.

Remarks​

API Call: Single request to Azure Translation service. No batching or caching performed.

Fallback: Returns empty string when translation array is unexpectedly empty (graceful degradation pattern).

Validation: Caller SHOULD ensure text is non-empty; this method does not trim or sanitize.

Interfaces​

ITranslatorBroker Interface​

Thin text translation + language identification broker abstraction over Azure AI Translation service.

public interface ITranslatorBroker

Derived
↳ AzureTranslatorBroker

Remarks​

Role (Broker Standard): Wraps a single external SDK (TextTranslationClient) and exposes primitive translation and language detection operations. NO business validation, persistence, authorization, throttling, caching, or retry policy (added upstream).

Determinism: Translation output may evolve as provider models update; callers SHOULD NOT depend on exact phrase stability for storage-based idempotency (recommend storing original text and performing on-demand translation or caching with version tags).

Character Handling: Unicode input is accepted as-is. No normalization (NFC/NFD) or HTML entity decoding is performed (backlog feature).

Error Semantics: Argument null/empty SHOULD produce System.ArgumentException in implementations; provider exceptions (network/auth/service) bubble for higher resilience layer handling.

Performance: Each call results in a network round trip. High-volume batch translation SHOULD be handled by an orchestration facade (parallelization + rate limiting). Future optimization: introduce bulk methods to reduce per-call overhead.

Backlog: Cancellation tokens, domain-aware profanity masking, glossary injection, multi-target locale fan-out, and metrics instrumentation.

Methods​

ITranslatorBroker.DetectLanguage(string) Method​

Detects the most probable language for a given text sample.

System.Threading.Tasks.Task<string> DetectLanguage(string text);

Parameters​

text System.String

Source text whose language should be inferred.

Returns​

System.Threading.Tasks.Task<System.String>
Detected BCP‑47 language tag (e.g. "en", "ro").

Remarks​

Heuristics: Underlying service may require minimum character length for high confidence. Very short inputs may return generic or unexpected codes.

Stability: Detection confidence is not surfaced here (future enhancement: return composite result including score).

ITranslatorBroker.Translate(string, string) Method​

Translates raw user/domain text into a target BCP‑47 language (default: English).

System.Threading.Tasks.Task<string> Translate(string text, string language="en");

Parameters​

text System.String

Source text to translate (SHOULD NOT be null or empty).

language System.String

Target locale code (BCP‑47, e.g. "en", "ro", "de"). Defaults to "en".

Returns​

System.Threading.Tasks.Task<System.String>
Translated text (may be empty on graceful degradation strategy).

Remarks​

Mutation: Pure function; returns a translated string (empty string on provider partial failure may be an implementation choice).

Safety: Caller SHOULD trim or sanitize input prior to translation if required (this method does not escape or filter content).

Fallback: Implementations MAY return empty string on provider fault; upstream layers SHOULD treat empty output as non-fatal.

// was this page useful?