← Back

Instant Localization: Documentation

Setup, Script Reference, Editor Tools Menu, Best Practices, Troubleshooting, and Technical Notes.

Table of Contents

  1. Introduction
  2. Setup Guide (Step-by-Step Tutorial)
  3. Script Reference
  4. Editor Tools Menu Reference
  5. Best Practices
  6. Troubleshooting
  7. Technical Notes

1. Introduction

The Instant Localization asset provides a quick and efficient way to add multilingual support to your Unity project, primarily targeting TextMeshProUGUI components. The system uses static calls to manage language switching and loads localization data from simple CSV files stored in the project's Resources folder.

Key Features:

  • CSV-based localization system supporting any number of languages
  • Runtime language switching with automatic UI refresh
  • TextMeshPro integration via ready-to-use LocalizeText component
  • Powerful Localization Key Selector Window with search, filtering, and bulk editing
  • Built-in Favorites system for quick access to commonly used keys
  • Real-time key management across all language files simultaneously
  • Custom Inspector tools for fast key selection directly from components
  • Search highlighting and alphabetical sorting for large projects
  • AI-powered Auto-Translate Window for batch translation using external providers
  • Translation preview, caching, and selective overwrite controls
↑ Back to top

2. Setup Guide (Step-by-Step Tutorial)

This guide will walk you through the necessary steps to integrate and use the localization system in your project.

↑ Back to top

2.1. Project Structure Setup

The localization system requires a specific folder structure to load language files at runtime using Unity's Resources.Load.

  1. Import TextMeshPro: Ensure you have the TextMeshPro package imported into your project, as the primary component relies on TextMeshProUGUI.
  2. Open Resources Folder: Go to Assets/Instant Localization folder and find folder named Resources. If you do not have one, create a new folder named Resources.
  3. Place CSV Files: Place all your localization data files (e.g., English.csv, Spanish.csv, German.csv) directly into the Assets/Instant Localization/Resources folder.
    • Crucial Naming: The filename (without the .csv extension) is used as the Language Code for switching languages (e.g., English or German).
    • CSV Format: Each CSV file must have a header row: key,text. Each subsequent line should follow the format: localization_key,Translation text / localizationKey,Translation text. Keys must be single identifiers without spaces.

Example CSV Content (English.csv):

/* Example CSV (English.csv) */
key,text
examine,Examine
save_game,Save Game
gamepadSensitivity,Gamepad Sensitivity

↑ Back to top

2.2. Localizing UI Text Components

To make a piece of UI text localizable, you must attach the LocalizeText component.

  1. Add TextMeshPro: Create a UI Text object in your scene (e.g., a TextMeshPro - Text component).
  2. Add LocalizeText Component: Add the LocalizeText.cs script to the same GameObject.
  3. Set the Key: In the Inspector for the LocalizeText component, you will see a field named Localized Text ID with a Search button next to it.
    • Quick Selection (Recommended): Click the Search button to open the Localization Key Selector Window where you can:
      • Browse all available keys
      • Search and filter keys
      • View translations in all languages
      • Add, edit, or delete keys
      • Mark frequently used keys as favorites
    • Manual Entry: Type the localization key directly (e.g., start_button) that exists in your CSV files.
  4. The component will automatically look up the key for the currently active language and display the corresponding text.
  5. If no translation exists for a key, the system returns the key as the fallback value.
↑ Back to top

2.3. Using the Localization Key Selector Window

The Localization Key Selector Window is a powerful editor tool for managing your localization keys. Access it via:

  • Inspector: Click the Search button next to any LocalizeText component's key field
  • Menu: Navigate to Tools > Localization > Open Localization Window (shortcut: Ctrl+Shift+T)

Window Features:

1. Language Selection
  • Switch between languages using the dropdown at the top
  • Preview translations in different languages
2. Search and Filter
  • Use the search bar to filter keys by name or value
  • Use CSV button to open current CSV file in default preview app
  • Toggle Sort A-Z to alphabetically sort keys
  • Search highlights matching text in white
