> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/maiagent-user-guide/en/work/writing-assistants/translation.md).

# AI Translation

AI translation Agent use case: enable the official built-in multilingual translation Agent, or build your own translation assistant with a company glossary of proper nouns. Supports text, document, an

Translation is one of the tasks most often handed to AI, but pasting text straight into a general-purpose model tends to cause three problems: the company's product names and proper nouns are translated differently each time, the paragraphs and table formatting of the original are lost, and high-risk documents such as contracts get no reminder to be double-checked. Building a dedicated translation Agent lets you fix "which language to translate into by default, how to translate proper nouns, how to preserve formatting, and which documents need a reminder note", so colleagues can paste in content and get consistent translations.

## Use Cases <a href="#scenarios" id="scenarios"></a>

| Scenario                        | Input                                                 | Output                                                                    |
| ------------------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------- |
| Everyday communication          | Foreign-language emails, messages, announcements      | A translation, with the original alongside when needed                    |
| Document translation            | Uploaded Word, PDF, and presentation files            | A translation that preserves the structure of headings, lists, and tables |
| Images and screenshots          | Photos containing text, screenshots of system screens | Recognizes the text first, then translates it                             |
| Marketing and slogans           | Ad copy, product slogans                              | A literal translation plus a version that fits the local feel             |
| Product and technical documents | Specifications, operation manuals                     | Translated according to the company glossary of proper nouns              |

## Three Approaches: Pick One First <a href="#choose-approach" id="choose-approach"></a>

