XUnity Auto Translator v5.3.1 (2024)

All the basic information about the plugin is located here - XUnity.AutoTranslator
Plugin author: bbepis
Icon: https://uxwing.com/language-translation-icon/

For translating the whole game, it's recommended to use community translation from Crowdin instead. Check the description of the Crowdin page to learn how to convert json file to game locale files.
https://crowdin.com/project/dyson-sphere-program

The following are some extracted important info for normal users. The full manual can be found in github repo or plugins\README (AutoTranslator).md in the zip package.

Introduction

This is an advanced translator plugin that can be used to translate Unity-based games automatically and also provides the tools required to translate games manually. It does (obviously) go to the internet, in order to provide the automated translation, so if you are not comfortable with that, don't use it.

Key Mapping

The following key inputs are mapped:

• ALT + 0: Toggle XUnity AutoTranslator UI. (That's a zero, not an O)
• ALT + 1: Toggle Translation Aggregator UI.
• ALT + T: Alternate between translated and untranslated versions of all texts provided by this plugin.
• ALT + R: Reload translation files. Useful if you change the text and texture files on the fly. Not guaranteed to work for all textures.
• ALT + U: Manual hooking. The default hooks wont always pick up texts. This will attempt to make lookups manually. Will not hook text components from frameworks not enabled.
• ALT + F: If OverrideFont is configured, will toggle between overridden and default font.
• ALT + Q: Reboot the plugin if it was shutdown. This will only work if the plugin was shut down due to consecutive errors towards the translation endpoint. Should only be used if you have reason to believe you have remedied the problem (such as changed VPN endpoint etc.) otherwise it will just shut down again.

Installation

Via mod manager r2modman.
Manual install:

1. Install BepInEx 5.4.17 framework
2. Download the mod zip file
3. Unzip and put the content into BepInEx folder
   core\XUnity.Common.dll -> BepInEx\core
plugins\XUnity.AutoTranslator, plugins\XUnity.ResourceRedirector -> BepInEx\plugins

Configuration

The config file BepInEx\Config\AutoTranslatorConfig.ini will be generated after the game start with this plugin.
In order to translate, change the language settings in the config file and restart to let the config file take effect.

[Service]Endpoint=GoogleTranslate ;Endpoint to use. See the [translators section](#translators) for valid values.FallbackEndpoint= ;Endpoint to automatically fallback to if the primary endpoint fails for a specific translation.[General]Language=en ;The language to translate intoFromLanguage=ja ;The original language of the game. "auto" is also supported for some endpoints, but it is generally not recommended[Files]Directory=Translation\{Lang}\Text ;Directory to search for cached translation files. Can use placeholder: {GameExeName}, {Lang}OutputFile=Translation\{Lang}\Text\_AutoGeneratedTranslations.txt ;File to insert generated translations into. Can use placeholders: {GameExeName}, {Lang}SubstitutionFile=Translation\{Lang}\Text\_Substitutions.txt ;File that contains substitution applied before translations. Can use placeholders: {GameExeName}, {Lang}PreprocessorsFile=Translation\{Lang}\Text\_Preprocessors.txt ;File that contains preprocessors to be applied before sending a text to a translator. Can use placeholders: {GameExeName}, {Lang}PostprocessorsFile=Translation\{Lang}\Text\_Postprocessors.txt ;File that contains postprocessors to be applied after receiving a text from a translator. Can use placeholders: {GameExeName}, {Lang}[TextFrameworks]EnableUGUI=True ;Enable or disable UGUI translationEnableNGUI=True ;Enable or disable NGUI translationEnableTextMeshPro=True ;Enable or disable TextMeshPro translationEnableTextMesh=False ;Enable or disable TextMesh translationEnableIMGUI=False ;Enable or disable IMGUI translation[Behaviour]MaxCharactersPerTranslation=200 ;Max characters per text to translate. Max 2500.IgnoreWhitespaceInDialogue=True ;Whether or not to ignore whitespace, including newlines, in dialogue keysIgnoreWhitespaceInNGUI=True ;Whether or not to ignore whitespace, including newlines, in NGUIMinDialogueChars=20 ;The length of the text for it to be considered a dialogueForceSplitTextAfterCharacters=0 ;Split text into multiple lines once the translated text exceeds this number of charactersCopyToClipboard=False ;Whether or not to copy hooked texts to clipboardMaxClipboardCopyCharacters=450 ;Max number of characters to hook to clipboard at a timeClipboardDebounceTime=1.25 ;The number of seconds it takes for hooked text to reach the clipboard. Minimum is 0.1EnableUIResizing=True ;Whether or not the plugin should provide a "best attempt" at resizing UI components upon translationEnableBatching=True ;Indicates whether batching of translations should be enabled for supported endpointsUseStaticTranslations=True ;Indicates whether or not to use translations from the included static translation cacheOverrideFont= ;Overrides the fonts used for texts when updating text components. NOTE: Only works for UGUIOverrideFontTextMeshPro= ;Consider using FallbackFontTextMeshPro instead. Overrides the fonts used for texts when updating text components. NOTE: Only works for TextMeshProFallbackFontTextMeshPro= ;Adds a fallback font for TextMeshPro in case a specific character is not supported. This is recommended over OverrideFontTextMeshProResizeUILineSpacingScale= ;A decimal value that the default line spacing should be scaled by during UI resizing, for example: 0.80. NOTE: Only works for UGUIForceUIResizing=True ;Indicates whether the UI resize behavior should be applied to all UI components regardless of them being translated.IgnoreTextStartingWith=\u180e; ;Indicates that the plugin should ignore any strings starting with certain characters. This is a list seperated by ';'.TextGetterCompatibilityMode=False ;Indicates whether or not to enable "Text Getter Compatibility Mode". Should only be enabled if required by the game. GameLogTextPaths= ;Indicates specific paths for game objects that the game uses as "log components", where it continuously appends or prepends text to. Requires expert knowledge to setup. This is a list seperated by ';'.RomajiPostProcessing=ReplaceMacronWithCircumflex;RemoveApostrophes;ReplaceHtmlEntities ;Indicates what type of post processing to do on 'translated' romaji texts. This can be important in certain games because the font used does not support various diacritics properly. This is a list seperated by ';'. Possible values: ["RemoveAllDiacritics", "ReplaceMacronWithCircumflex", "RemoveApostrophes", "ReplaceHtmlEntities"]TranslationPostProcessing=ReplaceMacronWithCircumflex;ReplaceHtmlEntities ;Indicates what type of post processing to do on translated texts (not romaji). Possible values: ["RemoveAllDiacritics", "ReplaceMacronWithCircumflex", "RemoveApostrophes", "ReplaceWideCharacters", "ReplaceHtmlEntities"]RegexPostProcessing=None ;Indicates what type of post processing to perform on the capture groups of regexes. Possible values: ["RemoveAllDiacritics", "ReplaceMacronWithCircumflex", "RemoveApostrophes", "ReplaceWideCharacters", "ReplaceHtmlEntities"]CacheRegexLookups=False ;Indicates whether or not results of regex lookups should be output to the specified OutputFileCacheWhitespaceDifferences=False ;Indicates whether or not whitespace differences should be output to the specified OutputFileCacheRegexPatternResults=False ;Indicates whether or not the complete result of regex-splitted translations should be output to the specified OutputFileGenerateStaticSubstitutionTranslations=False ;Indicates that the plugin should generate translations without variables when using substitutionsGeneratePartialTranslations=False ;Indicates that the plugin should generate partial translations to support text translations as it is "scrolling in"EnableTranslationScoping=False ;Indicates the plugin should parse 'TARC' directives and scope translations based on theseEnableSilentMode=False ;Indicates the plugin should not print out success messages in relation to translationsBlacklistedIMGUIPlugins= ;If an IMGUI window assembly/class/method name contains any of the strings in this list (case insensitive) that UI will not be translated. Requires MonoMod hooks. This is a list seperated by ';'OutputUntranslatableText=False ;Indicates if texts that are considered by the plugin to be untranslatable should be output to the specified OutputFileIgnoreVirtualTextSetterCallingRules=False; Indicates that rules for virtual method calls should be ignored when trying to set the text of a text component. May in some cases help setting the text of stubborn componentsMaxTextParserRecursion=1 ;Indicates how many levels of recursion are allowed when text is parsed so it can be translated in different parts. This can be used with splitter-regexes in advanced scenarios. The default value of one essentially means that recursion is disabled.HtmlEntityPreprocessing=True ;Will preprocess and decode html entities before they are send for translation. Some translators will fail when html entities are sent.HandleRichText=True ;Will enable automated handling of rich text (text with markup)PersistRichTextMode=Final ;Indicates how parsed rich text should be persisted. Either 'Fragment' to store the the text piecemeal or 'Final' to store the entire translated string (does not support substitutions!)EnableTranslationHelper=False ;Indicates if translator-related helpful log messages should be enabled. May be useful when tranlating based on redirected resourcesForceMonoModHooks=False ;Indicates that the plugin must use MonoMod hooks instead of harmony hooksInitializeHarmonyDetourBridge=False ;Indicates the plugin should initial harmony detour bridge which allows harmony hooks to work in an environment where System.Reflection.Emit does not exist (usually such settings are handled by plugin managers, so don't use when using a plugin manager)RedirectedResourceDetectionStrategy=AppendMongolianVowelSeparatorAndRemoveAll ;Indicates if and how the plugin should attempt to recognize redirected resources in order to prevent double translations. Can be ["None", "AppendMongolianVowelSeparator", "AppendMongolianVowelSeparatorAndRemoveAppended", "AppendMongolianVowelSeparatorAndRemoveAll"]OutputTooLongText=False ;Indicates if the plugin should output text that exceeds 'MaxCharactersPerTranslation' without translating it[Texture]TextureDirectory=Translation\{Lang}\Texture ;Directory to dump textures to, and root of directories to load images from. Can use placeholder: {GameExeName}, {Lang}EnableTextureTranslation=False ;Indicates whether the plugin will attempt to replace in-game images with those from the TextureDirectory directoryEnableTextureDumping=False ;Indicates whether the plugin will dump texture it is capable of replacing to the TextureDirectory. Has significant performance impactEnableTextureToggling=False ;Indicates whether or not toggling the translation with the ALT+T hotkey will also affect textures. Not guaranteed to work for all textures. Has significant performance impactEnableTextureScanOnSceneLoad=False ;Indicates whether or not the plugin should scan for textures on scene load. This enables the plugin to find and (possibly) replace more textureEnableSpriteRendererHooking=False ;Indicates whether or not the plugin should attempt to hook SpriteRenderer. This is a seperate option because SpriteRenderer can't actually be hooked properly and the implemented workaround could have a theoretical impact on performance in certain situationsLoadUnmodifiedTextures=False ;Indicates whether or not unmodified textures should be loaded. Modifications are determined based on the hash in the file name. Only enable this for debugging purposes as it is likely to cause odditiesTextureHashGenerationStrategy=FromImageName ;Indicates how the mod identifies pictures through hashes. Can be ["FromImageName", "FromImageData", "FromImageNameAndScene"]DuplicateTextureNames= ;Indicates specific texture names that are duplicated in the game. List is separated by ';'.DetectDuplicateTextureNames=False;Indicates if the plugin should detect duplicate texture names.EnableLegacyTextureLoading=False ;Indicates the plugin should use a different strategy to load images, that may be relevant if the game engine is oldCacheTexturesInMemory=True ;Indicates that all textures loaded should be kept in memory for optimal performance. Disable to decrease memory usage[ResourceRedirector]PreferredStoragePath=Translation\{Lang}\RedirectedResources ;Indicates the preferred storage for redirected resources in relation to the Auto Translator. Can use placeholder: {GameExeName}, {Lang}EnableTextAssetRedirector=False ;Indicates if TextAssets should be redirectedLogAllLoadedResources=False ;Indicates if the plugin should log to the console all loaded assets. Useful to determine what can be hookedEnableDumping=False ;Indicates if translatable resources that are found should be dumpedCacheMetadataForAllFiles=True ;When files are in ZIP files in the PreferredStoragePath, these files are indexed in memory to avoid performing file check IO when loading them. Enabling this option will do the same for physical files[Http]UserAgent= ;Override the user agent used by APIs requiring a user agentDisableCertificateValidation=False ;Indiciates whether certificate validations for the .NET API should be disabled[TranslationAggregator]Width=400 ;The total width of the translation aggregator window.Height=100 ;The width (per translator) of the translation aggregator window.EnabledTranslators= ;The id's of the translation endpoints that has been enabled in the translation aggregator window. List is separated by ';'.[Google]ServiceUrl= ;OPTIONAL, can be used to direct google API request to a different URL. Can be used to circumvent GFWoC[GoogleLegitimate]GoogleAPIKey= ;OPTIONAL, needed if GoogleTranslateLegitimate is configured[BingLegitimate]OcpApimSubscriptionKey= ;OPTIONAL, needed if BingTranslateLegitimate is configured[Baidu]BaiduAppId= ;OPTIONAL, needed if BaiduTranslate is configuredBaiduAppSecret= ;OPTIONAL, needed if BaiduTranslate is configured[Yandex]YandexAPIKey= ;OPTIONAL, needed if YandexTranslate is configured[Watson]Url= ;OPTIONAL, needed if WatsonTranslate is configuredKey= ;OPTIONAL, needed if WatsonTranslate is configured[DeepL]MinDelay=2 ;OPTIONAL, used for throttling DeepLMaxDelay=7 ;OPTIONAL, used for throttling DeepL[DeepLLegitimate]ApiKey= ;OPTIONAL, required if DeepLLegitimate is configuredFree=False ;OPTIONAL, required if DeepLLegitimate is configured[Custom]Url= ;Optional, needed if CustomTranslated is configured[LecPowerTranslator15]InstallationPath= ;Optional, needed if LecPowerTranslator15 is configured[LingoCloud]LingoCloudToken= ;Optional, needed if LingoCloudTranslate is configured[Debug]EnableConsole=False ;Enables the console. Do not enable if other plugins (managers) handles thisEnableLog=False ;Enables extra logging for debugging purposes[Migrations]Enable=True ;Used to enable automatic migrations of this configuration fileTag=4.15.0 ;Tag representing the last version this plugin was executed under. Do not edit

Text Frameworks

The following text frameworks are supported.

• UGUI
• NGUI
• IMGUI (disabled by default)
• TextMeshPro
• TextMesh (disabled by default, often text float in 3D space)
• FairyGUI for Unity
• Utage (VN Game Engine)

Frequently Asked Questions

Q: How do I disable auto translations?
A: Select the empty endpoint when you press ALT+0 or set the configuration parameter Endpoint= to empty.

Q: How do I disable the plugin entirely?
A: You can do so by deleting the "XUnity.AutoTranslator" directory in the "{GameDirectory}\BepInEx\plugins" directory. Avoid deleting the "XUnity.ResourceRedirector" directory as other plugins may depend on it.

Q: The game stops working when this plugin applies translations.
A: Try setting the following configuration parameter TextGetterCompatibilityMode=True.

Q: Can this plugin translate other plugins/mods?
A: Likely yes, see here.

Q: How do I use CustomTranslate?
A: If you have to ask, you probably can't. CustomTranslate is intended for developers of a translation service. They would be able to expose an API that conforms to CustomTranslate's API specification without needing to implement a custom ITranslateEndpoint in this plugin as well.

Q: Please provide support for translation service X.
A: For now, additional support for services that does not require some form of authentication is unlikely. Do note though, that it is possible to implement custom translators independently of this plugin. And it takes remarkably little code to do so.

Translating Mods

Often other mods UI are implemented through IMGUI. As you can see above, this is disabled by default. By changing the "EnableIMGUI" value to "True", it will start translating IMGUI as well, which likely means that other mods UI will be translated.

It is also possible to provide plugin-specific translations. See next section.

Manual Translations

When you use this plugin, you can always go to the file Translation\{Lang}\Text\_AutoGeneratedTranslations.txt (OutputFile) to edit any auto generated translations and they will show up the next time you run the game. Or you can press (ALT+R) to reload the translation immediately.

It is also worth noting that this plugin will read all text files (*.txt) in the Translation (Directory), so if you want to provide a manual translation, you can simply cut out texts from the Translation\_AutoGeneratedTranslations.{lang}.txt (OutputFile) and place them in new text files in order to replace them with a manual translation. These text files can also be placed in standard .zip archives.

In this context, the Translation\{Lang}\Text\_AutoGeneratedTranslations.txt (OutputFile) will always have the lowest priority when reading translations. So if the same translation is present in two places, it will not be the one from the (OutputFile) that is used.

In some ADV engines text 'scrolls' into place slowly. Different techniques are used for this and in some instances if you want the translated text to be scrolling in instead of the untranslated text, you may need to set GeneratePartialTranslations=True. This should not be turned on unless required by the game.