> 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](https://docs.itranslator.app/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](https://docs.itranslator.app/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.
