Google Cloud Translation v2 API - Class TranslationClient (3.2.0-beta01)

Version 3.2.0-beta01

• 3.4.0 (latest)
• 3.3.0
• 3.2.0
• 3.1.0
• 3.0.0
• 2.1.0

public abstract class TranslationClient : IDisposable

Reference documentation and code samples for the Google Cloud Translation v2 API class TranslationClient.

Abstract class providing operations for Google Cloud Translation.

Inheritance

Object > TranslationClient

Implements

IDisposable

Inherited Members

Object.GetHashCode()

Object.GetType()

Object.MemberwiseClone()

Object.ToString()

Derived Types

TranslationClientImpl

Namespace

Google.Cloud.Translation.V2

Assembly

Google.Cloud.Translation.V2.dll

Remarks

This abstract class is provided to enable testability while permitting additional operations to be added in the future. See Create(GoogleCredential, TranslationModel), CreateAsync(GoogleCredential, TranslationModel) and CreateFromApiKey(String, TranslationModel) to construct instances; alternatively, you can construct a TranslationClientImpl directly from a TranslateService.

All instance methods declared in this class are virtual, with an implementation which simply throws NotImplementedException. All these methods are overridden in TranslationClientImpl.

This class implements IDisposable; however, the Dispose() method only requires calling if many short-lived instances of TranslationClient are being created. Most code would be expected to create a single TranslationClient instance, and use this instance throughout the lifetime of the application. In this case, Dispose need not be called.

Properties

DefaultModel

public virtual TranslationModel DefaultModel { get; }

The default translation model used by this client.

Property Value
Type	Description
TranslationModel

Remarks

Each Translate method has an optional parameter to override this.

Service

public virtual TranslateService Service { get; }

The underlying translation service object used by this client.

Property Value
Type	Description
TranslateService

Remarks

The TranslationClient class only provides convenience operations built on top of an existing service object. Any more complex operations which are not supported by this wrapper may wish to use the same service object as the wrapper, in order to take advantage of its configuration (for authentication, application naming etc).

Methods

Create()

public static TranslationClient Create()

Synchronously creates a TranslationClient using application default credentials. For any non-default values, please use TranslationClientBuilder.

Returns
Type	Description
TranslationClient

Create(GoogleCredential, TranslationModel)

public static TranslationClient Create(GoogleCredential credential = null, TranslationModel model = TranslationModel.ServiceDefault)

Synchronously creates a TranslationClient, using application default credentials if no credentials are specified.

Parameters
Name	Description
credential	GoogleCredential Optional GoogleCredential. If this is non-null, default scopes are applied to it (for credential types that support scoping), overriding any existing scopes in the credentials. To use scoped credentials without any modifications, create a TranslationClientBuilder and set the Credential property.
model	TranslationModel The default translation model to use. Defaults to ServiceDefault.

Returns
Type	Description
TranslationClient	The created TranslationClient.

Remarks

If a credential is supplied, the default scopes are applied to it (for credential types that support scoping), overriding any existing scopes in the credentials. To use scoped credentials without any modifications, create a TranslationClientBuilder and set the Credential property.

CreateAsync()

public static Task<TranslationClient> CreateAsync()

Asynchronously creates a TranslationClient using application default credentials. For any non-default values, please use TranslationClientBuilder.

Returns
Type	Description
Task<TranslationClient>	The task representing the created TranslationClient.

CreateAsync(GoogleCredential, TranslationModel)

public static Task<TranslationClient> CreateAsync(GoogleCredential credential = null, TranslationModel model = TranslationModel.ServiceDefault)

Asynchronously creates a TranslationClient, using application default credentials if no credentials are specified.

Parameters
Name	Description
credential	GoogleCredential Optional GoogleCredential. If this is non-null, default scopes are applied to it (for credential types that support scoping), overriding any existing scopes in the credentials. To use scoped credentials without any modifications, create a TranslationClientBuilder and set the Credential property.
model	TranslationModel The default translation model to use. Defaults to ServiceDefault.

Returns
Type	Description
Task<TranslationClient>	The task representing the created TranslationClient.

Remarks

If a credential is supplied, the default scopes are applied to it (for credential types that support scoping), overriding any existing scopes in the credentials. To use scoped credentials without any modifications, create a TranslationClientBuilder and set the Credential property.

CreateFromApiKey(String, TranslationModel)

public static TranslationClient CreateFromApiKey(string apiKey, TranslationModel model = TranslationModel.ServiceDefault)

Creates a TranslationClient from an API key instead of using OAuth2 credentials.

Parameters
Name	Description
apiKey	String API key to use. Must not be null.
model	TranslationModel The default translation model to use. Defaults to ServiceDefault.

