An example translation file can be seen in the
Examples folder in this repository.
Currently the only provided example is for the CM3D2 MutlipleMaids plug-in.
The name of a translation file must be the same as the plugin assembly name that should be translated. For instance, CM3D2.MutlipleMaids.Plugin is to be translated, one must name the translation file
CM3D2.MutlipleMaids.Plugin.txt (the case of the letters does not matter).
Each translation is on its own line:
<Original> is the original string, meanwhile
<Translation> is the translation of the original input.
Note the following:
<Translation>are separated by one (or multiple) TAB character(s).
<Original>strings must be sanitized as follows: newlines (
\n) are not removed; start and end are not trimmed from any whitespace; all other special characters are escaped.
<Translation>can contain special characters, but they must be escaped. For instance, you can use a newline (
\n), a TAB (
\t) or a double quote (
- A line with
Any line that starts with
; is ignored. Use them to set up comments.
Any translation line that starts with
$ becomes a regular expression. If the input string does not match any
<Original>, it is tested against every single specified regular expression.
Any captured groups within a RegEx can be accessed as per the .NET Regual Expression Language specification for subsitutions.
Important concerns to note
Using RegExes reduces performance
Since IMGUI updates almost every in-game update, the translation loader has to retranslate strings very frequently. While IMGUI Transltation Loader can do that very fast when it comes to normal "static" strings, it cannot do so with RegExes. As such, the plug-in has to iterate through every single RegEx to find a match (or to fail to do so). Thus, use RegExes as little as possible!
IMGUI Translation Loader can fail to determine the plug-in assembly
Currently IMGUI Translation Loader works as follows: when an IMGUI element is created, the translation loader looks at the stack trace that lead to the element being created. If any of the assemblies in the stack trace is other than
UnityEngine, it is considered the "plug-in assembly", and the translation loader will look for the string based on its name.
This might not always be true. Thus prepare for instances where the translation loader fails to correctly determine the right plug-in assembly. If that ever happens, consider reporting the issue.