Basic Usage

This guide covers the fundamental patterns for using Lexis in your Unity project.

Initialization

Lexis auto-initializes on first access, but you can explicitly initialize for more control:

using Lexis;

void Start()
{
    // Auto-loads settings from Resources/LocalizationSettings
    Localization.Initialize();

    // Or with custom settings
    Localization.Initialize(customSettings);
}

Getting Translations

Simple Lookup

// Search all tables for the key
string text = Localization.Get("ui.title");

// From a specific table
string text = Localization.Get("ui", "title");

With Format Arguments

// Positional arguments
string message = Localization.Get("welcome.message", playerName, level);

// From specific table with arguments
string score = Localization.Get("ui", "score.format", scoreValue);

Check Translation Exists

bool exists = Localization.HasTranslation("ui.title");
bool existsInLocale = Localization.HasTranslation("ui.title", "de");
bool existsInTable = Localization.HasTranslation("ui", "title", "de");

Changing Languages

// Set by locale code
Localization.SetLocale("de");

// Set by locale object
Localization.SetLocale(germanLocale);

// Get available locales
IReadOnlyList<Locale> locales = Localization.AvailableLocales;

// Get current locale
Locale current = Localization.CurrentLocale;

Responding to Language Changes

Subscribe to locale changes to update your UI:

void OnEnable()
{
    Localization.OnLocaleChanged += HandleLocaleChanged;
}

void OnDisable()
{
    Localization.OnLocaleChanged -= HandleLocaleChanged;
}

void HandleLocaleChanged(Locale newLocale)
{
    // Update all text in your UI
    RefreshUI();
}

Using LocalizedString

LocalizedString is a serializable struct for Inspector fields:

public class UIPanel : MonoBehaviour
{
    [SerializeField] private LocalizedString titleText;
    [SerializeField] private LocalizedString scoreFormat;

    public void UpdateUI(int score)
    {
        // Implicit conversion to string
        titleLabel.text = titleText;

        // With formatting
        scoreLabel.text = scoreFormat.GetValue(score);
    }
}

LocalizedString Properties

LocalizedString ls = new LocalizedString("ui", "title");

string tableId = ls.TableId;     // "ui"
string key = ls.Key;             // "title"
string value = ls.Value;         // Current locale translation
bool isValid = ls.IsValid;       // Has valid key
bool hasTranslation = ls.HasTranslation; // Translation exists

System Locale Detection

// Detect best matching system locale
Locale detected = Localization.DetectSystemLocale();

// Auto-detect is also available via settings:
// LocalizationSettings.DetectSystemLocale = true;

Table Management

Register and unregister tables at runtime for DLC or dynamic content:

// Register a new table
Localization.RegisterTable(dlcTable);

// Unregister when no longer needed
bool removed = Localization.UnregisterTable("dlc-table-id");

// Get a loaded table
StringTable table = Localization.GetTable("main");

Best Practices

1. Initialize early - Call Localization.Initialize() in your loading sequence
2. Subscribe to changes - Always handle OnLocaleChanged in UI components
3. Use LocalizedString - Prefer Inspector-configured strings over hardcoded keys
4. Cache translations - In hot paths, cache LocalizedString.Value instead of calling Get() repeatedly
5. Use table IDs - For large projects, use explicit table IDs to avoid key collisions