Skip to main content
This guide shows you how to migrate from the deprecated Translation API endpoint to the translation tool in chat completions. After completing these steps, you can translate text using the translation tool, which provides the same capabilities within a chat completion workflow.

​
Compare the APIs

The Translation API and the translation tool both provide text translation, but the translation tool integrates translation into conversational workflows and changes how you specify translation requests and configurations. The table below compares the two approaches.
AspectTranslation APITranslation tool
Endpoint/v1/translation/v1/chat with the prebuilt translation tool specification
Request structurePass translation parameters such as text, source_language_code, target_language_code, etc. directly in the request bodyProvide the text to translate as part of the conversation messages array and include the translation tool in the tools array. Specify additional settings (such as languages or preferences) in the tool configuration, not as direct request parameters.
Response formatTranslation in the data fieldAnswer in choices[0].message.content; structured details in the translation_data field
Parameter controlExplicit API parameters for each optionMost translation details (languages, formality, etc.) specified in the prompt or tool configuration rather than as top-level request fields

​
Migrate your code

The tabs below show a request using the translation API and the same request using the translation tool.
  • Before: Translation API
  • After: Translation tool
The Translation API accepts text and translation parameters directly in the request body:
curl --request POST \
  --url https://api.writer.com/v1/translation \
  --header "Authorization: Bearer $WRITER_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "palmyra-translate",
  "source_language_code": "en",
  "target_language_code": "es",
  "text": "Hello, world!",
  "formality": true,
  "length_control": true,
  "mask_profanity": true
}'
Response:
{
  "data": "¡Hola, mundo!"
}

​
Map your parameters

The following table shows how Translation API parameters map to the translation tool:
Translation APITranslation tool
textInclude in the message content field
source_language_codetools[0].function.source_language (optional)
target_language_codetools[0].function.target_language (optional)
formalitytools[0].function.formality
length_controltools[0].function.length_control
mask_profanitytools[0].function.mask_profanity
With the translation tool, the source_language and target_language parameters are optional. If you don’t provide them, the model automatically detects the source language and determines the target language from your message.To specify languages explicitly, include them in your message prompt (for example, “Translate to Spanish”) or use the optional source_language and target_language parameters in the tool configuration.

​
Access translation metadata

The translation tool response includes additional metadata in the translation_data field. The metadata includes the source text, source language, and target language: 
from writerai import Writer

# Initialize the Writer client. If you don't pass the `api_key` parameter,
# the client looks for the `WRITER_API_KEY` environment variable.
client = Writer()

messages = [{"role": "user", "content": "Translate the following message to Spanish: 'Hello, world!'"}]

tools = [{
  "type": "translation",
  "function": {
    "model": "palmyra-translate",
    "formality": True,
    "length_control": True,
    "mask_profanity": True
  }
}]

response = client.chat.chat(
  model="palmyra-x5", 
  messages=messages, 
  tools=tools,
  tool_choice="auto"
)

# Get translated text
translated_text = response.choices[0].message.content

# Get translation metadata
translation_metadata = response.choices[0].message.translation_data
source_lang = translation_metadata.source_language_code
target_lang = translation_metadata.target_language_code
source_text = translation_metadata.source_text

print(f"Translated '{source_text}' from {source_lang} to {target_lang}: {translated_text}")
Learn more about the translation tool and related features: