Translate text in a chat
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:
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. If your message contains a different language than this value, this value overrides the language detection. |
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. If your message contains a different language than this value, this value overrides the language selection. |
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:
- Translation tool
- Knowledge Graph tool
- LLM tool
- Vision tool
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:
Parameter | Type | Description |
---|---|---|
source_language_code | string | The language code of the text you provided to the translation tool. |
target_language_code | string | The language code of the translated text. |
source_text | string | The 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.
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.
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.
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.
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.