# Text-Replacement

### What is the Text-Replacement feature?

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 actually gets translated (and sent to other channels/servers), while the original message in the source channel stays untouched.

Because the replacement happens **before** translation, you get full control over what the translation engine sees — which means cleaner translations, consistent wording, and the ability to adapt content to the target context.

### What can I use it for?

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

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

{% 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 %}

### 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 modal where you enter the <strong>Input</strong> (the text to look for) and the <strong>Output</strong> (what it should be replaced with).</td></tr><tr><td><code>/text-replacement list</code></td><td>Shows every configured replacement 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 currently configured on your server.</td></tr></tbody></table>

### How does it work, step by step?

1. A user sends a message that iTranslator is going to translate (via Automatic-Translation, Role-Translation, a flag reaction, or the `/translate` command).
2. Right before the content is sent to the translation engine, iTranslator walks through **all** configured replacements for the server and applies them in order to the raw message content.
3. The resulting string is what gets translated and posted to the target channel(s).

The original message shown in the source channel is never modified — only the text that leaves for translation is.

### Limits

<table><thead><tr><th></th><th width="220">Free</th><th>Premium</th></tr></thead><tbody><tr><td>Max number of replacements</td><td>3</td><td>100</td></tr><tr><td>Max length of Input / 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 [iTranslator Premium](https://itranslator.app/premium).
{% endhint %}

### Tips

* **Be specific with your Inputs.** A replacement is a plain substring swap — if your Input matches something inside another word, it *will* be replaced there too. Prefer distinctive tokens (full mention strings, unique abbreviations, keywords surrounded by spaces, etc.).
* **Role / channel / user mention mapping between servers is the killer use-case.** Store the source-server mention as Input and the target-server mention as Output. Your pings will keep working after translation.


---

# Agent Instructions: Querying This Documentation

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

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.itranslator.app/amazing-features/text-replacement.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.