Translate text in a chat - Writer AI Studio

Tool structure

The translation tool allows you to translate text during a chat completion. 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:

Parameter	Type	Description
`type`	`string`	The type of tool, which is `translation` for the translation tool
`function`	`object`	An object containing the tool’s description and model
`function.model`	`string`	`palmyra-translate`
`function.formality`	`boolean`	Whether the translation should be formal or informal, if the target language supports it.
`function.length_control`	`boolean`	Whether to control the length of the translation, if the target language supports it.
`function.mask_profanity`	`boolean`	Whether to mask profanity in the translation, if the target language supports it.
`function.source_language`	`string`	(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.
`function.target_language`	`string`	(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.

Non-streaming response

{
  "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.

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
                    }
                }
        ]
    }'

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