AI 原生开放教材

外观

Microsoft Agent Skills技能与配置库·英文原文 ↗原件 ↓仓库 ↗

Azure AI Text Translation SDK Acceptance Criteria ​

SDK: azure-ai-translation-textRepository: https://github.com/Azure/azure-sdk-for-pythonPurpose: Skill testing acceptance criteria for validating generated code correctness

1. Correct Import Patterns ​

1.1 Client Imports ​

✅ CORRECT: Sync Client with API Key and Region ​

python
from azure.ai.translation.text import TextTranslationClient
from azure.core.credentials import AzureKeyCredential

✅ CORRECT: Sync Client with API Key and Endpoint ​

python
from azure.ai.translation.text import TextTranslationClient
from azure.core.credentials import AzureKeyCredential
python
from azure.ai.translation.text import TextTranslationClient
from azure.identity import DefaultAzureCredential

✅ CORRECT: Async Client ​

python
from azure.ai.translation.text.aio import TextTranslationClient
from azure.identity.aio import DefaultAzureCredential

1.2 Model Imports ​

✅ CORRECT: DictionaryExample Models ​

python
from azure.ai.translation.text.models import DictionaryExampleTextItem

1.3 Anti-Patterns (ERRORS) ​

❌ INCORRECT: Wrong credential type ​

python
# WRONG - using wrong credential class
from azure.identity import ServicePrincipalCredential

client = TextTranslationClient(credential=ServicePrincipalCredential(...))

❌ INCORRECT: Missing region or endpoint ​

python
# WRONG - no region specified with AzureKeyCredential
credential = AzureKeyCredential(key)
client = TextTranslationClient(credential=credential)

❌ INCORRECT: Mixing sync and async ​

python
# WRONG - using sync client from async code
from azure.ai.translation.text import TextTranslationClient
from azure.identity.aio import DefaultAzureCredential

async def translate():
    client = TextTranslationClient(...)  # Should use .aio

2. Client Creation Patterns ​

2.1 ✅ CORRECT: With API Key and Region ​

python
from azure.ai.translation.text import TextTranslationClient
from azure.core.credentials import AzureKeyCredential
import os

key = os.environ["AZURE_TRANSLATOR_KEY"]
region = os.environ["AZURE_TRANSLATOR_REGION"]

client = TextTranslationClient(credential=AzureKeyCredential(key), region=region)

2.2 ✅ CORRECT: With API Key and Endpoint ​

python
from azure.ai.translation.text import TextTranslationClient
from azure.core.credentials import AzureKeyCredential
import os

endpoint = os.environ["AZURE_TRANSLATOR_ENDPOINT"]
key = os.environ["AZURE_TRANSLATOR_KEY"]

client = TextTranslationClient(endpoint=endpoint, credential=AzureKeyCredential(key))

2.3 ✅ CORRECT: With Entra ID (Recommended) ​

python
from azure.ai.translation.text import TextTranslationClient
from azure.identity import DefaultAzureCredential
import os

endpoint = os.environ["AZURE_TRANSLATOR_ENDPOINT"]
credential = DefaultAzureCredential()

client = TextTranslationClient(endpoint=endpoint, credential=credential)

2.4 ✅ CORRECT: Async Client ​

python
from azure.ai.translation.text.aio import TextTranslationClient
from azure.identity.aio import DefaultAzureCredential
import os

async with TextTranslationClient(
    endpoint=os.environ["AZURE_TRANSLATOR_ENDPOINT"],
    credential=DefaultAzureCredential(),
) as client:
    result = await client.translate(body=["Hello"], to=["es"])

2.5 Anti-Patterns (ERRORS) ​

❌ INCORRECT: Wrong parameter names ​

python
# WRONG - using 'url' instead of 'endpoint'
client = TextTranslationClient(url=endpoint, credential=credential)

# WRONG - using 'key' instead of credential object
client = TextTranslationClient(key=key, region=region)

❌ INCORRECT: Hardcoded credentials ​

python
# WRONG - credentials hardcoded
client = TextTranslationClient(
    credential=AzureKeyCredential("abc123..."),
    region="eastus"
)

❌ INCORRECT: Missing context manager for async ​

python
# WRONG - not using context manager
client = TextTranslationClient(endpoint=endpoint, credential=credential)
result = await client.translate(body=["Hello"], to=["es"])
# Missing cleanup

3. Text Translation Patterns ​

3.1 ✅ CORRECT: Single Language Translation ​

python
result = client.translate(
    body=["Hello, world!"],
    to=["es"]  # Spanish
)

for item in result:
    for translation in item.translations:
        print(f"Translated: {translation.text}")

3.2 ✅ CORRECT: Multiple Language Translation ​

python
result = client.translate(
    body=["Hello, world!"],
    to=["es", "fr", "de"]  # Spanish, French, German
)

