Localization System Documentation

Overview

This documentation provides a comprehensive guide on how to implement and use the I2 Localization system within your Unity project, specifically utilizing the LocalizationMapping script for dynamic data. The system integrates seamlessly with the I2 Localization asset from the Unity Asset Store, allowing developers to manage multi-language support with ease.

Links to Important Resources:

1. Setting Up I2 Localization

Before utilizing the LocalizationMapping script, ensure that I2 Localization is properly installed in your Unity project:

  1. Download and import the I2 Localization asset from the Unity Asset Store.
  2. Set up the I2 Localization system by creating a new Localization Source and defining the languages you wish to support.
  3. Define localization terms using the I2 Localization editor or through the script for dynamic management.

For detailed setup instructions, refer to the I2 Localization Official Documentation.

2. Integration of LocalizationMapping Script

The LocalizationMapping script facilitates dynamic localization by allowing translations to be managed at runtime using JSON data. Here’s how to integrate and use this script in your project:

2.1 Script Overview

The LocalizationMapping script provides the following core functionalities:

  • Localize a Term: Updates or sets translations for a specific term in multiple languages.
  • Localize a Text Object: Adds a term to the I2 Localization system if it doesn’t exist and applies the corresponding translations.
  • Assign Parameters: Sets dynamic parameters within localized strings, with special handling for languages like Arabic.

2.2 Script Usage

2.2.1 Dynamic Localization with JSON Data

The system expects JSON data as input for translations. Here’s how to use the script with JSON data:

  1. Prepare the JSON Data:

    Ensure that your JSON data structure matches the expected format.

    {
    "term": "GREETING_TERM",
    "translations": {
        "en": "Hello, World!",
        "ar": "مرحبا بالعالم"
    }
}

  2. Parse the JSON Data:

    Use Unity’s JsonUtility or a similar library to parse the JSON data into a dictionary.

    string jsonData = /* your JSON string */;
var localizationData = JsonUtility.FromJson<LocalizationData>(jsonData);

// Convert to Dictionary<string, string>
Dictionary<string, string> translations = new Dictionary<string, string>
{
    { "en", localizationData.translations["en"] },
    { "ar", localizationData.translations["ar"] }
};

    Ensure that LocalizationData is a class that matches the JSON structure:

    [Serializable]
public class LocalizationData
{
    public string term;
    public Dictionary<string, string> translations;
}

  3. Localize the Term:

    With the parsed data, call the Localize method to dynamically update the term in I2 Localization.

    LocalizationMapping.Localize(localizationData.term, translations);

2.2.2 Localizing Text Objects

If you are working with Localize components attached to UI elements or other GameObjects:

  1. Get the Localize Component: Attach the necessary component to your GameObject.

  2. Apply the Localization: Apply the localization to the text object using the provided dictionary.

2.2.3 Parameterization in Localization

When localization terms include parameters (e.g., {0}, {1} placeholders):

  1. Get the LocalizationParamsManager Component: Attach or find the component in your GameObject.

  2. Assign Parameter Values: Set the values for the placeholders dynamically.

3. Special Considerations

  • Arabic Language Handling: The script includes specific logic for handling Arabic text, such as replacing "ARABIC LETTER FARSI YEH" with "ARABIC LETTER YEH." This ensures proper display of Arabic text in Unity.

  • Adding New Languages: While the script primarily demonstrates English and Arabic, it can be extended to support additional languages. Simply add new key-value pairs to the dictionary and modify the script accordingly.

4. Example Usage

Here’s a complete example of how to use the LocalizationMapping script with dynamic JSON data.

string jsonData = @"
{
    ""localize"": {
        ""en"": ""Welcome to the Game!"",
        ""ar"": ""مرحبًا بكم في اللعبة!""
    }
}";

var localizationData = JsonUtility.FromJson<LocalizationData>(jsonData);
Dictionary<string, string> translations = new Dictionary<string, string>
{
    { "en", localizationData.localize["en"] },
    { "ar", localizationData.localize["ar"] }
};

LocalizationMapping.Localize(localizeObject, translations);

5. Further Reading

For more detailed information on customizing and extending I2 Localization, refer to the official I2 Localization Documentation.