XUnity.AutoTranslator

# XUnity Auto Translator

Text Frameworks

This is an auto translation mod that hooks into the unity game engine and attempts to provide translations for the following text frameworks for Unity:

• UGUI
• NGUI
• IMGUI
• TextMeshPro
• Utage (VN Game Engine)

It does go to the internet, in order to provide the translation, so if you are not comfortable with that, dont use it.

Plugin Frameworks

The mod can be installed into the following Plugin Managers:

• BepInEx
• IPA
• UnityInjector

Installations instructions for both methods can be found below.

Additionally it can be installed without a dependency on a plugin manager through ReiPatcher. However, this approach is not recommended if you use one of the above mentioned Plugin Managers!

Configuration

The default configuration file, looks as such (2.6.0+):

[Service]
Endpoint=GoogleTranslate         ;Endpoint to use. Can be ["GoogleTranslate", "GoogleTranslateLegitimate", "BaiduTranslate", "YandexTranslate", "WatsonTranslate", "ExciteTranslate", ""]. If empty, it simply means: Only use cached translations

[General]
Language=en                      ;The language to translate into
FromLanguage=ja                  ;The original language of the game

[Files]
Directory=Translation                                          ;Directory to search for cached translation files
OutputFile=Translation\_AutoGeneratedTranslations.{lang}.txt   ;File to insert generated translations into

[TextFrameworks]
EnableUGUI=True                  ;Enable or disable UGUI translation
EnableNGUI=True                  ;Enable or disable NGUI translation
EnableTextMeshPro=True           ;Enable or disable TextMeshProp translation
EnableIMGUI=False                ;Enable of disable IMGUI translation
AllowPluginHookOverride=True     ;Allow other text translation plugins to override this plugin's hooks

[Behaviour]
Delay=0                          ;Delay to wait before attempting to translate a text in seconds
MaxCharactersPerTranslation=150  ;Max characters per text to translate
IgnoreWhitespaceInDialogue=True  ;Whether or not to ignore whitespace, including newlines, in dialogue keys
IgnoreWhitespaceInNGUI=True      ;Whether or not to ignore whitespace, including newlines, in NGUI
MinDialogueChars=20              ;The length of the text for it to be considered a dialogue
ForceSplitTextAfterCharacters=0  ;Split text into multiple lines once the translated text exceeds this number of characters
CopyToClipboard=False            ;Whether or not to copy hooked texts to clipboard
MaxClipboardCopyCharacters=450   ;Max number of characters to hook to clipboard at a time
EnableUIResizing=True            ;Whether or not the plugin should provide a "best attempt" at resizing UI components upon translation. Only work for NGUI
EnableBatching=True              ;Indicates whether batching of translations should be enabled for supported endpoints
TrimAllText=True                 ;Indicates whether spaces in front and behind translation candidates should be removed before translation
UseStaticTranslations=True       ;Indicates whether or not to use translations from the included static translation cache
OverrideFont=                    ;Overrides the fonts used for texts when updating text components. NOTE: Only works for UGUI
WhitespaceRemovalStrategy=TrimPerNewline ;Indicates how whitespace/newline removal should be handled before attempting translation. Can be ["TrimPerNewline", "AllOccurrences"]

[Http]
UserAgent=                       ;Override the user agent used by APIs requiring a user agent

[GoogleLegitimate]
GoogleAPIKey=                    ;OPTIONAL, needed if GoogleTranslateLegitimate is configured

[Baidu]
BaiduAppId=                      ;OPTIONAL, needed if BaiduTranslate is configured
BaiduAppSecret=                  ;OPTIONAL, needed if BaiduTranslate is configured

[Yandex]
YandexAPIKey=                    ;OPTIONAL, needed if YandexTranslate is configured

[Watson]
WatsonAPIUrl=                    ;OPTIONAL, needed if WatsonTranslate is configured
WatsonAPIUsername=               ;OPTIONAL, needed if WatsonTranslate is configured
WatsonAPIPassword=               ;OPTIONAL, needed if WatsonTranslate is configured

[Debug]
EnablePrintHierarchy=False       ;Used for debugging
EnableConsole=False              ;Enables the console. Do not enable if other plugins (managers) handles this
EnableLog=False                  ;Enables extra logging for debugging purposes

[Migrations]
Enable=True                      ;Used to enable automatic migrations of this configuration file
Tag=2.9.0                        ;Tag representing the last version this plugin was executed under. Do not edit

Key Mapping

The following key inputs are mapped:

• ALT + T: Alternate between translated and untranslated versions of all texts provided by this plugin.
• ALT + D: Dump untranslated texts (if no endpoint is configured)
• ALT + R: Reload translation files. Useful if you change the text files on the fly.
• ALT + U: Manual hooking. The default hooks wont always pick up texts. This will attempt to make lookups manually.

Installation

The plugin can be installed in following ways:

BepInEx Plugin

REQUIRES: BepInEx plugin manager (follow its installation instructions first!).

1. Download XUnity.AutoTranslator-BepIn-{VERSION}.zip from releases.
2. Extract directly into the game directory, such that the plugin dlls are placed in BepInEx folder.

The file structure should like like this:

{GameDirectory}/BepInEx/XUnity.AutoTranslator.Plugin.Core.dll
{GameDirectory}/BepInEx/XUnity.AutoTranslator.Plugin.Core.BepInEx.dll
{GameDirectory}/BepInEx/ExIni.dll
{GameDirectory}/BepInEx/Translation/AnyTranslationFile.txt (these files will be auto generated by plugin!)

IPA Plugin

REQUIRES: IPA plugin manager (follow its installation instructions first!).

