## Tool structure

The translation tool allows you to translate text during a [chat completion](https://dev.writer.com/home/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](https://dev.writer.com/api-reference/translation-api/language-support#formality). |
| `function.length_control` | `boolean` | Whether to control the length of the translation, [if the target language supports it](https://dev.writer.com/api-reference/translation-api/language-support#length-control). |
| `function.mask_profanity` | `boolean` | Whether to mask profanity in the translation, [if the target language supports it](https://dev.writer.com/api-reference/translation-api/language-support#profanity-masking). |
| `function.source_language` | `string` | (Optional) The [language code](https://dev.writer.com/api-reference/translation-api/language-support#language-codes) 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](https://dev.writer.com/api-reference/translation-api/language-support#language-codes) 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

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

```python
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.

```bash
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.