BerylliumLocalizationManager 1.5.0

BerylliumLocalizationManager

Localization manager for simple and efficient switching between languages. It reads the localization folders produced by Beryllium Localization Helper and serves translated texts by string ID: pick a current language, look strings up, keep translation files in memory, and bind callbacks that follow every language switch.

• Targets .NET 10, no dependencies.
• Nothing throws for a bad folder or a bad lookup: every operation is a Try... method with an error message.

Installation

dotnet add package BerylliumLocalizationManager

Localization folder layout

The folder is written by Beryllium Localization Helper and looks like this:

<localization folder>/
  Languages.manifest        languages: english name, local name, reference flag
  FilesStructure.manifest   tree of folders and translation files
  StringIDs.manifest        string IDs and the file each one belongs to
  <language english name>/  one folder per language, mirroring the files structure
    Menus/
      main.json             { "string_id": "translated text", ... }

Translation files are plain JSON objects mapping a string ID to its text. An empty text means "not translated yet". The manifests only store what cannot be derived: paths come from the tree, translation status from the files.

Quick start

using BerylliumLocalizationManager;

var localization = new LocalizationManager();

if (!localization.TryLoadLocalizationFolder(@"D:\Game\Localization", out var error))
    throw new InvalidOperationException(error);

// the reference language is a good default until the player picks one
localization.TrySetCurrentLanguage(localization.ReferenceLanguage!.EnglishName, out _);

// read the whole language into memory once, then lookups never touch the disk
localization.TryCacheAllFiles(out _);

if (localization.TryGetLocalizedStringById("menu_start", out var text, out error))
    Console.WriteLine(text);
else
    Console.WriteLine($"menu_start: {error}");

// a bound callback receives the text now and after every language switch
localization.TryBindToStringId("menu_start", value => startButton.Text = value, out _);

localization.TrySetCurrentLanguage("Ukrainian", out _); // startButton.Text is updated

Behaviour worth knowing

• Untranslated strings. A string whose text is empty (or null) in the translation file is not translated. A lookup fails with Language doesn't have localized version for this string ID, and a bound callback receives an empty string. To fall back, look the string up in ReferenceLanguage yourself.
• Caching. Lookups keep the translation file they read in memory (cacheContainingFile defaults to true), so a string costs one file read the first time and a dictionary lookup afterwards. TryCacheAllFiles preloads a whole language, ClearCache drops everything. A cached file is not re-read when it changes on disk; reload the folder or clear the cache.
• Bindings. A callback is registered once per string ID and callbacks run in the order they were bound. When a language switch runs your OnLanguageChanged handlers and bound callbacks, an exception thrown by one of them does not stop the others and does not leave the manager half-updated: the switch completes, then the exceptions are rethrown together as an AggregateException.
• Reloading. TryLoadLocalizationFolder can be called again, for the same or another folder. When it fails nothing changes and the previous folder stays usable. When it succeeds the cache is dropped, the current language is kept if the new folder has a language with the same English name (otherwise it becomes null and OnLanguageChanged is raised), and every bound callback receives its text again.
• Names and paths. Language names and relative file paths are matched ignoring letter case, and a relative path may use either separator (Menus/main.json or Menus\main.json). String IDs are case-sensitive. Paths are always resolved inside the localization folder; a manifest pointing outside of it is rejected.
• Corrupted folders. A missing or malformed manifest, a files structure that is not a tree, or duplicate names and IDs make the load fail with a message that names the problem.
• Threading. One instance serves one folder and is meant to be used from one thread at a time.

API overview

Compatibility

Version 1.5.0 reads the folders written by Beryllium Localization Helper 1.1 and later (paths derived from the tree, translation status derived from the files) and also the folders written by earlier versions, which stored both in the manifests. Version 1.0.0 only reads the earlier folders.

Changelog

1.5.0

• Targets .NET 10.
• Reads the current localization helper format; earlier folders still load.
• Translation files are cached by default; TryCacheAllFiles preloads a language.
• Language names and relative paths ignore letter case; relative paths accept either separator.
• A folder can be reloaded in place; a failed load keeps the previous folder.
• Exceptions from handlers and bound callbacks no longer interrupt a language switch; they are rethrown together afterwards.
• Paths are confined to the localization folder; corrupted manifests are reported instead of crashing.
• ReferenceLanguage, IsLoaded, LocalizationFolderPath and FileEntry.RelativeFilePath added.
• Newtonsoft.Json dependency removed.
• Breaking: LanguageEntry.TranslatedStringIDs removed; Languages, Files and StringIDs are read-only; a lookup of an untranslated string fails whether or not its file is cached.