Returns
Type	Description
TranslationClient	The created TranslationClient.

Remarks

You are encouraged to use OAuth2 credentials where possible. This method is primarily provided to make the transition from using API keys to OAuth2 credentials straightforward.

DetectLanguage(String)

public virtual Detection DetectLanguage(string text)

Detects the language of the specified text synchronously.

Parameter
Name	Description
text	String The text to detect the language of. Must not be null.

Returns
Type	Description
Detection	The most likely detected language.

Remarks

This implementation simply delegates to DetectLanguages(IEnumerable<String>).

Example

TranslationClient client = TranslationClient.Create();
Detection result = client.DetectLanguage("It is raining.");
Console.WriteLine($"Language: {result.Language}; confidence {result.Confidence}");

DetectLanguageAsync(String, CancellationToken)

public virtual async Task<Detection> DetectLanguageAsync(string text, CancellationToken cancellationToken = default(CancellationToken))

Detects the language of the specified text asynchronously.

Parameters
Name	Description
text	String The text to detect the language of. Must not be null.
cancellationToken	CancellationToken The token to monitor for cancellation requests.

Returns
Type	Description
Task<Detection>	The most likely detected language.

Remarks

This implementation simply delegates to DetectLanguagesAsync(IEnumerable<String>, CancellationToken).

Example

TranslationClient client = TranslationClient.Create();
Detection result = await client.DetectLanguageAsync("It is raining.");
Console.WriteLine($"Language: {result.Language}; confidence {result.Confidence}");

DetectLanguages(IEnumerable<String>)

public virtual IList<Detection> DetectLanguages(IEnumerable<string> textItems)

Detects the languages of the specified text items synchronously.

Parameter
Name	Description
textItems	IEnumerable<String> The text items to detect the language of. Must not be null or contain null elements.

Returns
Type	Description
IList<Detection>	A list of detected languages. This will be the same size as textItems, in the same order.

Example

TranslationClient client = TranslationClient.Create();
IList<Detection> results = client.DetectLanguages(new[] { "It is raining.", RainingTranslation });
foreach (var result in results)
{
    Console.WriteLine($"Text: {result.Text}; language: {result.Language}; confidence {result.Confidence}");
}

DetectLanguagesAsync(IEnumerable<String>, CancellationToken)

public virtual Task<IList<Detection>> DetectLanguagesAsync(IEnumerable<string> textItems, CancellationToken cancellationToken = default(CancellationToken))

Detects the languages of the specified text items asynchronously.

Parameters
Name	Description
textItems	IEnumerable<String> The text items to detect the language of. Must not be null or contain null elements.
cancellationToken	CancellationToken The token to monitor for cancellation requests.

Returns
Type	Description
Task<IList<Detection>>	A list of detected languages. This will be the same size as textItems, in the same order.

Example

TranslationClient client = TranslationClient.Create();
IList<Detection> results = await client.DetectLanguagesAsync(new[] { "It is raining.", RainingTranslation });
foreach (var result in results)
{
    Console.WriteLine($"Text: {result.Text}; language: {result.Language}; confidence {result.Confidence}");
}

Dispose()

public virtual void Dispose()

Dispose of this instance. See the TranslationClient remarks on when this should be called.

ListLanguages(String, Nullable<TranslationModel>)

public virtual IList<Language> ListLanguages(string target = null, TranslationModel? model = null)

Lists the language supported by the Translate API synchronously.

Parameters
Name	Description
target	String The target language in which to return the language names in the results, for display purposes. May be null, in which case only the language codes are returned.
model	Nullable<TranslationModel> The model to request languages for. May be null, in which case DefaultModel is used.

Returns
Type	Description
IList<Language>	A list of supported languages.

Example

TranslationClient client = TranslationClient.Create();
IList<Language> languages = client.ListLanguages(LanguageCodes.English);
// Display just the first 10 languages for brevity
foreach (Language language in languages.Take(10))
{
    Console.WriteLine($"Language: {language.Name}; code {language.Code}");
}

ListLanguagesAsync(String, Nullable<TranslationModel>, CancellationToken)

public virtual Task<IList<Language>> ListLanguagesAsync(string target = null, TranslationModel? model = null, CancellationToken cancellationToken = default(CancellationToken))

Lists the language supported by the Translate API asynchronously.

Parameters
Name	Description
target	String The target language in which to return the language names in the results, for display purposes. May be null, in which case only the language codes are returned.
model	Nullable<TranslationModel> The model to request languages for. May be null, in which case DefaultModel is used.
cancellationToken	CancellationToken The token to monitor for cancellation requests.

Returns
Type	Description
Task<IList<Language>>	A list of supported languages.

Example

