H073.Local 1.2.0

HxLocal API Documentation

Introduction

The Localisation class within the HxLocal namespace is a robust localization management tool that reads translations from JSON files. Whether your project requires a single language or supports several, this tool simplifies the translation process by storing and retrieving localized content based on user preferences.

Initial Configuration

Default Folder

The class assumes that translations are stored in a directory named "Lingos". This directory should contain JSON files named according to the respective language codes (e.g., "en.json" for English, "de.json" for German).

Custom Folder Path:

If your translations reside in a different directory, ensure you configure the FilePath property before attempting to load a language or fetch translations:

Localisation.FilePath = "YourCustomDirectory";

⚠️ Important: Modify the folder path prior to invoking any other functions from the API to guarantee accurate directory referencing.

Working with the API

1. Loading Languages:

Initiate the desired language into memory by utilizing the LoadLanguage function:

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

Here, "fr" represents the language code for French.

2. Fetching Translations:

For translated content, invoke the GetString function:

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

For translations nested within JSON objects, use dot notation to pinpoint the desired text:

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

3. Formatted Strings:

To include variables within the translations or to adjust them dynamically, the GetString method can accept arguments:

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

Assuming the related translation is akin to: "greetingWithName": "Hello, {0}!", the result would be "Hello, Alice!".

4. Available Languages:

To discern the languages your application supports:

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

This function scans the designated directory for JSON files and returns an array of their names without the file extension.

5. Refreshing Loaded Language:

If you've made updates to the currently loaded language file and wish to refresh the data without switching languages, use the Reload method:

Localisation.Reload();

This re-reads the JSON file for the current language and updates the internal data store.

Sample JSON Translation Files

English (en.json):

{
    "greeting": "Hello",
    "farewell": "Goodbye",
    "welcomeMessage": "Welcome to our platform!",
    "parent": {
        "child": {
            "message": "This is a nested message."
        }
    },
    "greetingWithName": "Hello, {0}!",
    "morning": {
        "greeting": {
            "hello": "Good morning!"
        }
    }
}

Spanish (es.json):

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

Conclusion

The HxLocal localization tool is designed to streamline the multilingual support in your applications. By efficiently managing translations from JSON files, it ensures that your users enjoy content tailored to their linguistic preferences.