AI Translation (PRO) 1.1.2

AITranslation Pro

Translate selected language files or a bounded set of loaded plugins, with optional opt-in global-chat translation and configurable provider controls.

◆ AT A GLANCE

• Translate one plugin into several locales.
• Run a bounded bulk operation across loaded plugins.
• Offer global-chat translation only to players who explicitly opt in.
• Use native global chat, with optional BetterChat formatting support.
• Validate file and chat responses before replacement or delivery.
• Control queue, concurrency, request, retry, bulk, chat and local token budgets.

The server owner supplies an OpenAI API token and pays any provider charges.

◆ HOW IT HELPS

Administrators can prepare several server locales without issuing a separate single-locale command for every loaded plugin. Players retain control over whether eligible global chat may leave the server for translation.

◆ KEY FEATURES

• Flexible file translation for one plugin, several locales or a bounded loaded-plugin set.
• Explicit chat consent with permission checks for senders and recipients.
• Shared queue, rate, daily, bulk, chat-size, locale-fan-out and token limits.
• Backup and recovery material before language-file replacement.

◆ REQUIREMENTS AND COMPATIBILITY

• Rust server running Oxide or Carbon.
• AITranslation Pro 1.1.2.
• Your own OpenAI API token with provider credit.
• English source language files for file translation.
• BetterChat only if you want its optional formatting route.

AITranslation Pro and AITranslation Free are separate and mutually exclusive. Do not run both together. Pro takes priority and unloads Free.

◆ SETUP

1. Stop the server or unload an older AITranslation Pro version.
2. Remove AITranslation Free if it is installed.
3. Place AITranslationPro.cs in the server's plugin directory.
4. Start or reload Pro once so its configuration is generated.
5. Set OpenAIToken in the protected server configuration.
6. Review the player notice, explicit-consent rule, permissions and limits.
7. Reload the plugin after saving the configuration.

Keep the configuration readable only by trusted server operators. Never expose the token in chat, logs or support requests.

◆ HOW IT WORKS

◆ TUTORIAL 1: TRANSLATE ONE PLUGIN INTO SEVERAL LOCALES

Suppose the source exists at:

│ oxide/lang/en/MyPlugin.json

Run from server console or RCON:

│ aitpro.translateplugin MyPlugin fr de

Pro sends only the selected English values, target languages and provider instructions. Each result must preserve the exact key set, string values and placeholders. A valid target is staged before replacement and the previous file is retained as <PluginName>.json.aitranslation.bak.

◆ TUTORIAL 2: BOUNDED BULK TRANSLATION

To translate a controlled set of loaded plugin language files:

│ ait.translateallplugins fr de

The operation remains subject to MaxBulkPlugins, queue, rate, daily and local token limits. Start with a small locale set and verify the results before a larger run.

◆ TUTORIAL 3: ENABLE OPT-IN GLOBAL CHAT

1. Keep Privacy.RequireExplicitConsent enabled.
2. Review the player-facing notice for your server.
3. Grant aitranslationpro.chat.use only to intended participants.
4. A player explicitly opts in with:

│ /ait.chat on

5. The player can check or revoke the stored choice:

│ /ait.chat status
│ /ait.chat off

Unknown consent or a storage failure is treated as opted out. Team and non-global channels remain unchanged. For eligible global chat, both sender and translated recipients require the permission and stored consent. A failed translation delivers the original message.

◆ CONFIGURATION HIGHLIGHTS

Edit the generated configuration for your installed version. This is the tracked 1.1.2 default shape with a token placeholder:

