Merge pull request #119 from All-Of-Us-Mods/translation-improvements

Optimised localisation system
This commit is contained in:
AS authored and GitHub committed 2026-11-11 02:46:32 -05:00
commit 85daa0aded
1 file changed
+162 -154
+162 -154
View File
@@ -4,6 +4,7 @@ using System.IO;
using System.Linq;
using System.Reflection;
using System.Xml;
using AmongUs.Data;
using MiraAPI.Utilities;
using Reactor.Localization.Utilities;
using UnityEngine;
@@ -16,6 +17,8 @@ namespace MiraAPI.Translation;
public static class MiraLocaleManager
{
private const string LangDirectory = "mira_languages";
private const string RefPrefix = "@ref:";
private const int MaxDepth = 10;
// Language, XML Name, then Value
@@ -40,6 +43,7 @@ public static class MiraLocaleManager
/// </summary>
public static Dictionary<MiraLanguage, string> LangList { get; } = new()
{
// Vanilla
{ MiraLanguage.English, "en_US" },
{ MiraLanguage.Latam, "es_419" },
{ MiraLanguage.Brazilian, "pt_BR" },
@@ -56,51 +60,26 @@ public static class MiraLocaleManager
{ MiraLanguage.SChinese, "zh_CN" },
{ MiraLanguage.TChinese, "zh_TW" },
{ MiraLanguage.Irish, "ga_IE" },
{ MiraLanguage.Polish, "pl_PL" }, // Custom
{ MiraLanguage.Turkish, "tr_TR" }, // Custom
{ MiraLanguage.Swedish, "sv_SE" }, // Custom
{ MiraLanguage.Lithuanian, "lt_LT" }, // Custom
{ MiraLanguage.Czech, "cs_CZ" }, // Custom
{ MiraLanguage.LChinese, "lzh_CN" }, // Custom
{ MiraLanguage.Greek, "el_GR" }, // Custom
{ MiraLanguage.Arabic, "arb" }, // Custom
{ MiraLanguage.Hebrew, "heb" }, // Custom
// Custom
{ MiraLanguage.Polish, "pl_PL" },
{ MiraLanguage.Turkish, "tr_TR" },
{ MiraLanguage.Swedish, "sv_SE" },
{ MiraLanguage.Lithuanian, "lt_LT" },
{ MiraLanguage.Czech, "cs_CZ" },
{ MiraLanguage.LChinese, "lzh_CN" },
{ MiraLanguage.Greek, "el_GR" },
{ MiraLanguage.Arabic, "arb" },
{ MiraLanguage.Hebrew, "heb" },
};
private static readonly Dictionary<string, MiraLanguage> ReverseLangLookup =
LangList.ToDictionary(x => x.Value, x => x.Key);
/// <summary>
/// Gets a dictionary mapping <see cref="MiraLanguage"/> values to their standard language codes.
/// </summary>
public static Dictionary<MiraLanguage, string> LangCultureList { get; } = new()
{
// Vanilla
{ MiraLanguage.English, "en-US" },
{ MiraLanguage.Latam, "es-419" },
{ MiraLanguage.Brazilian, "pt-BR" },
{ MiraLanguage.Portuguese, "pt-PT" },
{ MiraLanguage.Korean, "ko-KR" },
{ MiraLanguage.Russian, "ru-RU" },
{ MiraLanguage.Dutch, "nl-NL" },
{ MiraLanguage.Filipino, "fil-PH" },
{ MiraLanguage.French, "fr-FR" },
{ MiraLanguage.German, "de-DE" },
{ MiraLanguage.Italian, "it-IT" },
{ MiraLanguage.Japanese, "ja-JP" },
{ MiraLanguage.Spanish, "es-ES" },
{ MiraLanguage.SChinese, "zh-CN" },
{ MiraLanguage.TChinese, "zh-TW" },
{ MiraLanguage.Irish, "ga-IE" },
// Custom
{ MiraLanguage.Polish, "pl-PL" },
{ MiraLanguage.Turkish, "tr-TR" },
{ MiraLanguage.Swedish, "sv-SE" },
{ MiraLanguage.Lithuanian, "lt-LT" },
{ MiraLanguage.Czech, "cs-CZ" },
{ MiraLanguage.LChinese, "lzh-CN" },
{ MiraLanguage.Greek, "el-GR" },
{ MiraLanguage.Arabic, "arb" },
{ MiraLanguage.Hebrew, "heb" },
};
public static Dictionary<MiraLanguage, string> LangCultureList { get; } =
LangList.ToDictionary(x => x.Key, x => x.Value.Replace('_', '-'));
/// <summary>
/// Gets the current language from Among Us settings.
@@ -111,7 +90,7 @@ public static class MiraLocaleManager
{
try
{
var langName = AmongUs.Data.DataManager.Settings.Language.CurrentLanguage;
var langName = DataManager.Settings.Language.CurrentLanguage;
return (MiraLanguage)langName;
}
catch
@@ -121,40 +100,24 @@ public static class MiraLocaleManager
}
}
/// <summary>
/// Registers translations for a mod.
/// Call once per mod during plugin Load().
/// </summary>
/// <param name="modGuid">The mod GUID (e.g., "mira.example").</param>
/// <inheritdoc cref="Register(string, string, Assembly)"/>
[Obsolete("Pass typeof(YourPlugin).Assembly directly to Register for better performance.")]
public static void Register(string modGuid)
{
var callingAssembly = Assembly.GetCallingAssembly();
LoadInternalStrings(callingAssembly, callingAssembly.GetName().Name!, modGuid);
LoadInternalStrings(Assembly.GetCallingAssembly(), modGuid);
}
/// <summary>
/// Registers translations for a mod.
/// Call once per mod during plugin Load().
/// </summary>
/// <param name="modGuid">The mod GUID (e.g., "mira.example").</param>
/// <param name="assembly">The <see cref="Assembly"/> to load the strings from.</param>
/// <inheritdoc cref="Register(string, string, Assembly)"/>
public static void Register(string modGuid, Assembly assembly)
{
LoadInternalStrings(assembly, assembly.GetName().Name!, modGuid);
LoadInternalStrings(assembly, modGuid);
}
/// <summary>
/// Registers translations for a mod.
/// Call once per mod during plugin Load().
/// </summary>
/// <param name="modGuid">The mod GUID (e.g., "mira.example").</param>
/// <param name="internalName">The mod's root namespace (e.g., "mira.api").</param>
/// <inheritdoc cref="Register(string, string, Assembly)"/>
[Obsolete("Pass typeof(YourPlugin).Assembly directly to Register for better performance.")]
public static void Register(string modGuid, string internalName)
{
var callingAssembly = Assembly.GetCallingAssembly();
LoadInternalStrings(callingAssembly, internalName, modGuid);
LoadInternalStrings(Assembly.GetCallingAssembly(), internalName, modGuid);
}
/// <summary>
@@ -169,15 +132,10 @@ public static class MiraLocaleManager
LoadInternalStrings(assembly, internalName, modGuid);
}
/// <summary>
/// Translates a key into the current language.
/// </summary>
/// <param name="key">The string id to find.</param>
/// <param name="fallback">Fallback string to use if no translation is found.</param>
/// <returns>A <see cref="string"/> based on the key provided.</returns>
/// <inheritdoc cref="Get(MiraLanguage, string, string)"/>
public static string Get(string key, string fallback = "")
{
return Get(CurrentLanguage, key, fallback != string.Empty ? fallback : key);
return Get(CurrentLanguage, key, string.IsNullOrEmpty(fallback) ? key : fallback);
}
/// <summary>
@@ -189,34 +147,30 @@ public static class MiraLocaleManager
/// <returns>A <see cref="string"/> based on the key provided.</returns>
public static string Get(MiraLanguage language, string key, string fallback = "")
{
if (Locale.TryGetValue(language, out var translations) &&
translations.TryGetValue(key, out var translation))
{
return translation;
}
var text = Locale.GetValueOrDefault(language)?.GetValueOrDefault(key);
if (Locale.TryGetValue(MiraLanguage.English, out var translationsEng) &&
translationsEng.TryGetValue(key, out var translationEng))
{
return translationEng;
}
if (language != MiraLanguage.English)
text ??= Locale.GetValueOrDefault(MiraLanguage.English)?.GetValueOrDefault(key);
return fallback;
return text ?? fallback;
}
/// <summary>
/// Translates a key into the current language.
/// </summary>
/// <param name="key">The string id to find.</param>
/// <param name="parseList">List of keys to change into other text.</param>
/// <param name="fallback">Fallback string to use if no translation is found.</param>
/// <returns>A <see cref="string"/> based on the key provided.</returns>
/// <inheritdoc cref="GetParsed(MiraLanguage, string, Dictionary{string, string}, string)"/>
public static string GetParsed(
string key,
Dictionary<string, string> parseList,
string fallback = "")
{
return GetParsed(CurrentLanguage, key, parseList, fallback != string.Empty ? fallback : key);
return GetParsed(CurrentLanguage, key, parseList, string.IsNullOrEmpty(fallback) ? key : fallback);
}
/// <inheritdoc cref="GetParsed(MiraLanguage, string, ValueTuple{string, string}[], string)"/>
public static string GetParsed(
string key,
(string, string)[] parseList,
string fallback = "")
{
return GetParsed(CurrentLanguage, key, parseList, string.IsNullOrEmpty(fallback) ? key : fallback);
}
/// <summary>
@@ -233,24 +187,35 @@ public static class MiraLocaleManager
Dictionary<string, string> parseList,
string fallback = "")
{
var text = fallback;
var text = Get(language, key, fallback);
if (Locale.TryGetValue(MiraLanguage.English, out var translationsEng) &&
translationsEng.TryGetValue(key, out var translationEng))
foreach (var (toReplace, value) in parseList)
{
text = translationEng;
text = text.Replace(toReplace, value);
}
if (language is not MiraLanguage.English &&
Locale.TryGetValue(language, out var translations) &&
translations.TryGetValue(key, out var translation))
{
text = translation;
}
return text;
}
foreach (var tmpText in parseList.Where(x => text.Contains(x.Key)))
/// <summary>
/// Translates a key into the current language.
/// </summary>
/// <param name="language">The specific language to prioritize.</param>
/// <param name="key">The string id to find.</param>
/// <param name="parseList">List of keys to change into other text.</param>
/// <param name="fallback">Fallback string to use if no translation is found.</param>
/// <returns>A <see cref="string"/> based on the key provided.</returns>
public static string GetParsed(
MiraLanguage language,
string key,
(string, string)[] parseList,
string fallback = "")
{
var text = Get(language, key, fallback);
foreach (var (toReplace, value) in parseList)
{
text = text.Replace(tmpText.Key, tmpText.Value);
text = text.Replace(toReplace, value);
}
return text;
@@ -268,12 +233,7 @@ public static class MiraLocaleManager
return idPart.StartsWith('#') ? idPart[1..] : $"{modId}.{idPart}.{suffix}";
}
/// <summary>
/// Builds a formatted translation ID string using a mod ID and a specific ID part.
/// </summary>
/// <param name="modId">The mod GUID.</param>
/// <param name="idPart">The core part of the ID. If it starts with '#', the character is stripped.</param>
/// <returns>A formatted translation ID <see cref="string"/>.</returns>
/// <inheritdoc cref="BuildTranslationId(string, string, string)"/>
public static string BuildTranslationId(string modId, string idPart)
{
return idPart.StartsWith('#') ? idPart[1..] : $"{modId}.{idPart}";
@@ -329,16 +289,16 @@ public static class MiraLocaleManager
{
var fileName = Path.GetFileNameWithoutExtension(filePath);
var lang = LangList.ContainsValue(fileName)
? LangList.First(x => x.Value == fileName).Key
: (MiraLanguage)(-1);
if ((int)lang == -1) continue;
if (!ReverseLangLookup.TryGetValue(fileName, out var lang))
{
continue;
}
try
{
Locale.TryAdd(lang, []);
var xmlContent = File.ReadAllText(filePath);
ParseXmlFile(xmlContent, lang, false);
using var fileStream = File.OpenRead(filePath);
ParseXmlFile(fileStream, lang, false);
}
catch (Exception e)
{
@@ -347,6 +307,11 @@ public static class MiraLocaleManager
}
}
private static void LoadInternalStrings(Assembly assembly, string modGuid)
{
LoadInternalStrings(assembly, assembly.GetName().Name!, modGuid);
}
private static void LoadInternalStrings(Assembly assembly, string internalName, string modGuid)
{
var resourcePrefix = $"{internalName}.Resources.Locale.";
@@ -354,27 +319,26 @@ public static class MiraLocaleManager
RegisteredModIds.Add(modGuid);
var atLeastOneLoaded = false;
foreach (var locale in LangList)
foreach (var (lang, name) in LangList)
{
using var resourceStream =
assembly.GetManifestResourceStream(resourcePrefix + locale.Value + ".xml");
using var resourceStream = assembly.GetManifestResourceStream(resourcePrefix + name + ".xml");
if (resourceStream == null)
{
// Silently skipped
continue;
}
using StreamReader reader = new(resourceStream);
var xmlContent = reader.ReadToEnd();
try
{
Locale.TryAdd(locale.Key, []);
ParseXmlFile(xmlContent, locale.Key, true);
Locale.TryAdd(lang, []);
ParseXmlFile(resourceStream, lang, true);
atLeastOneLoaded = true;
}
catch (Exception e)
{
Error($"Failed to load translation {resourcePrefix}{locale.Value}: {e.Message}");
Error($"Failed to load translation {resourcePrefix}{name}: {e.Message}");
}
}
@@ -391,52 +355,96 @@ public static class MiraLocaleManager
/// <param name="language">The language that the xml file corresponds to.</param>
/// <param name="loadingInternal">Flag that indicates if the xml being parsed is internal or not.</param>
public static void ParseXmlFile(string xmlContent, MiraLanguage language, bool loadingInternal)
{
using var stringReader = new StringReader(xmlContent);
using var xmlReader = XmlReader.Create(stringReader);
ParseXml(xmlReader, language, loadingInternal);
}
/// <summary>
/// Parses the provided xml stream into translation keys and values and registers them to the locale manager.
/// </summary>
/// <param name="xmlStream">The stream to the xml content.</param>
/// <param name="language">The language that the xml file corresponds to.</param>
/// <param name="loadingInternal">Flag that indicates if the xml being parsed is internal or not.</param>
public static void ParseXmlFile(Stream xmlStream, MiraLanguage language, bool loadingInternal)
{
using var reader = XmlReader.Create(xmlStream);
ParseXml(reader, language, loadingInternal);
}
private static void ParseXml(XmlReader reader, MiraLanguage language, bool loadingInternal)
{
var dict = Locale[language];
XmlDocument xmlDoc = new();
var total = 0;
var pendingRefs = new Dictionary<string, string>();
try
{
xmlDoc.LoadXml(xmlContent);
var stringNodes = xmlDoc.SelectNodes("/resources/string");
if (stringNodes == null)
while (reader.ReadToFollowing("string"))
{
return;
var name = reader.GetAttribute("name");
if (string.IsNullOrEmpty(name))
continue;
if (loadingInternal && dict.ContainsKey(name))
{
Error($"String for \"{name}\" in {language} was overwritten by a duplicate!");
}
var value = reader.ReadElementContentAsString();
if (value.StartsWith(RefPrefix, StringComparison.Ordinal))
{
pendingRefs[name] = value[RefPrefix.Length..];
}
else
{
value = value.Replace('[', '<')
.Replace(']', '>')
.Replace("<nl>", "\n")
.Replace("<and>", "&");
dict[name] = value;
total++;
}
}
var total = 0;
foreach (XmlNode node in stringNodes)
foreach (var unresolved in pendingRefs)
{
if (node.Attributes?["name"] == null)
var originalKey = unresolved.Key;
var currentTarget = unresolved.Value;
var depth = 0;
var resolved = false;
while (depth < MaxDepth)
{
continue;
if (dict.TryGetValue(currentTarget, out var resolvedValue))
{
dict[originalKey] = resolvedValue;
total++;
resolved = true;
break;
}
if (pendingRefs.TryGetValue(currentTarget, out var nextTarget))
{
currentTarget = nextTarget;
depth++;
}
else
{
Error($"Translation reference '{unresolved.Value}' for '{originalKey}' not found.");
break;
}
}
var name = node.Attributes["name"]!.Value;
var value = node.InnerText;
if (string.IsNullOrEmpty(name)) continue;
if (value.Contains('['))
if (!resolved && depth >= MaxDepth)
{
value = value.Replace('[', '<');
Error($"Circular translation reference or max depth exceeded for '{originalKey}'.");
}
if (value.Contains(']'))
{
value = value.Replace(']', '>');
}
value = value.Replace("<nl>", "\n").Replace("<and>", "&");
if (loadingInternal && Locale[language].ContainsKey(name))
{
Error($"String for \"{name}\" in {language} was overwritten by duplicate!");
}
dict[name] = value;
total++;
}
Info($"Loaded {language.ToDisplayString()} translation with ({total} keys)");