H073.Local 1.3.1

HxLocal API Documentation

Introduction

The Localisation class within the HxLocal namespace is a comprehensive tool for managing localizations by reading translations from JSON files. Whether you're catering to a monolingual audience or a global community, this utility makes handling translations effortless and efficient.

Initial Configuration

Default Folder

By default, the class looks for translations in a directory named "Lingos". This directory should house JSON files corresponding to each supported language (e.g., "en.json" for English, "de.json" for German).

Custom Folder Path:

Should you prefer a different directory for your translations, modify the FilePath property before loading a language or fetching translations:

Localisation.FilePath = "YourCustomDirectory";

⚠️ Important: Adjust the folder path prior to any other API calls to ensure accurate directory referencing.

Working with the API

1. Loading Languages:

To activate a specific language, use the LoadLanguage function:

Localisation.LoadLanguage("fr");  // Loads the French translations

For this example, "fr" denotes the language code for French.

Language Change Event:

When loading a new language, you may want to react to the change. The OnLanguageChange event allows you to do just that:

Localisation.OnLanguageChange += (sender, e) => 
{
    Console.WriteLine($"Language changed from {e.PrevLanguage} to {e.CurrLanguage}.");
};
Localisation.LoadLanguage("de");  // Output: Language changed from en to de.

This provides a hook to execute custom logic whenever the language changes, such as updating UI elements.

Exception Handling:

Loading a language might trigger exceptions. Here's a way to handle them:

try
{
    Localisation.LoadLanguage("fr");  // Attempting to load French translations.
}
catch(LanguageNotFoundException ex)
{
    Console.WriteLine(ex.Message);  // Language file might be missing.
}
catch(JsonParseException ex)
{
    Console.WriteLine(ex.Message);  // Issue parsing the JSON content.
}
catch(IOOperationException ex)
{
    Console.WriteLine(ex.Message);  // I/O-related exceptions.
}

2. Fetching Translations:

To access translated content, employ the GetString method:

var greeting = Localisation.GetString("greeting");

For nested translations within the JSON structure, utilize dot notation:

var morningGreeting = Localisation.GetString("morning.greeting.hello");

3. Formatted Strings:

To incorporate variables within the translations, the GetString function supports additional arguments:

var personalizedGreeting = Localisation.GetString("greetingWithName", "Alice");

In this scenario, given the translation reads: "greetingWithName": "Hello, {0}!", the output would be "Hello, Alice!".

4. Available Languages:

To display supported languages:

var languages = Localisation.ListAvailableLanguages();
foreach(var lang in languages)
{
    Console.WriteLine(lang);  // Outputs available language codes.
}

This method peruses the specified directory, detecting JSON files and returning their names (sans file extensions).

5. Refreshing Loaded Language:

For instances where the active language file gets updated and you wish to synchronize the changes without altering languages, invoke the Reload method:

Localisation.Reload();

This action reinterprets the current language's JSON file, refreshing the internal datastore.

Sample JSON Translation Files

English (en.json):

{
    "greeting": "Hello",
    "farewell": "Goodbye",
    "welcomeMessage": "Welcome aboard!",
    "parent": {
        "child": {
            "message": "Here's a nested message."
        }
    },
    "greetingWithName": "Hello, {0}!",
    "morning": {
        "greeting": {
            "hello": "Top of the morning to you!"
        }
    }
}

Spanish (es.json):

{
    "greeting": "Hola",
    "farewell": "Adiós",
    "welcomeMessage": "¡Bienvenido a bordo!",
    "parent": {
        "child": {
            "message": "Aquí hay un mensaje anidado."
        }
    },
    "greetingWithName": "¡Hola, {0}!",
    "morning": {
        "greeting": {
            "hello": "¡Buenos días!"
        }
    }
}

Conclusion

The HxLocal API is your ticket to seamless multilingual support in applications. With its capability to manage translations from JSON files efficiently, users are guaranteed content aptly tailored to their linguistic preferences.