for item in result:
    for translation in item.translations:
        print(f"{translation.to}: {translation.text}")

3.3 ✅ CORRECT: With Source Language Specified ​

python
result = client.translate(
    body=["Bonjour le monde"],
    from_parameter="fr",  # Note: 'from_parameter' not 'from'
    to=["en", "es"]
)

3.4 ✅ CORRECT: Batch Translation ​

python
# Up to 100 texts per request
texts = ["Hello", "Good morning", "How are you?"]

result = client.translate(
    body=texts,
    to=["es"]
)

for item in result:
    print(item.translations[0].text)

3.5 ✅ CORRECT: With Translation Options ​

python
result = client.translate(
    body=["<p>Hello, world!</p>"],
    to=["es"],
    text_type="html",                # "plain" or "html"
    profanity_action="Marked",       # "NoAction", "Deleted", "Marked"
    profanity_marker="Asterisk",     # "Asterisk", "Tag"
    include_alignment=True,
    include_sentence_length=True
)

3.6 Anti-Patterns (ERRORS) ​

❌ INCORRECT: Wrong parameter name for source language ​

python
# WRONG - 'from' is a Python keyword
result = client.translate(body=["Hello"], to=["es"], from="en")

Fix: Use from_parameter instead of from, since from is a reserved Python keyword. This parameter specifies the source language code.

python
result = client.translate(body=["Hello"], to=["es"], from_parameter="en")

❌ INCORRECT: String instead of list for to parameter ​

python
# WRONG - 'to' must be a list
result = client.translate(body=["Hello"], to="es")

Fix: The to parameter must always be a list of target language codes, even if translating to a single language. This allows the SDK to handle batch translations to multiple languages in a single request.

python
result = client.translate(body=["Hello"], to=["es"])

❌ INCORRECT: Not accessing translations correctly ​

python
# WRONG - accessing text directly
for item in result:
    print(item.text)  # This won't work

Fix: Each item in the result is a translation item that contains a list of translations objects. You must iterate through the translations list to access the translated text. Each translation object has to, text, and other fields.

python
for item in result:
    for translation in item.translations:
        print(translation.text)

4. Language Detection Patterns ​

4.1 ✅ CORRECT: Basic Language Detection ​

python
result = client.translate(
    body=["Hola, como estas?"],
    to=["en"]
)

for item in result:
    if item.detected_language:
        print(f"Detected: {item.detected_language.language}")
        print(f"Confidence: {item.detected_language.score:.2f}")

4.2 ✅ CORRECT: Using Detect Method ​

python
result = client.detect(body=["Bonjour"])

for item in result:
    print(f"Language: {item.language}")
    print(f"Confidence: {item.score}")

4.3 Anti-Patterns (ERRORS) ​

❌ INCORRECT: Not checking for None ​

python
# WRONG - detected_language might be None
language = result[0].detected_language.language

Fix: The detected_language field can be None if the API cannot confidently detect the language. Always check before accessing its properties. This prevents AttributeError when the language is undetected.

python
if result[0].detected_language:
    language = result[0].detected_language.language

5. Transliteration Patterns ​

5.1 ✅ CORRECT: Basic Transliteration ​

python
result = client.transliterate(
    body=["konnichiwa"],
    language="ja",
    from_script="Latn",  # Latin script
    to_script="Jpan"     # Japanese script
)

for item in result:
    print(f"Transliterated: {item.text}")
    print(f"Script: {item.script}")

5.2 ✅ CORRECT: Language Code with Script Conversion ​

python
result = client.transliterate(
    body=["Привет"],
    language="ru",
    from_script="Cyrl",  # Cyrillic
    to_script="Latn"     # Latin
)

5.3 Anti-Patterns (ERRORS) ​

❌ INCORRECT: Invalid script codes ​

python
# WRONG - script codes don't exist
result = client.transliterate(
    body=["hello"],
    language="en",
    from_script="Latin",   # Should be "Latn"
    to_script="Arabic"     # Should be "Arab"
)

6. Dictionary Lookup Patterns ​

6.1 ✅ CORRECT: Basic Dictionary Lookup ​

python
result = client.lookup_dictionary_entries(
    body=["fly"],
    from_parameter="en",
    to="es"
)

for item in result:
    print(f"Source: {item.normalized_source}")
    for translation in item.translations:
        print(f"  {translation.normalized_target}")
        print(f"  Part of speech: {translation.pos_tag}")
        print(f"  Confidence: {translation.confidence}")

6.2 ✅ CORRECT: Dictionary Examples ​

python
from azure.ai.translation.text.models import DictionaryExampleTextItem

result = client.lookup_dictionary_examples(
    body=[DictionaryExampleTextItem(text="fly", translation="volar")],
    from_parameter="en",
    to="es"
)

for item in result:
    for example in item.examples:
        print(f"Source: {example.source_prefix}{example.source_term}{example.source_suffix}")
        print(f"Target: {example.target_prefix}{example.target_term}{example.target_suffix}")