| Approach                                | Best for                                                                                                         | How to do it                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| --------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Enable the official built-in Agent**  | You want to use it right away and do not need custom rules                                                       | In the <mark style="color:blue;">Official Built-in</mark> tab of the [Agent Marketplace](https://docs.maiagent.ai/maiagent-user-guide/en/work/built-in-agents/use.md), find <mark style="color:blue;">Multilingual Translation</mark> (Personal Productivity); an administrator enables it in [Built-in Agent Management](https://docs.maiagent.ai/maiagent-user-guide/en/org/management.md). Medical institutions also have <mark style="color:blue;">Medical Translation</mark> (Healthcare), which preserves drug names, dosages, and units verbatim |
| **Apply a template and then modify it** | You want to start from the official design and add your company's proper nouns and tone                          | In the [Agent Template Library](https://docs.maiagent.ai/maiagent-user-guide/en/build/agent/agent-templates.md), apply <mark style="color:blue;">Multilingual Translation</mark> to get an editable Agent, then adjust it by following steps 2–3 on this page                                                                                                                                                                                                                                                                                           |
| **Build from scratch**                  | The rules are simple (for example, always Chinese to English), or you want full control of the role instructions | Follow all the steps on this page                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |

Once an official built-in Agent is enabled, its role instructions cannot be changed, but you can [import a dedicated knowledge base](https://docs.maiagent.ai/maiagent-user-guide/en/org/management.md#knowledge-base) and put the glossary of proper nouns in it.

{% hint style="info" %}
To translate an entire PDF while preserving its original layout (chart positions, columns), use the knowledge base's [PDF document translation](https://docs.maiagent.ai/maiagent-user-guide/en/build/knowledge-base/translate-pdf.md) instead; a conversational translation Agent is suited to text, paragraphs, and ordinary documents.
{% endhint %}

## What to Prepare <a href="#prerequisites" id="prerequisites"></a>

* An account that can create Agents (the role has the <mark style="color:blue;">AI Assistants</mark> permission)
* A glossary of proper nouns (optional but recommended): the original terms and specified translations for product names, departments and job titles, and industry terminology, in Excel or CSV format
* A style guide (optional): the tone of external documents, wording to avoid, and number and date formats
* Decide the default target language: which language to translate into when the user does not specify one

## Setup Steps <a href="#setup" id="setup"></a>

### 1. Create the Agent <a href="#step-create-agent" id="step-create-agent"></a>

Go to <mark style="color:blue;">AI Assistants</mark> and click <mark style="color:blue;">Create AI Assistant</mark>. Name it, for example, "Translation Assistant". For <mark style="color:blue;">LLM Model</mark>, choose a model that your organization has enabled: to translate images and screenshots, choose a model that supports image input; for short everyday texts, a faster-responding model can save Credits. Keep the response mode at the default <mark style="color:blue;">Agent Mode</mark>. For details, see [Create an Agent](https://docs.maiagent.ai/maiagent-user-guide/en/build/agent/setup.md).

### 2. Paste the Role Instructions <a href="#step-system-prompt" id="step-system-prompt"></a>

In <mark style="color:blue;">Response Mode Settings</mark>, paste the following example into <mark style="color:blue;">Role Instructions</mark>, and change the default language to what your company needs.

```
## Role
You are a translation assistant who only translates and polishes translations. For other requests, politely explain that you cannot help.

## Before you start
- When the user provides the source text and the target language, translate directly without asking further questions.
- When no target language is specified: if the source text is Chinese, translate it into English; if it is in any other language, translate it into Traditional Chinese (Taiwanese usage).
- When no source text is provided, ask the user to paste text or upload a file.
- When the user uploads an image or screenshot, first list the text you recognized, then give the translation.

## Translation principles
- Stay faithful to the original meaning: do not add information that is not in the source, and do not omit or rewrite anything.
- Keep numbers, units, dates, amounts, personal names, place names, organization names, code, and URLs exactly as in the original.
- Preserve the paragraph, heading, list, and table structure of the original.
- For proper nouns, first check the glossary in the knowledge base and use the specified translation if there is one; if none is found, keep the original term and add the original in parentheses after it,
  and do not invent an official translated name. Translate the same term the same way throughout the text.
- Match the tone of the original: use a formal register for official documents and contracts, and natural phrasing for marketing and colloquial content.

## Output
- By default, output only the translation. When the user requests it, switch to a paragraph-by-paragraph "original / translation" comparison.
- For creative content such as ad copy and slogans, provide a literal translation plus a version that fits the local feel, and explain the difference between the two.
- List a "Terminology" section at the end for terms that used the glossary or had the original added in parentheses.

## Reminder
- For translations of contracts, regulations, medical documents, and financial documents, add at the end:
  "This translation is for reference only. For formal use, please have it reviewed by a professional familiar with both languages."
```

### 3. Attach the Glossary of Proper Nouns <a href="#step-knowledge-base" id="step-knowledge-base"></a>

Upload the glossary to a [knowledge base](https://docs.maiagent.ai/maiagent-user-guide/en/build/knowledge-base/km.md) and attach it in the Agent's <mark style="color:blue;">Knowledge Base Settings</mark>. When preparing the glossary:

* Put one term per row, with the columns "Original, Specified translation, Notes (applicable situations or translations that must not be used)"
* List the translations of the same term in different languages in separate rows; do not cram them into one cell
* When there are not many terms (a few dozen), you can also write them directly into the "Translation principles" section of the role instructions, which gives the most reliable hit rate
* Frequently asked fixed translations can also be built into an [FAQ](https://docs.maiagent.ai/maiagent-user-guide/en/build/knowledge-base/faq.md)

### 4. Enable File Upload and the Tools You Need <a href="#step-enable-features" id="step-enable-features"></a>

* Go to this Agent's "Internal" chat platform → [Function Settings](https://docs.maiagent.ai/maiagent-user-guide/en/build/conversation-settings/platform-settings/function-settings.md#basic-functions) and enable <mark style="color:blue;">Allow file uploads</mark>, so colleagues can upload documents and images
* To have the Agent output the translation as a Word or PDF file, enable the [Code Interpreter](https://docs.maiagent.ai/maiagent-user-guide/en/build/agent/code-interpreter.md)
* To let the Agent look up unfamiliar proper nouns online, add the built-in web search tool in the <mark style="color:blue;">Tools</mark> tab; see [Configure Tools for an Agent](https://docs.maiagent.ai/maiagent-user-guide/en/build/tools/configure_tools.md)

### 5. Open It to Colleagues <a href="#step-share" id="step-share"></a>

In [Role Permissions](https://docs.maiagent.ai/maiagent-user-guide/en/org/roles/role-permission.md), assign this Agent's "Internal" chat platform to the roles that need it. Colleagues can then select it in [Internal Q\&A](https://docs.maiagent.ai/maiagent-user-guide/en/work/explain.md) and start a conversation. To offer it to external users on your website or customer service entry point, create a separate [Web Chat](https://docs.maiagent.ai/maiagent-user-guide/en/build/choose-channel/web-chat.md) chat platform.

## Test Cases <a href="#test-cases" id="test-cases"></a>

| #  | Input                                                                                       | Expected result                                                                                     |
| -- | ------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| 1  | Paste a passage of Chinese without specifying a language                                    | Translates directly into English without asking back                                                |
| 2  | Paste a passage of Japanese without specifying a language                                   | Translates into Traditional Chinese, using Taiwanese usage                                          |
| 3  | "Translate into Japanese: This product comes with a 24-month warranty, priced at NT$12,800" | Numbers, amounts, and currency are kept as in the original                                          |
| 4  | A sentence containing a product name from the glossary                                      | Uses the specified translation from the glossary and lists the terminology at the end               |
| 5  | A sentence containing a proper noun not in the glossary                                     | Keeps the original and adds a note, without inventing a translated name                             |
| 6  | Paste a passage with headings, bullet lists, and tables                                     | The translation keeps the same structure                                                            |
| 7  | Upload a system screenshot containing English                                               | First lists the recognized text, then gives the translation                                         |
| 8  | Paste a contract clause                                                                     | The translation ends with a reminder for review by a professional                                   |
| 9  | "Translate this slogan into English: 安心，從這裡開始"                                              | One literal version and one version that fits the local feel, with an explanation of the difference |
| 10 | "Write an English job application letter for me"                                            | Explains that it only translates and polishes translations                                          |

## FAQ <a href="#faq" id="faq"></a>

### Which languages are supported? <a href="#faq-languages" id="faq-languages"></a>

It depends on the language model you choose. Mainstream models give the best quality for Chinese, English, Japanese, Korean, and the major European languages; for less common languages, test with a few passages of real content first, and have a native speaker double-check important documents.

### Are proper nouns still translated inconsistently? <a href="#faq-terminology" id="faq-terminology"></a>

First confirm the glossary is actually being retrieved: in the chat platform's [Function Settings](https://docs.maiagent.ai/maiagent-user-guide/en/build/conversation-settings/platform-settings/function-settings.md#ai-interaction), enable <mark style="color:blue;">Show cited documents</mark> and check whether the translation cites the glossary. If it does not, write the most critical terms directly into the role instructions, or split the glossary into smaller files with one term per row.

### Can it translate a whole long document? <a href="#faq-long-document" id="faq-long-document"></a>

You can upload a document and ask the Agent to translate it, but for very long ones the reply may be split into parts or truncated. For a whole PDF where the layout must be preserved, use [PDF document translation](https://docs.maiagent.ai/maiagent-user-guide/en/build/knowledge-base/translate-pdf.md); for other long documents, we recommend translating chapter by chapter.

### Can the translation be used externally as is? <a href="#faq-publish" id="faq-publish"></a>

For ordinary correspondence and internal documents, yes. For contracts, regulations, medical documents, and formal externally published documents, have colleagues familiar with both languages double-check the key clauses and numbers.

### How is this different from just asking AI to translate in MaiGPT? <a href="#faq-vs-maigpt" id="faq-vs-maigpt"></a>

MaiGPT is suited to one-off personal translation; a translation Agent fixes the default language, proper nouns, and output format, so everyone in the company gets consistent translations and does not have to retype instructions every time.

## Further Reading <a href="#further-reading" id="further-reading"></a>

* [Use Cases: Documents and Content Creation](https://docs.maiagent.ai/maiagent-user-guide/en/work/writing-assistants.md): design highlights of other document Agents
* [Multi-Language Support](https://docs.maiagent.ai/maiagent-user-guide/en/build/agent/multi-language-support.md): Web Chat interface language and reply language settings
* [Use Official Built-in Agents](https://docs.maiagent.ai/maiagent-user-guide/en/work/built-in-agents/use.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.maiagent.ai/maiagent-user-guide/en/work/writing-assistants/translation.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
