Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[ReleasePR @azure-rest/ai-translation-text] [AI.TextTranslation] Disambiguate example titles #25596

Closed
wants to merge 1 commit into from
Closed

[ReleasePR @azure-rest/ai-translation-text] [AI.TextTranslation] Disambiguate example titles #25596

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 5 additions & 5 deletions common/config/rush/pnpm-lock.yaml
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

13 changes: 2 additions & 11 deletions sdk/translation/ai-translation-text-rest/CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,12 +1,3 @@
# Release History
## 1.0.0-beta.1 (2023-04-19)

## 1.0.0-beta.1 (2023-04-18)
Initial release

### Features Added
- Added support for Text Translation - [Translate API](https://learn.microsoft.com/azure/cognitive-services/translator/reference/v3-0-translate)
- Added support for Text Transliteration - [Transliterate API](https://learn.microsoft.com/azure/cognitive-services/translator/reference/v3-0-transliterate)
- Added support for Finding Sentence Boundaries - [FindSentenceBoundaries API](https://learn.microsoft.com/azure/cognitive-services/translator/reference/v3-0-break-sentence)
- Added support for Getting the Supported Languages - [GetLanguages API](https://learn.microsoft.com/azure/cognitive-services/translator/reference/v3-0-languages)
- Added support for Looking up the Dictionary Entries - [LookupDictionaryEntries API](https://learn.microsoft.com/azure/cognitive-services/translator/reference/v3-0-dictionary-lookup)
- Added support for Looking up the Dictionary Examples - [LookupDictionaryExamples API](https://learn.microsoft.com/azure/cognitive-services/translator/reference/v3-0-dictionary-examples)
- Initial Release
266 changes: 14 additions & 252 deletions sdk/translation/ai-translation-text-rest/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,271 +22,46 @@ Dictionary example Returns grammatical structure and context examples for the so

Key links:

- [Source code](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/translation/ai-translation-text-rest)
- [Package (NPM)](https://www.npmjs.com/package/@azure-rest/ai-translation-text)
- [API reference documentation](https://learn.microsoft.com/azure/cognitive-services/translator/reference/v3-0-reference)
- [API reference documentation](https://docs.microsoft.com/javascript/api/@azure-rest/ai-translation-text?view=azure-node-preview)
- [Samples](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/translation/ai-translation-text-rest/samples)

## Getting started

### Currently supported environments

- LTS versions of Node.js
- Latest versions of Edge, Chrome, Safar and Firefox

### Prerequisites

- An existing Translator service or Cognitive Services resource.
- You must have an [Azure subscription](https://azure.microsoft.com/free/) to use this package.

### Install the `@azure-rest/ai-translation-text` package

Install the Azure Text Translation REST client library for JavaScript with `npm`:
Install the Azure TextTranslation REST client REST client library for JavaScript with `npm`:

```bash
npm install @azure-rest/ai-translation-text
```

#### Create a Translator service resource
### Create and authenticate a `TextTranslationClient`

You can create Translator resource following [Create a Translator resource][translator_resource_create].
To use an [Azure Active Directory (AAD) token credential](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/identity/identity/samples/AzureIdentityExamples.md#authenticating-with-a-pre-fetched-access-token),
provide an instance of the desired credential type obtained from the
[@azure/identity](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/identity/identity#credentials) library.

### Browser support
To authenticate with AAD, you must first `npm` install [`@azure/identity`](https://www.npmjs.com/package/@azure/identity)

#### JavaScript Bundle
After setup, you can choose which type of [credential](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/identity/identity#credentials) from `@azure/identity` to use.
As an example, [DefaultAzureCredential](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/identity/identity#defaultazurecredential)
can be used to authenticate the client.

To use this client library in the browser, first you need to use a bundler. For details on how to do this, please refer to our [bundling documentation](https://aka.ms/AzureSDKBundling).

### Authenticate the client

Interaction with the service using the client library begins with creating an instance of the [TextTranslationClient][translator_client_class] class. You will need an **API key** or `TokenCredential` to instantiate a client object. For more information regarding authenticating with cognitive services, see [Authenticate requests to Translator Service][translator_auth].

#### Get an API key

You can get the `endpoint`, `API key` and `Region` from the Cognitive Services resource or Translator service resource information in the [Azure Portal][azure_portal].

Alternatively, use the [Azure CLI][azure_cli] snippet below to get the API key from the Translator service resource.

```PowerShell
az cognitiveservices account keys list --resource-group <your-resource-group-name> --name <your-resource-name>
```

### Create a `TextTranslationClient` using an API key and Region credential

Once you have the value for the API key and Region, create an `TranslatorCredential`.

With the value of the `TranslatorCredential` you can create the [TextTranslationClient][translator_client_class]:

```javascript
const translateCedential = new TranslatorCredential(apiKey, region);
const translationClient = TextTranslationClient(endpoint, translateCedential);
```

## Examples

The following section provides several code snippets using the `client` [created above](#create-a-texttranslationclient-using-an-api-key-and-region-credential), and covers the main features present in this client library.

### Get Supported Languages

Gets the set of languages currently supported by other operations of the Translator.

```javascript
const langResponse = await translationClient.path("/languages").get();

if (isUnexpected(langResponse)) {
throw langResponse.body;
}

const languages = langResponse.body;

if (languages.translation) {
console.log("Translated languages:");
for (const key in languages.translation) {
const translationLanguage = languages.translation[key];
console.log(`${key} -- name: ${translationLanguage.name} (${translationLanguage.nativeName})`);
}
}

if (languages.transliteration) {
console.log("Transliteration languages:");
for (const key in languages.transliteration) {
const transliterationLanguage = languages.transliteration[key];
console.log(
`${key} -- name: ${transliterationLanguage.name} (${transliterationLanguage.nativeName})`
);
}
}

if (languages.dictionary) {
console.log("Dictionary languages:");
for (const key in languages.dictionary) {
const dictionaryLanguage = languages.dictionary[key];
console.log(
`${key} -- name: ${dictionaryLanguage.name} (${dictionaryLanguage.nativeName}), supported target languages count: ${dictionaryLanguage.translations.length}`
);
}
}
```

Please refer to the service documentation for a conceptual discussion of [languages][languages_doc].

### Translate

Renders single source-language text to multiple target-language texts with a single request.

```javascript
const inputText = [{ text: "This is a test." }];
const parameters = {
to: "cs",
from: "en",
};
const translateResponse = await translationClient.path("/translate").post({
body: inputText,
queryParameters: parameters,
});

if (isUnexpected(translateResponse)) {
throw translateResponse.body;
}

const translations = translateResponse.body;
for (const translation of translations) {
console.log(
`Text was translated to: '${translation?.translations[0]?.to}' and the result is: '${translation?.translations[0]?.text}'.`
);
}
```

Please refer to the service documentation for a conceptual discussion of [translate][translate_doc].

### Transliterate

Converts characters or letters of a source language to the corresponding characters or letters of a target language.

```javascript
const inputText = [{ text: "这是个测试。" }];
const parameters = {
language: "zh-Hans",
fromScript: "Hans",
toScript: "Latn",
};
const transliterateResponse = await translationClient.path("/transliterate").post({
body: inputText,
queryParameters: parameters,
});

if (isUnexpected(transliterateResponse)) {
throw transliterateResponse.body;
}

const translations = transliterateResponse.body;
for (const transliteration of translations) {
console.log(
`Input text was transliterated to '${transliteration?.script}' script. Transliterated text: '${transliteration?.text}'.`
);
}
```

Please refer to the service documentation for a conceptual discussion of [transliterate][transliterate_doc].

### Break Sentence

Identifies the positioning of sentence boundaries in a piece of text.

```javascript
const inputText = [{ text: "zhè shì gè cè shì。" }];
const parameters = {
language: "zh-Hans",
script: "Latn",
};
const breakSentenceResponse = await translationClient.path("/breaksentence").post({
body: inputText,
queryParameters: parameters,
});

if (isUnexpected(breakSentenceResponse)) {
throw breakSentenceResponse.body;
}

const breakSentences = breakSentenceResponse.body;
for (const breakSentence of breakSentences) {
console.log(`The detected sentece boundaries: '${breakSentence?.sentLen.join(", ")}'.`);
}
```

Please refer to the service documentation for a conceptual discussion of [break sentence][breaksentence_doc].

### Dictionary Lookup

Returns equivalent words for the source term in the target language.

```javascript
const inputText = [{ text: "fly" }];
const parameters = {
to: "es",
from: "en",
};
const dictionaryResponse = await translationClient.path("/dictionary/lookup").post({
body: inputText,
queryParameters: parameters,
});

if (isUnexpected(dictionaryResponse)) {
throw dictionaryResponse.body;
}

const dictionaryEntries = dictionaryResponse.body;
for (const dictionaryEntry of dictionaryEntries) {
console.log(
`For the given input ${dictionaryEntry?.translations?.length} entries were found in the dictionary.`
);
console.log(
`First entry: '${dictionaryEntry?.translations[0]?.displayTarget}', confidence: ${dictionaryEntry?.translations[0]?.confidence}.`
);
}
```

Please refer to the service documentation for a conceptual discussion of [dictionary lookup][dictionarylookup_doc].

### Dictionary Examples

Returns grammatical structure and context examples for the source term and target term pair.

```javascript
const inputText = [{ text: "fly", translation: "volar" }];
const parameters = {
to: "es",
from: "en",
};
const dictionaryResponse = await translationClient.path("/dictionary/examples").post({
body: inputText,
queryParameters: parameters,
});

if (isUnexpected(dictionaryResponse)) {
throw dictionaryResponse.body;
}

const dictionaryExamples = dictionaryResponse.body;
for (const dictionaryExample of dictionaryExamples) {
console.log(
`For the given input ${dictionaryExample?.examples?.length} examples were found in the dictionary.`
);
const firstExample = dictionaryExample?.examples[0];
console.log(
`Example: '${firstExample.targetPrefix + firstExample.targetTerm + firstExample.targetSuffix}'.`
);
}
```

Please refer to the service documentation for a conceptual discussion of [dictionary examples][dictionaryexamples_doc].
Set the values of the client ID, tenant ID, and client secret of the AAD application as environment variables:
AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET

## Troubleshooting

When you interact with the Translator Service using the TextTranslator client library, errors returned by the Translator service correspond to the same HTTP status codes returned for REST API requests.

For example, if you submit a translation request without a target translate language, a `400` error is returned, indicating "Bad Request".

You can find the different error codes returned by the service in the [Service Documentation][service_errors].

### Logging

Enabling logging may help uncover useful information about failures. In order to see a log of HTTP requests and responses, set the `AZURE_LOG_LEVEL` environment variable to `info`. Alternatively, logging can be enabled at runtime by calling `setLogLevel` in the `@azure/logger`:
Expand All @@ -298,16 +73,3 @@ setLogLevel("info");
```

For more detailed instructions on how to enable logs, you can look at the [@azure/logger package docs](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/core/logger).

[azure_cli]: https://docs.microsoft.com/cli/azure
[azure_portal]: https://portal.azure.com
[translator_resource_create]: https://learn.microsoft.com/azure/cognitive-services/Translator/create-translator-resource
[translator_auth]: https://learn.microsoft.com/azure/cognitive-services/translator/reference/v3-0-reference#authentication
[service_errors]: https://learn.microsoft.com/azure/cognitive-services/translator/reference/v3-0-reference#errors
[translator_client_class]: https://github.com/azure/azure-sdk-for-js/blob/main/sdk/translation/ai-translation-text-rest/src/generated/clientDefinitions.ts
[languages_doc]: https://learn.microsoft.com/azure/cognitive-services/translator/reference/v3-0-languages
[translate_doc]: https://learn.microsoft.com/azure/cognitive-services/translator/reference/v3-0-translate
[transliterate_doc]: https://learn.microsoft.com/azure/cognitive-services/translator/reference/v3-0-transliterate
[breaksentence_doc]: https://learn.microsoft.com/azure/cognitive-services/translator/reference/v3-0-break-sentence
[dictionarylookup_doc]: https://learn.microsoft.com/azure/cognitive-services/translator/reference/v3-0-dictionary-lookup
[dictionaryexamples_doc]: https://learn.microsoft.com/azure/cognitive-services/translator/reference/v3-0-dictionary-examples
2 changes: 1 addition & 1 deletion sdk/translation/ai-translation-text-rest/api-extractor.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,4 +28,4 @@
}
}
}
}
}
12 changes: 5 additions & 7 deletions sdk/translation/ai-translation-text-rest/karma.conf.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -53,13 +53,11 @@ module.exports = function (config) {

envPreprocessor: [
"TEST_MODE",
"TEXT_TRANSLATION_TENANT_ID",
"TEXT_TRANSLATION_CLIENT_ID",
"TEXT_TRANSLATION_CLIENT_SECRET",
"TEXT_TRANSLATION_ENDPOINT",
"TEXT_TRANSLATION_CUSTOM_ENDPOINT",
"TEXT_TRANSLATION_API_KEY",
"TEXT_TRANSLATION_REGION",
"ENDPOINT",
"AZURE_CLIENT_SECRET",
"AZURE_CLIENT_ID",
"AZURE_TENANT_ID",
"SUBSCRIPTION_ID",
"RECORDINGS_RELATIVE_PATH",
],

Expand Down
Loading