6.3 Anti-Patterns (ERRORS) ​

❌ INCORRECT: Wrong model for examples ​

python
# WRONG - using strings instead of DictionaryExampleTextItem
result = client.lookup_dictionary_examples(
    body=[{"text": "fly", "translation": "volar"}],
    from_parameter="en",
    to="es"
)

Fix: The lookup_dictionary_examples method requires the body parameter to be a list of DictionaryExampleTextItem objects, not dictionaries or strings. This ensures proper serialization and API compatibility.

python
from azure.ai.translation.text.models import DictionaryExampleTextItem

result = client.lookup_dictionary_examples(
    body=[DictionaryExampleTextItem(text="fly", translation="volar")],
    from_parameter="en",
    to="es"
)

7. Sentence Breaking Patterns ​

7.1 ✅ CORRECT: Find Sentence Boundaries ​

python
result = client.find_sentence_boundaries(
    body=["Hello! How are you? I hope you are well."],
    language="en"
)

for item in result:
    print(f"Sentence lengths: {item.sent_len}")

7.2 Anti-Patterns (ERRORS) ​

❌ INCORRECT: Missing language parameter ​

python
# WRONG - language is required
result = client.find_sentence_boundaries(
    body=["Hello! How are you?"]
)

8. Supported Languages Patterns ​

8.1 ✅ CORRECT: Get All Supported Languages ​

python
languages = client.get_supported_languages()

# Translation languages
for code, lang in languages.translation.items():
    print(f"{code}: {lang.name} ({lang.native_name})")

# Transliteration languages
for code, lang in languages.transliteration.items():
    print(f"{code}: {lang.name}")

# Dictionary languages
for code, lang in languages.dictionary.items():
    print(f"{code}: {lang.name}")

8.2 ✅ CORRECT: Caching Languages ​

python
# Cache languages to avoid repeated API calls
supported_languages = client.get_supported_languages()

def get_translation_languages():
    return supported_languages.translation

def is_supported(lang_code):
    return lang_code in supported_languages.translation

9. Async Patterns ​

9.1 ✅ CORRECT: Full Async Example ​

python
import asyncio
from azure.ai.translation.text.aio import TextTranslationClient
from azure.identity.aio import DefaultAzureCredential
import os

async def main():
    async with TextTranslationClient(
        endpoint=os.environ["AZURE_TRANSLATOR_ENDPOINT"],
        credential=DefaultAzureCredential(),
    ) as client:
        result = await client.translate(
            body=["Hello, world!"],
            to=["es", "fr"]
        )
        
        for item in result:
            for translation in item.translations:
                print(f"{translation.to}: {translation.text}")

asyncio.run(main())

9.2 ✅ CORRECT: Batch Processing with Async ​

python
async def translate_batch(texts, target_lang):
    async with TextTranslationClient(
        endpoint=os.environ["AZURE_TRANSLATOR_ENDPOINT"],
        credential=DefaultAzureCredential(),
    ) as client:
        result = await client.translate(
            body=texts,
            to=[target_lang]
        )
        
        translations = []
        for item in result:
            translations.append(item.translations[0].text)
        return translations

9.3 Anti-Patterns (ERRORS) ​

❌ INCORRECT: Missing await ​

python
# WRONG - missing await
async def bad_translate():
    result = client.translate(body=["Hello"], to=["es"])  # Missing await
    return result[0].translations[0].text

❌ INCORRECT: Wrong credential type ​

python
# WRONG - using sync credential with async client
from azure.ai.translation.text.aio import TextTranslationClient
from azure.identity import DefaultAzureCredential  # Should be from .aio

async with TextTranslationClient(credential=DefaultAzureCredential()):
    ...

10. Best Practices Checklist ​

Correct Patterns ​

  • [ ] Use DefaultAzureCredential for authentication (Entra ID)
  • [ ] Use AzureKeyCredential with region for API key auth
  • [ ] Batch up to 100 texts in single request
  • [ ] Check detected_language before accessing
  • [ ] Use from_parameter not from for source language
  • [ ] Use list for to parameter (e.g., to=["es", "fr"])
  • [ ] Use async client for high-throughput scenarios
  • [ ] Cache get_supported_languages() response
  • [ ] Specify text_type="html" when translating HTML
  • [ ] Import DictionaryExampleTextItem for examples

Anti-Patterns to Avoid ​

  • [ ] Hardcoded credentials
  • [ ] String instead of list for to parameter
  • [ ] Using Python keyword from (use from_parameter)
  • [ ] Not checking detected_language for None
  • [ ] Sync credential with async client
  • [ ] Invalid script codes for transliteration
  • [ ] Missing language parameter for sentence breaking
  • [ ] Accessing translations without iterating
  • [ ] Not using context managers for resources

11. Environment Variables ​

Required ​

bash