TranslationClient client = await TranslationClient.CreateAsync();
IList<Language> languages = await client.ListLanguagesAsync(LanguageCodes.English);
// Display just the first 10 languages for brevity
foreach (Language language in languages.Take(10))
{
    Console.WriteLine($"Language: {language.Name}; code {language.Code}");
}

TranslateHtml(IEnumerable<String>, String, String, Nullable<TranslationModel>)

public virtual IList<TranslationResult> TranslateHtml(IEnumerable<string> htmlItems, string targetLanguage, string sourceLanguage = null, TranslationModel? model = null)

Translates multiple items of HTML synchronously.

Parameters
Name	Description
htmlItems	IEnumerable<String> The HTML strings to translate. Must not be null or contain null elements.
targetLanguage	String The code for the language to translate into. Must not be null.
sourceLanguage	String The code for the language to translate from. May be null, in which case the server will detect the source language.
model	Nullable<TranslationModel> The model to request for translation. May be null, in which case DefaultModel is used.

Returns
Type	Description
IList<TranslationResult>	A list of translations. This will be the same size as htmlItems, in the same order.

Remarks

See the Translation API documentation for more details on how to translate HTML and the terms of service.

Example

TranslationClient client = TranslationClient.Create();
IList<TranslationResult> results = client.TranslateHtml(
    new[] { "<p><strong>It is raining.</strong></p>", "<p><strong>It is sunny.</strong></p>" },
    LanguageCodes.French);
foreach (TranslationResult result in results)
{
    Console.WriteLine($"Result: {result.TranslatedText}; detected language {result.DetectedSourceLanguage}");
}

TranslateHtml(String, String, String, Nullable<TranslationModel>)

public virtual TranslationResult TranslateHtml(string html, string targetLanguage, string sourceLanguage = null, TranslationModel? model = null)

Translates a single item of HTML synchronously.

Parameters
Name	Description
html	String The HTML to translate.
targetLanguage	String The code for the language to translate into. Must not be null.
sourceLanguage	String The code for the language to translate from. May be null, in which case the server will detect the source language.
model	Nullable<TranslationModel> The model to request for translation. May be null, in which case DefaultModel is used.

Returns
Type	Description
TranslationResult	The translation of html.

Remarks

This implementation simply delegates to TranslateHtml(IEnumerable<String>, String, String, Nullable<TranslationModel>)

See the Translation API documentation for more details on how to translate HTML and the terms of service.

Example

TranslationClient client = TranslationClient.Create();
TranslationResult result = client.TranslateHtml("<p><strong>It is raining.</strong></p>", LanguageCodes.French);
Console.WriteLine($"Result: {result.TranslatedText}; detected language {result.DetectedSourceLanguage}");

TranslateHtmlAsync(IEnumerable<String>, String, String, Nullable<TranslationModel>, CancellationToken)

public virtual Task<IList<TranslationResult>> TranslateHtmlAsync(IEnumerable<string> htmlItems, string targetLanguage, string sourceLanguage = null, TranslationModel? model = null, CancellationToken cancellationToken = default(CancellationToken))

Translates multiple items of HTML asynchronously.

Parameters
Name	Description
htmlItems	IEnumerable<String> The HTML strings to translate. Must not be null or contain null elements.
targetLanguage	String The code for the language to translate into. Must not be null.
sourceLanguage	String The code for the language to translate from. May be null, in which case the server will detect the source language.
model	Nullable<TranslationModel> The model to request for translation. May be null, in which case DefaultModel is used.
cancellationToken	CancellationToken The token to monitor for cancellation requests.

Returns
Type	Description
Task<IList<TranslationResult>>	A list of translations. This will be the same size as htmlItems, in the same order.

Remarks

See the Translation API documentation for more details on how to translate HTML and the terms of service.

Example

See TranslateHtmlAsync for an example using an alternative overload.

TranslateHtmlAsync(String, String, String, Nullable<TranslationModel>, CancellationToken)

public virtual async Task<TranslationResult> TranslateHtmlAsync(string html, string targetLanguage, string sourceLanguage = null, TranslationModel? model = null, CancellationToken cancellationToken = default(CancellationToken))

Translates a single item of HTML asynchronously.

Parameters
Name	Description
html	String The HTML to translate. Must not be null.
targetLanguage	String The code for the language to translate into. Must not be null.
sourceLanguage	String The code for the language to translate from. May be null, in which case the server will detect the source language.
model	Nullable<TranslationModel> The model to request for translation. May be null, in which case DefaultModel is used.
cancellationToken	CancellationToken The token to monitor for cancellation requests.

Returns
Type	Description
Task<TranslationResult>	The translation of html.

Remarks

This implementation simply delegates to TranslateHtmlAsync(IEnumerable<String>, String, String, Nullable<TranslationModel>, CancellationToken)