1. Download XUnity.AutoTranslator-IPA-{VERSION}.zip from releases.
2. Extract directly into the game directory, such that the plugin dlls are placed in Plugins folder.

The file structure should like like this

{GameDirectory}/Plugins/XUnity.AutoTranslator.Plugin.Core.dll
{GameDirectory}/Plugins/XUnity.AutoTranslator.Plugin.Core.IPA.dll
{GameDirectory}/Plugins/0Harmony.dll
{GameDirectory}/Plugins/ExIni.dll
{GameDirectory}/Plugins/Translation/AnyTranslationFile.txt (these files will be auto generated by plugin!)

UnityInjector Plugin

REQUIRES: UnityInjector (follow its installation instructions first!).

1. Download XUnity.AutoTranslator-UnityInjector-{VERSION}.zip from releases.
2. Extract directly into the game directory, such that the plugin dlls are placed in UnityInjector folder. This may not be game root directory!

The file structure should like like this

{GameDirectory}/UnityInjector/XUnity.AutoTranslator.Plugin.Core.dll
{GameDirectory}/UnityInjector/XUnity.AutoTranslator.Plugin.Core.UnityInjector.dll
{GameDirectory}/UnityInjector/0Harmony.dll
{GameDirectory}/UnityInjector/ExIni.dll
{GameDirectory}/UnityInjector/Translation/AnyTranslationFile.txt (these files will be auto generated by plugin!)

Standalone Installation (ReiPatcher)

REQUIRES: Nothing, ReiPatcher is provided by this download.

1. Download XUnity.AutoTranslator-ReiPatcher-{VERSION}.zip from releases.
2. Extract directly into the game directory, such that "SetupReiPatcherAndAutoTranslator.exe" is placed alongside other exe files.
3. Execute "SetupReiPatcherAndAutoTranslator.exe". This will setup up ReiPatcher correctly.
4. Execute the shortcut {GameExeName}.lnk that was created besides existing executables. This will patch and launch the game.
5. From now on you can launch the game from the {GameExeName}.exe instead.

The file structure should like like this

{GameDirectory}/ReiPatcher/Patches/XUnity.AutoTranslator.Patcher.dll
{GameDirectory}/ReiPatcher/ExIni.dll
{GameDirectory}/ReiPatcher/Mono.Cecil.dll
{GameDirectory}/ReiPatcher/Mono.Cecil.Inject.dll
{GameDirectory}/ReiPatcher/Mono.Cecil.Mdb.dll
{GameDirectory}/ReiPatcher/Mono.Cecil.Pdb.dll
{GameDirectory}/ReiPatcher/Mono.Cecil.Rocks.dll
{GameDirectory}/ReiPatcher/ReiPatcher.exe
{GameDirectory}/{GameExeName}_Data/Managed/ReiPatcher.exe
{GameDirectory}/{GameExeName}_Data/Managed/XUnity.AutoTranslator.Plugin.Core.dll
{GameDirectory}/{GameExeName}_Data/Managed/0Harmony.dll
{GameDirectory}/{GameExeName}_Data/Managed/ExIni.dll
{GameDirectory}/AutoTranslator/AnyTranslationFile.txt (these files will be auto generated by plugin!)

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.

Integrating with Auto Translator

Implementing a dedicated translation component

As a mod author implementing a translation plugin, you are able to, if you cannot find a translation to a string, simply delegate it to this mod, and you can do it without taking any references to this plugin.

Here's how it works, and what is required:

• You must implement a Component (MonoBehaviour for instance) that this plugin is able to locate by simply traversing all objects during startup.
• On this component you must add an event for the text hooks you want to override from XUnity AutoTranslator. This is done on a per text framework basis. The signature of these events must be: Func. The arguments are, in order:
  1. The component that represents the text in the UI. (The one that probably has a property called 'text').
  2. The untranslated text
  3. This is the return value and will be the translated text IF an immediate translation took place. Otherwise it will simply be null.
• The signature for each framework looks like:
  1. UGUI: public static event Func OnUnableToTranslateUGUI
  2. TextMeshPro: public static event Func OnUnableToTranslateTextMeshPro
  3. NGUI: public static event Func OnUnableToTranslateNGUI
  4. IMGUI: public static event Func OnUnableToTranslateIMGUI
  5. Also, the events can be either instance based or static.

  Implementing a component that the Auto Translator should not interfere with

  As a mod author, you might not want the Auto Translator to interfere with your mods UI. If this is the case there's two ways to tell Auto Translator not to perform any translation:

  • If your UI is based on GameObjects, you can simply name your GameObjects containing the text element (for example Text class) to something that contains the string "XUAIGNORE". The Auto Translator will check for this and ignore components that contains the string.

  • If your UI is based on IMGUI, the above approach is not possible, because there are no GameObject. In that case you can do the following instead:

    public class MyPlugin : XPluginBase
    {
    private GameObject _xua;
    private bool _lookedForXua;
    
    public void OnGUI()
    {
      // make sure we only do this lookup once, as it otherwise may be detrimental to performance!
      // also: do not attempt to do this in the Awake method or similar of your plugin, as your plugin may be instantiated before the auto translator!
      if(!_lookedForXua)
      {
         _lookedForXua = true;
         _xua = GameObject.Find( "___XUnityAutoTranslator" );
      }
    
      // try-finally block is important to make sure you re-enable the plugin
      try
      {
         _xua?.SendMessage("DisableAutoTranslator");
    
         // do your GUI things here
         GUILayout.Button( "こんにちは！" );
      }
      finally
      {
         _xua?.SendMessage("EnableAutoTranslator");
      }
    }
    }
    

  This approach requires version 2.15.0 or later!