The translation tool for chat completions allows you to translate text during a conversation with a Palmyra model.

While Palmyra X models can perform translation tasks, they are not optimized for these tasks and may not perform well without correct prompting. Palmyra Translate is a dedicated model optimized for translation use cases.

The Writer API also has a translation endpoint that you can use to translate text outside of a chat completion. See the translation API guide for more information.

This guide explains how to use the translation tool in a chat completion and provides an example of how to use it.

You need an API key to access the Writer API. Get an API key by following the steps in the API quickstart.

We recommend setting the API key as an environment variable in a .env file with the name WRITER_API_KEY.

​
Tool structure

The translation tool allows you to translate text during a chat with a Palmyra model.

To use the translation tool, add it to the tools array in your chat-completion endpoint request.

The translation tool object has the following structure:

ParameterTypeDescription
typestringThe type of tool, which is translation for the translation tool
functionobjectAn object containing the tool’s description and model
function.modelstringpalmyra-translate
function.formalitybooleanWhether the translation should be formal or informal, if the target language supports it.
function.length_controlbooleanWhether to control the length of the translation, if the target language supports it.
function.mask_profanitybooleanWhether to mask profanity in the translation, if the target language supports it.
function.source_languagestring(Optional) The language code of the text you want to translate. If you don’t provide a source language, the model automatically detects the language of the text you want to translate. If your message contains a different language than this value, this value overrides the language detection.
function.target_languagestring(Optional) The language code you want to translate the text to. If you don’t provide a target language, the model automatically selects the most appropriate language based on the message you provide to the chat completion endpoint. If your message contains a different language than this value, this value overrides the language selection.
"tools": [
    {
        "type": "translation",
        "function": {
            "model": "palmyra-translate",
            "formality": false,
            "length_control": false,
            "mask_profanity": true
        }
    }  
]

You can only pass one prebuilt tool in the tools array at a time. However, you can pass multiple custom tools in the same request.

Prebuilt tools are:

​
Response format

For non-streaming responses, the translated text is in the choices[0].message.content field. For streaming responses, the translated text is in the choices[0].delta.content field.

The response also contains a translation_data field that contains the following information:

ParameterTypeDescription
source_language_codestringThe language code of the text you provided to the translation tool.
target_language_codestringThe language code of the translated text.
source_textstringThe text the translation tool translated.

You can use the translation tool with streaming chat responses, but the translation tool call is not streamed. The response comes back in the choices[0].delta.content field once the full translation is complete.

If you are unfamiliar with the chat completions endpoint or streaming vs. non-streaming responses, learn more in the chat completion guide.

See the chat completion endpoint for more information on the response fields.

{
  "id": "63ae5c5d",
  "object": "chat.completion",
  "choices": [
    {
      "index": 0,
      "finish_reason": "tool_calls",
      "message": {
        "content": "¡Hola, mundo!",
        "role": "assistant",
        "tool_calls": null,
        "graph_data": {
          "sources": null,
          "status": null,
          "subqueries": null
        },
        "llm_data": null,
        "image_data": null,
        "translation_data": {
          "source_text": "Hello, world!",
          "source_language_code": "en",
          "target_language_code": "es"
        },
        "refusal": null
      },
      "logprobs": null
    }
  ],
  "created": 1745956341,
  "model": "palmyra-x5",
  "usage": {
    "prompt_tokens": 2909,
    "total_tokens": 2945,
    "completion_tokens": 36,
    "prompt_token_details": null,
    "completion_tokens_details": null
  },
  "system_fingerprint": "v1",
  "service_tier": null
}

​
Usage example

This example uses palmyra-translate to translate a message during a chat completion.

​
Create a tools array containing a translation tool

First, create a tools array that specifies the translation tool you want to use.

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

​
Send the request using chat completions

Add the tools array to the chat endpoint call along with your array of messages. Setting tool_choice to auto allows the model to choose when to use the translation tool, based on the message provided in the messages array.

The response contains the translated text in the choices[0].message.content field.

curl --location 'https://api.writer.com/v1/chat' \
    --header 'Content-Type: application/json' \
    --header "Authorization: Bearer $WRITER_API_KEY" \
    --data '{
        "model": "palmyra-x5",
        "messages": [
            {
                "role": "user",
                "content": "Translate the following message to Spanish: Hello, world!"
            }
        ],
        "tool_choice": "auto",
        "tools": [
            {
                "type": "translation",
                "function": {
                    "model": "palmyra-translate",
                    "formality": false,
                    "length_control": false,
                    "mask_profanity": true
                    }
                }
        ]
    }'

If you want to verify the translation data in the response, you can print the translation_data field to see the source text, source language code, and target language code that the translation tool used.

print(response.choices[0].message.translation_data)

By following this guide, you can use the translation tool to have the palmyra-translate model translate a message during a chat completion.

​
Next steps

Learn about additional capabilities of the Writer API, such as detecting AI-generated text and analyzing images.