See the Translation API documentation for more details on how to translate HTML and the terms of service.

Example

TranslationClient client = await TranslationClient.CreateAsync();
TranslationResult result = await client.TranslateHtmlAsync("<p><strong>It is raining.</strong></p>", LanguageCodes.French);
Console.WriteLine($"Result: {result.TranslatedText}; detected language {result.DetectedSourceLanguage}");

TranslateText(IEnumerable<String>, String, String, Nullable<TranslationModel>)

public virtual IList<TranslationResult> TranslateText(IEnumerable<string> textItems, string targetLanguage, string sourceLanguage = null, TranslationModel? model = null)

Translates multiple items of text synchronously.

Parameters
Name	Description
textItems	IEnumerable<String> The text strings to translate. Must not be null or contain null elements.
targetLanguage	String The code for the language to translate into. Must not be null.
sourceLanguage	String The code for the language to translate from. May be null, in which case the server will detect the source language.
model	Nullable<TranslationModel> The model to request for translation. May be null, in which case DefaultModel is used.

Returns
Type	Description
IList<TranslationResult>	A list of translations. This will be the same size as textItems, in the same order.

Example

TranslationClient client = TranslationClient.Create();
IList<TranslationResult> results = client.TranslateText(
    new[] { "It is raining.", "It is sunny." },
    LanguageCodes.French);
foreach (TranslationResult result in results)
{
    Console.WriteLine($"Result: {result.TranslatedText}; detected language {result.DetectedSourceLanguage}");
}

TranslateText(String, String, String, Nullable<TranslationModel>)

public virtual TranslationResult TranslateText(string text, string targetLanguage, string sourceLanguage = null, TranslationModel? model = null)

Translates a single item of text synchronously.

Parameters
Name	Description
text	String The text to translate.
targetLanguage	String The code for the language to translate into. Must not be null.
sourceLanguage	String The code for the language to translate from. May be null, in which case the server will detect the source language.
model	Nullable<TranslationModel> The model to request for translation. May be null, in which case DefaultModel is used.

Returns
Type	Description
TranslationResult	The translation of text.

Remarks

This implementation simply delegates to TranslateText(IEnumerable<String>, String, String, Nullable<TranslationModel>)

Example

TranslationClient client = TranslationClient.Create();
TranslationResult result = client.TranslateText("It is raining.", LanguageCodes.French);
Console.WriteLine($"Result: {result.TranslatedText}; detected language {result.DetectedSourceLanguage}");

TranslateTextAsync(IEnumerable<String>, String, String, Nullable<TranslationModel>, CancellationToken)

public virtual Task<IList<TranslationResult>> TranslateTextAsync(IEnumerable<string> textItems, string targetLanguage, string sourceLanguage = null, TranslationModel? model = null, CancellationToken cancellationToken = default(CancellationToken))

Translates multiple items of text asynchronously.

Parameters
Name	Description
textItems	IEnumerable<String> The text strings to translate. Must not be null or contain null elements.
targetLanguage	String The code for the language to translate into. Must not be null.
sourceLanguage	String The code for the language to translate from. May be null, in which case the server will detect the source language.
model	Nullable<TranslationModel> The model to request for translation. May be null, in which case DefaultModel is used.
cancellationToken	CancellationToken The token to monitor for cancellation requests.

Returns
Type	Description
Task<IList<TranslationResult>>	A list of translations. This will be the same size as textItems, in the same order.

Example

See TranslateTextAsync for an example using an alternative overload.

TranslateTextAsync(String, String, String, Nullable<TranslationModel>, CancellationToken)

public virtual async Task<TranslationResult> TranslateTextAsync(string text, string targetLanguage, string sourceLanguage = null, TranslationModel? model = null, CancellationToken cancellationToken = default(CancellationToken))

Translates a single item of text asynchronously.

Parameters
Name	Description
text	String The text to translate. Must not be null.
targetLanguage	String The code for the language to translate into. Must not be null.
sourceLanguage	String The code for the language to translate from. May be null, in which case the server will detect the source language.
model	Nullable<TranslationModel> The model to request for translation. May be null, in which case DefaultModel is used.
cancellationToken	CancellationToken The token to monitor for cancellation requests.

Returns
Type	Description
Task<TranslationResult>	The translation of text.

Remarks

This implementation simply delegates to TranslateTextAsync(IEnumerable<String>, String, String, Nullable<TranslationModel>, CancellationToken)

Example

TranslationClient client = await TranslationClient.CreateAsync();
TranslationResult result = await client.TranslateTextAsync("It is raining.", LanguageCodes.French);
Console.WriteLine($"Result: {result.TranslatedText}; detected language {result.DetectedSourceLanguage}");