Class TranslationService

Service for translating text using Azure Translator cognitive service.

Inheritance

object

TranslationService

Implements

ITranslationService

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Namespace: DataWeb.Localization.AzureTranslator

Assembly: DataWeb.Localization.AzureTranslator.dll

Syntax

public class TranslationService : ITranslationService

Remarks

This service integrates with Microsoft Azure Translator API to provide multilingual translation capabilities. It supports translation rules for custom term translations, HTML content preservation, and placeholder handling. The service applies regex-based transformations to protect specific HTML attributes and placeholders during translation.

Constructors

TranslationService(IConfigurationService, IHttpClientFactory, IAppErrorService, IServiceProvider)

Service for translating text using Azure Translator cognitive service.

Declaration

public TranslationService(IConfigurationService configurationService, IHttpClientFactory httpClientFactory, IAppErrorService appErrorService, IServiceProvider serviceProvider)

Parameters

Type	Name	Description
IConfigurationService	configurationService
IHttpClientFactory	httpClientFactory
IAppErrorService	appErrorService
IServiceProvider	serviceProvider

Remarks

This service integrates with Microsoft Azure Translator API to provide multilingual translation capabilities. It supports translation rules for custom term translations, HTML content preservation, and placeholder handling. The service applies regex-based transformations to protect specific HTML attributes and placeholders during translation.

Methods

GetTranslationRules(TranslationRuleFilter, CancellationToken)

Retrieves translation rules from the configured translation rule store.

Declaration

public Task<IEnumerable<TranslationRule>> GetTranslationRules(TranslationRuleFilter filter, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
TranslationRuleFilter	filter	The filter criteria for retrieving translation rules. Cannot be null.
CancellationToken	cancellationToken	Cancellation token to cancel the operation.

Returns

Type	Description
Task<IEnumerable<TranslationRule>>	A collection of translation rules matching the filter criteria, or an empty collection if no store is configured.

Remarks

Translation rules are used to enforce custom term translations and override the default Azure Translator output. Rules are filtered by culture and can include global rules applicable to all cultures.

Exceptions

Type	Condition
ArgumentNullException	Thrown when filter is null.

TranslateSectionData(IEnumerable<Control>, Dictionary<string, object>, Dictionary<string, object>, string, string, IUser, string, NavigationContext, CancellationToken)

Translates section data for a collection of localization controls.

Declaration

public Task<Dictionary<string, string>> TranslateSectionData(IEnumerable<Control> localizationControls, Dictionary<string, object> sectionData, Dictionary<string, object> sourceSectionData, string culture, string sourceCulture, IUser user, string itemId = null, NavigationContext navigationContext = null, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
IEnumerable<Control>	localizationControls	The collection of localization controls that define which fields to translate. Cannot be null.
Dictionary<string, object>	sectionData	The target dictionary to store translated values. Cannot be null.
Dictionary<string, object>	sourceSectionData	The source dictionary containing original values to translate. Cannot be null.
string	culture	The target culture code for translation (e.g., "it", "it-IT"). Cannot be null.
string	sourceCulture	The source culture code (e.g., "en", "en-US"). Cannot be null.
IUser	user	The user requesting the translation. Cannot be null.
string	itemId	Optional identifier for the item being translated, used in error logging.
NavigationContext	navigationContext	Optional navigation context passed to control's post-translation processing.
CancellationToken	cancellationToken	Cancellation token to cancel the operation.

Returns

Type	Description
Task<Dictionary<string, string>>	A dictionary containing the translated values for each localization control.

Remarks

This method translates content from sourceSectionData into sectionData for the specified culture. Each control specifies which data field to translate. The method applies translation rules, validates character limits, and invokes control-specific post-translation processing via ProcessOnTranslateAsync. The method also sets the "IsAutotranslated" flag if present in the section data.

Exceptions

Type	Condition
ArgumentNullException	Thrown when any required parameter is null.

TranslateValueAsync(string, string, string, TranslationTextType, IEnumerable<TranslationRule>, CancellationToken)

Translates a single text value from source culture to target culture.

Declaration

public Task<string> TranslateValueAsync(string value, string sourceCulture, string targetCulture, TranslationTextType textType = TranslationTextType.Plain, IEnumerable<TranslationRule> translationRules = null, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	value	The text value to translate. Cannot be null.
string	sourceCulture	The source culture code (e.g., "en", "en-US"). Cannot be null.
string	targetCulture	The target culture code for translation (e.g., "it", "it-IT"). Cannot be null.
TranslationTextType	textType	The type of text being translated (Plain, Html, or other). Defaults to Plain.
IEnumerable<TranslationRule>	translationRules	Optional custom translation rules for term substitution.
CancellationToken	cancellationToken	Cancellation token to cancel the operation.

Returns

Type	Description
Task<string>	The translated text value, or null if translation fails.

Exceptions

Type	Condition
ArgumentNullException	Thrown when value, sourceCulture, or targetCulture is null.

TranslateValuesAsync(IEnumerable<string>, string, string, TranslationTextType, IEnumerable<TranslationRule>, CancellationToken)

Translates a collection of text values from source culture to target culture.

Declaration

public Task<IEnumerable<string>> TranslateValuesAsync(IEnumerable<string> values, string sourceCulture, string targetCulture, TranslationTextType textType = TranslationTextType.Plain, IEnumerable<TranslationRule> translationRules = null, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
IEnumerable<string>	values	The collection of text values to translate. Cannot be null.
string	sourceCulture	The source culture code (e.g., "en", "en-US"). Cannot be null.
string	targetCulture	The target culture code for translation (e.g., "it", "it-IT"). Cannot be null.
TranslationTextType	textType	The type of text being translated (Plain, Html, or other). Defaults to Plain.
IEnumerable<TranslationRule>	translationRules	Optional custom translation rules sorted by term length (longest first) for optimal matching.
CancellationToken	cancellationToken	Cancellation token to cancel the operation.

Returns

Type	Description
Task<IEnumerable<string>>	A collection of translated text values in the same order as input values.

Remarks

This method applies custom translation rules before translation and protects HTML attributes (href, alt) and placeholders ({{...}}) by encoding them as Base64. The service uses Azure Translator API for the actual translation. If a character limit (50000 characters) is exceeded, the original value is returned and an error is logged.

Exceptions

Type	Condition
ArgumentNullException	Thrown when values, sourceCulture, or targetCulture is null.
HttpRequestException	Thrown when the Azure Translator API request fails.

Implements

ITranslationService