3. Favorites System
  • Click the star icon next to any key to mark it as a favorite
  • Favorites always appear at the top of the list
4. Key Management
  • Add New: Create new keys across all language files simultaneously
  • Edit: Modify existing key translations for all languages at once
  • Delete: Remove keys from all language files
  • View All Translations: Select a key to see its translation in every language
5. Quick Selection
  • Single-click to select a key
  • Double-click to apply the key and close the window
  • Click Select button to apply the selected key
↑ Back to top

2.4. Managing Localization Keys

Manual key/values management guide

Adding New Keys

  1. Click the Add New button at the bottom
  2. Enter the key and translations for each language
  3. Click Create - the key will be added to all CSV files

Editing Existing Keys

  1. Select a key from the list
  2. Click the Edit button
  3. Modify translations for any language
  4. Click Save to update all CSV files

Deleting Keys

  1. Select a key from the list
  2. Click the Delete button
  3. Confirm the deletion - the key will be removed from all CSV files
↑ Back to top

2.5. Switching Languages at Runtime

The active language for the entire application is controlled by the static LocalizationSystem class.

  1. To change the language, call the static SetLanguage method from any of your game scripts. The parameter must match the name of one of your CSV files (the language code).

Example Language Switch Script (C#):

// Switches the game language to Spanish.
// This will automatically load the 'Spanish.csv' file and update all UI texts.
fe1zed.InstantLocalization.LocalizationSystem.SetLanguage("Spanish");

↑ Back to top

2.6. Localize via code (recommended for dynamic / formatted text)

The package includes a simple example script (Assets/Instant Localization/Example/Example.cs) that demonstrates how to:

  • Subscribe to LocalizationSystem.OnLanguageChanged,
  • Update a TextMeshProUGUI when the language changes,
  • Pass multiple arguments into a formatted localized string.

Example CSV (English.csv):

/* Example CSV (English.csv) */
key,text
example_complex,{0}, your character is level {1}. You have {2} skill points and your current quest is: {3}.

↑ Back to top

2.7. Auto-Translate window

The Auto-Translate Window is an editor tool that allows you to automatically generate translations for your localization files using external AI-powered translation providers. Access it via:

  • Menu: Navigate to Tools > Localization > Auto Translate (shortcut: Ctrl+Alt+A).

Basic Usage

  • Select the source language file.
  • Select the target language file.
  • Choose a translation provider.
  • Configure provider settings (API key, if required).
  • Generate translations.
  • Apply the results to update the target CSV file.

Behavior

  • Only localization values are translated — keys remain unchanged.
  • Existing translations can be preserved or overwritten depending on the selected options.
  • Changes are written directly to the CSV file.
  • Large datasets are processed in batches. Different translation providers impose limits on request size and rate. To ensure reliable operation, the system splits translation work into smaller batches.
  • Multiple keys are grouped into a single request when available
  • Helps avoid request size limits and rate limiting
  • Improves performance compared to translating each entry individually

Notes

  • Requires a valid API key for the selected provider.
  • Internet connection is required.
  • Generated translations may require manual review.
↑ Back to top

3. Script Reference

This section outlines the public methods and properties available for developers to interact with the localization system via code.

↑ Back to top

3.1. LocalizationSystem (Static Class)

The fe1zed.InstantLocalization.LocalizationSystem is the central API for managing the application's language state.

Member Type Description
public static string Language { get; private set; } Property Gets the language code of the currently loaded language (e.g., "English").
public static event Action OnLanguageChanged; Event An event fired whenever a new language is loaded. LocalizeText components subscribe to this event to update their text.
public static void SetLanguage(string languageCode) Method Loads the localization data for the specified languageCode (must match a CSV file name in Assets/Instant Localization/Resources/). Triggers OnLanguageChanged.
public static string GetLocalisedValue(string key) Method Manually retrieves the translation for a given key in the currently active language. Returns the key itself if the translation is missing.
public static void ReloadLanguage() Method Reloads the current language from the CSV file. Useful after manually editing CSV files.
public static int GetRequiredArgsCount(string localizedValue) Method Scans a localized string for numeric placeholders ({0}, {1}, …) and returns how many arguments are required. Used internally to validate calls to the formatted overload of GetLocalisedValue.
public static void UpdateTexts() Method Forces the OnLanguageChanged event to fire, which causes all subscribing components to refresh their text. Available via Tools > Localization > Update texts menu.
↑ Back to top

3.2. LocalizeText (Component)

The fe1zed.InstantLocalization.LocalizeText is a MonoBehaviour component intended to be attached to a TextMeshProUGUI component.

Member Type Description
public string localizedTextID; Field The key used to look up the text in the currently loaded CSV localization file. This is the main field edited via the Inspector.
Automatic Behavior Subscribes to LocalizationSystem.OnLanguageChanged in OnEnable() and automatically updates its text to the corresponding localized string. Works in both Editor and Runtime.
↑ Back to top

4. Editor Tools Menu Reference

The system provides convenient menu items under Tools > Localization:

Menu Item Shortcut Description
Open Localization Window Ctrl+Shift+T Opens the Localization Key Selector Window.
Update texts Forces all LocalizeText components to refresh their displayed text. Useful after editing CSV files manually.
Auto Translate Ctrl+Alt+A Opens the Auto-Translate Window.
Auto Translate Documentation Opens documentation web page.
↑ Back to top

5. Best Practices

Use the Editor Window:
Manage keys through the Localization Key Selector Window instead of manually editing CSV files. This ensures consistency across all language files and reduces the risk of missing or mismatched entries.

Use Favorites for Workflow Efficiency:
Mark frequently used keys (such as common UI labels and buttons) as favorites to speed up selection and reduce repetitive searching.

Adopt Consistent Naming Conventions:
Use clear, descriptive, and structured key names (for example, ui_button_start, menu_settings_title, dialog_greeting). Consistent naming improves maintainability as the project grows.

Test Language Switching Frequently:
Regularly switch languages during Play Mode to verify that all localized components update correctly and that no keys are missing.

Review Generated Translations:
If using the Auto-Translate feature, always review machine-generated translations for accuracy and context before release.

Back Up Localization Data:
Keep backups of your CSV files before performing bulk edits or automated operations to prevent accidental data loss.

Understand Editor vs Runtime Behavior:
Localization files are accessed differently in the Editor (direct file access) and at runtime (via Resources.Load). Always test localization in a built player, not only in Editor Play Mode.

Keep CSV Files Clean and Valid:
Ensure files use UTF-8 encoding and avoid duplicate keys, malformed rows, or unintended formatting changes from spreadsheet software.

↑ Back to top

6. Troubleshooting

Problem: Text doesn't update when switching languages
Solution: Ensure the LocalizeText component is properly attached and the key exists in all CSV files. Use Tools > Instant Localization > Update texts to force refresh.

Problem: CSV file not found error
Solution: Verify the CSV file is located in Assets/Instant Localization/Resources/ and the filename matches the language code being loaded.

Problem: Favorites not persisting
Solution: Check that Assets/Instant Localization/Data/InstantLocalizationFavorites.asset exists and is not corrupted. The asset is auto-created on first use.

Problem: Keys appear as "(missing)"
Solution: The key exists in one language file but not others. Use the Edit function in the Localization Key Selector Window to add translations for all languages.

Problem: Auto-Translate produces empty or incomplete results
Solution: Verify that a valid API key is configured, the selected provider is available, and your internet connection is active. Some providers may also impose request limits or quotas.

↑ Back to top

7. Technical Notes

  • Editor-Only Features: The Localization Key Selector Window, CSV Manager, and Favorites system are Editor-only and will not be included in builds. As well as Auto-Translate window and related scripts.
  • Performance: CSV files are loaded once when language is set. Runtime lookups use Dictionary for O(1) performance.
  • Thread Safety: The system is not thread-safe. Always call methods from the main Unity thread.
  • File Encoding: CSV files should be UTF-8 encoded to support special characters and non-Latin alphabets.

Developed by fe1zed


↑ Back to top