> For the complete documentation index, see [llms.txt](https://docs.itranslator.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.itranslator.app/amazing-features/text-replacement.md).

# Text-Replacement

Transform the content of a message right before iTranslator sends it to the translation engine — perfect for mapping mentions across servers, expanding jargon, fixing branded terms, and much more.

## What is Text-Replacement?

Text-Replacement lets you define pairs of **Input → Output** strings. Whenever iTranslator is about to translate a message, it first scans the raw content and swaps every occurrence of an `Input` with its matching `Output`. The **replaced** text is what gets translated (and sent to other channels or servers), while the original message in the source channel stays untouched.

Because the replacement happens **before** the translation, you control what the translation engine sees: cleaner translations, consistent wording, and content adapted to the target context.

{% hint style="info" %}
Text-Replacement applies to **every** translation performed by iTranslator in your server: Automatic-Translation, Role-Translation, Translation by Flag and the `/translate` command.
{% endhint %}

## What can I use it for?

Text-Replacement is intentionally simple, but very flexible. A few ideas:

* **Cross-server role, channel and user mention mapping**\
  In a multi-server setup where the messages of one server are translated and relayed to another, Discord IDs differ between the servers. Map a mention from Server A to its equivalent on Server B and the pings stay valid after translation.\
  *Example:* `<@&111111111111111111>` → `<@&222222222222222222>`
* **Brand, product and proper-noun protection**\
  Prevent the translator from awkwardly translating brand names, product names or in-game items.\
  *Example:* map a codename to its official name (`iTrans` → `iTranslator`), or keep a product name untouched by mapping it to itself.
* **Acronyms and internal jargon**\
  Replace short abbreviations with their full form, so the translation is accurate in every language.\
  *Example:* `QA` → `Quality Assurance`, `afaik` → `as far as I know`
* **Sensitive content**\
  Strip internal links, replace them with public ones, or rewrite templated tags before the translation leaves your channel.

## Manage your rules

{% tabs %}
{% tab title="Dashboard" %}
Open your server in the [dashboard](/fundamentals/dashboard.md) and go to **Server → Text-Replacement**. Type the **Original text** and what it is **Replaced by**, then click **Add**. Click the cross on a rule to remove it.

<figure><img src="https://3955709218-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FuW8Vjy8RHWcWMwcAWdcy%2Fuploads%2Fgit-blob-ab4d6cfc2194b0c5f4e10f03e8c3c381533a03bd%2Fdashboard-textreplacement.png?alt=media" alt="The Text-Replacement page of the dashboard with three rules"><figcaption></figcaption></figure>
{% endtab %}

{% tab title="Commands" %}
All Text-Replacement commands require the **Manage Server** permission.

<table><thead><tr><th width="260">Command</th><th>Description</th></tr></thead><tbody><tr><td><code>/text-replacement add</code></td><td>Opens a form where you enter the <strong>Input</strong> (the text to look for) and the <strong>Output</strong> (what it is replaced with).</td></tr><tr><td><code>/text-replacement list</code></td><td>Shows every replacement configured on your server, with pagination if you have many.</td></tr><tr><td><code>/text-replacement remove</code></td><td>Removes a replacement. The <code>input</code> option has autocomplete, so you can quickly pick an existing entry.</td></tr><tr><td><code>/text-replacement help</code></td><td>Displays a summary of the feature and how many replacements are configured on your server.</td></tr></tbody></table>
{% endtab %}
{% endtabs %}

## How does it work, step by step?

{% stepper %}
{% step %}

### A message is about to be translated

A member sends a message that iTranslator is going to translate: through Automatic-Translation, Role-Translation, a flag reaction or the `/translate` command.
{% endstep %}

{% step %}

### The rules are applied

Right before the content is sent to the translation engine, iTranslator goes through **all** the rules of the server and applies them, in order, to the raw content of the message.
{% endstep %}

{% step %}

### The result is translated

The resulting text is what gets translated and posted in the target channels. The original message is never modified.
{% endstep %}
{% endstepper %}

## Limits

<table><thead><tr><th width="260"></th><th width="200">Free</th><th>Premium &#x26; Pro</th></tr></thead><tbody><tr><td>Number of replacements</td><td>3</td><td>100</td></tr><tr><td>Length of an Input or an Output</td><td>16 characters</td><td>256 characters</td></tr></tbody></table>

{% hint style="info" %}
Need more replacements or longer patterns? Upgrade your server with [Premium](/overview/premium.md).
{% endhint %}

## Tips

* **Be specific with your Inputs.** A replacement is a plain substring swap: if your Input matches a part of another word, it *is* replaced there too. Prefer distinctive tokens such as full mention strings or unique abbreviations.
* **Mind the case.** Matching is case-sensitive: `QA` and `qa` are two different Inputs.
* **Mapping mentions between servers is the killer use case.** Store the mention of the source server as Input and the mention of the target server as Output, and your pings keep working after translation.


---

# 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.itranslator.app/amazing-features/text-replacement.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.