│ {
│   "OpenAIToken": "PASTE_TOKEN_HERE",
│   "ChatConfiguration": {
│     "Enabled": true,
│     "Model": {
│       "Model": "gpt-5.6-luna",
│       "Temperature": 0.0,
│       "MaxTokens": 512,
│       "Prompt": ""
│     }
│   },
│   "LangFilesConfiguration": {
│     "Enabled": true,
│     "TimeBetweenRequestsInSeconds": 1.0,
│     "Model": {
│       "Model": "gpt-5.6-luna",
│       "Temperature": 0.0,
│       "MaxTokens": 4096,
│       "Prompt": ""
│     }
│   },
│   "Privacy": {
│     "RequireExplicitConsent": true,
│     "PlayerNotice": "This server can send global chat to OpenAI for translation. Use /ait.chat on to opt in or /ait.chat off to remain opted out."
│   },
│   "Limits": {
│     "MaxQueued": 32,
│     "MaxConcurrent": 2,
│     "MaxRequestsPerMinute": 30,
│     "MaxRequestsPerDay": 1000,
│     "DailyTokenBudget": 500000,
│     "MaxRetries": 2,
│     "MaxLanguageFileCharacters": 60000,
│     "MaxProviderResponseCharacters": 150000,
│     "MaxChatCharacters": 500,
│     "MaxChatLocalesPerMessage": 4,
│     "ChatSenderCooldownSeconds": 5,
│     "MaxBulkPlugins": 100
│   }
│ }

The model is configurable. Verify current OpenAI availability and pricing before enabling requests. Temperature, Prompt and LangFilesConfiguration.TimeBetweenRequestsInSeconds remain readable for older configurations but are not used to create current requests.

◆ COMMANDS AND PERMISSIONS

◆ COMMANDS

Command — Purpose
aitpro.translateplugin <plugin> <locale1> [locale2 ...] — Translate one installed plugin into one or more locales.
ait.translateplugin <plugin> <locale1> [locale2 ...] — Historical Pro alias.
ait.translateallplugins <locale1> [locale2 ...] — Translate a bounded set of loaded plugin language files.
`/ait.chat on\ — off\ — status` — Record or display the player's chat-translation choice.

◆ PERMISSIONS

Permission — Purpose
aitranslationpro.admin — Allow a trusted non-admin connection to initiate paid file or bulk translation.
aitranslationpro.chat.use — Allow consenting senders and recipients to participate in translated global chat.

◆ BETTERCHAT

BetterChat is optional. When available, Pro uses its formatting API; otherwise the native global-chat route remains available. Test the combination on a non-production server before relying on it because live dynamic hook ordering was not validated during the recorded final validation.

◆ RECOVERY TUTORIAL

1. Unload AITranslation Pro.
2. Inspect the target file, .aitranslation.bak and any .aitranslation.rollback file.
3. Restore the known-good copy manually if required.
4. Remove recovery material only after verifying the target file.
5. Reload Pro and retry one small file translation.

Pro blocks another replacement while unresolved recovery material is present.

◆ PRIVACY, VALIDATION AND COST CONTROLS

• Explicit consent is enforced for chat translation.
• Tokens, translated content, player chat and provider response bodies are not logged.
• Malformed, incomplete, refused, oversized or structurally incorrect responses are rejected.
• Chat messages have local length, locale fan-out and sender-cooldown limits.
• File and chat work share configurable queue, rate, daily and token budgets.
• The operator remains responsible for OpenAI usage and charges.

◆ TROUBLESHOOTING

◆ FILE TRANSLATION DOES NOT START

Confirm the token, source file, authorization, enabled file route, local limits and absence of unresolved recovery material.

◆ A PLAYER DOES NOT RECEIVE TRANSLATED CHAT

Check that chat is enabled, the message is global, both participants have aitranslationpro.chat.use and both have stored consent. Use /ait.chat status to verify the current choice.

◆ BETTERCHAT IS NOT INSTALLED

It is not required. Pro can use native global chat without BetterChat.

◆ A TRANSLATED RESPONSE IS REJECTED

Review the redacted error code. Pro rejects wrong keys, changed placeholders, oversized output and incomplete provider responses. Retry with a small source or message after checking provider availability and limits.

◆ KNOWN LIMITATIONS

• Translation quality and provider availability are outside the plugin's control.
• Chat translation applies only to eligible opted-in global chat.
• BetterChat formatting is optional and live hook ordering remains unverified.
• A real OpenAI request was not executed during the recorded final validation.

◆ SUPPORT

Use the Codefling support section with the Pro version, Oxide or Carbon version, BetterChat state, command or chat route and a redacted error code. Never share the OpenAI token, player chat or language-file contents.