Localization

​

Features

• Introduced a dynamic language selector seamlessly integrated with Unity’s Localization system.
• Automatic Text Collection: Auto-add texts from Story nodes, Data fields, State Tables, UI Texts, etc., to the string table.
• Preview Runtime Changes: Allows switching languages during runtime in the Unity editor for real-time preview.

​

Setup

1. Navigate to Edit > Project Settings > Localization.
2. Under Available Locales, click “Add All” to include all pre-existing locales.
3. Remove unnecessary locales and add any missing ones you need for your project.

​

Room Config Data Setup

1. Open Room Manager Config:
   • Locate the RoomManagerConfig file in your project. This is where the main menu and experience data are stored.
2. Add Locales to Main Menu Languages:
   • Navigate to the Main Menu Languages section in the Room Manager Config.
   • Add the locales you want to make available for the Main Menu. These languages will determine how the Main Menu is displayed in different locales.
3. Configure Experience Data → Available Languages:Steps:
   • Navigate to the Experience Data section within the Room Manager Config.
   • Each experience can have its own set of available languages. These locales determine which languages are supported for that specific experience.
   • In the Available Languages field for each experience, add the locale codes you want to make available.
   • Use the same codes from the Available Locales list in Project Settings.

1. The Locale Toggles feature allows you to specify whether a locale requires the Legacy Text component instead of TMP text.
2. It also lets you configure text size limits for Legacy Text, ensuring proper font rendering.

1. Navigate to the Locale Toggles list in the RoomManagerConfig.
2. Locate the auto-populated list of locales (based on the Available Locales in Project Settings).
   • Each locale will already have its Locale Code populated (e.g., en, ja-JP, etc.).
3. For each locale, set the following manually:How to set Locale Toggles in Room Manager Config
   • Use Legacy Text: Set this to true if the locale should use Legacy Text instead of TMP text.
   • Min Text Size: Specify the minimum font size for Legacy Text.
   • Max Text Size: Specify the maximum font size for Legacy Text.

• To use Legacy Text for Kannada (kn), your toggle configuration would look like this: Locale Code:

kn (auto-populated)
Use Legacy Text: true
Min Text Size: 10
Max Text Size: 25

• During runtime, the LocalizationManagerCore:
  1. Checks if a locale has Use Legacy Text enabled.
  2. Automatically applies Legacy Text settings (like min/max size) to all relevant text components.

​

Scene Changes

1. Add the Localization Manager Prefab:
   1. If your scene does not already contain the Framework Systems prefab, you need to manually add the Localization Manager prefab to your scene.
   2. This prefab is responsible for managing all localization operations, including loading string tables, font tables, and runtime locale changes.

1. On the Localization Manager, click the “Initialize Table Names to Default Tables” button.
2. This action automatically sets up the following fields:
   1. String Table Name: Defines the table storing all localized text strings for the project.
   2. Font Table Name: Specifies the table containing font assets for different languages.
3. What is the Primary Locale?
   1. The Primary Locale is the default language used as a reference point for adding and validating entries in the string and font tables (e.g., "en" for English).
   2. It is specified in the Localization Manager as _primaryLocaleKey.
   3. Usage:
      1. When running the Setup Scene, text entries are added to the string table under the Primary Locale.
      2. During runtime, if a selected locale is missing or unavailable, the system falls back to the Primary Locale for displaying text.
   4. Why is the Primary Locale Important?
      1. It ensures all string table entries are consistently created and validated against the base language.
      2. The fallback mechanism guarantees that text is displayed even if translations for a specific locale are incomplete or missing.
4. Understand Tables in Localization:
   1. String Tables: These tables store all the localized text strings used in your project. They enable dynamic language switching for UI elements and in-game text.
   2. Asset Tables: These tables store localized assets such as images, fonts, and audio clips, allowing asset variations for different languages.
5. Font Asset ID Usage:
   1. The Font Asset ID determines which font from the Font Asset Table is applied to all TMP_Text components in the scene.
   2. It acts as a reference to the Table Entry Key in the Font Table, ensuring the correct font is applied based on the selected locale.
   3. Steps:
      1. Click Open Font Table in the Inspector to view the Font Asset Table.
      2. Check that the Regular table entry exists for each language, ensuring that appropriate fonts are configured for all supported locales.
6. Run the Setup Scene Process:
   1. Click the “Setup Scene” button on the Localization Manager. This action automatically configures text and assets for localization. It performs the following tasks:
      1. Finds all TMP_Text components in the scene, including inactive objects.
      2. Adds their text entries to the String Table, creating new entries if necessary.
      3. Attaches the LocalizeStringEvent component to each TMP_Text object to enable runtime localization.
      4. Configures the Font Replacer Component to ensure fonts are localized based on the selected locale.
      5. Processes additional localization for text from Story Nodes, State Tables, and Room Config Data.
7. Verify Translations in the String Table:
   1. Click the Open String Table button in the Inspector to view and verify all the text entries added during the Setup Scene process.
   2. Ensure all required strings are present and properly localized.

​

Translate the String Table

1. After you have clicked on Setup Scene button which will fetch all the texts from the scene & put them in the string table, open the string table editor.
2. On the top right corner you can see a button for Export → .csv
3. Copy all cells to Google Sheet where we will do the translation.
4. Apply formula to a cell for translation in the appropriate cell:
   1. =GOOGLETRANSLATE(A2, “en”, “hi”)
      • where A2- source cell with English string (”en”) being translated to Hindi (”hi”)
   2. Here is the link for all language codes required for Google Translate formula:
5. Once a cell has been translated by a formula, to replicate the result just click & drag the icon on the bottom right corner of a cell like this:

1. Translate the whole table like so & have it ready.
2. Paste the whole table to the excel sheet & then save the excel sheet as this format- CSV UTF-8 (Comma delimited)

1. Now import the new excel sheet to Unity string table by clicking on Import → CSV & select the Excel file.

1. A perfectly translated & imported String table should look something like this

​

Set a Font for Specific Text

1. Once the Setup Scene process is complete, you can customize fonts for specific texts in your scene by following these steps:
2. Add a New Font Key to the Font Asset Table:
   1. Open the Font Asset Table in Unity’s Localization system.
   2. Add a new entry with a unique Key (e.g., Custom_Font_01) and assign the desired font asset to all the cells in the row.
3. Refer to the New Font Key in the Font Behaviour Component:
   1. Select the Text GameObject in the scene where you want to apply the new font.
   2. Locate or add the LocalizedTMPFontBehaviour component.
   3. Set the Table Entry Reference to the new key you added in the Font Asset Table.
4. Verify the Font Change: Ensure the correct font appears when switching locales or running the scene.

​

Verify all Translated Text

1. Select a Preview Locale:
   • Use the Preview Locale Dropdown in the Inspector to choose the language you want to test.
   • The dropdown is automatically populated with locale codes from Project Settings > Localization > Available Locales.
2. Choose a Preview Font Asset:

1. Use the Preview Font Asset ID Dropdown in the Inspector to select the font asset for testing.
2. The dropdown is populated with font asset keys from the Font Asset Table configured in the Localization Manager.
3. Open the Preview Window:
   • Select the LocalizationManager in your scene.
   • In the Inspector, click Show Preview Window.
4. Verify Translated Text:
   • The Preview Window displays all the localized text entries from the selected String Table for the chosen locale.
   • Ensure all text renders correctly, with proper alignment and formatting.
5. Check Font Compatibility:

• The Preview Window applies the selected Font Asset ID to the text.
• If any characters are unsupported, they may appear as empty boxes or incorrect glyphs. Update the Font Asset Table with a compatible font if needed.

1. Switch Between Locales and Fonts:
   • Test different combinations of locales and font asset IDs to ensure compatibility across languages.
2. Close the Preview Window:
   • After testing, click Hide Preview Window in the Inspector to close it.

​

Best Practices

• Always Rebuild Addressables:
  • After adding or modifying locales, ensure Addressable are rebuilt: Window > Asset Management > Addressables > Groups > Build > New Build.
  • This guarantees updated localization tables are included.
• Test Fonts for All Locales:
  • Ensure that fonts in the Font Asset Table support all required characters for your target languages. Missing characters may cause rendering issues.
• Maintain Consistent Table References:
  • Ensure that keys in the String Table and Font Asset Table follow a consistent naming convention to avoid mismatches.

​

Known Issues

1. Auto Size Requirement for Certain Languages:
   1. Languages like Kannada may require Auto Size to be enabled for certain TMP_Text components after applying the font asset and text.
   2. Solution: Perform a dry run in the Unity Editor for each locale to check text scaling and formatting before creating a build.
2. UI Text Instantiated at Runtime:

  TMP_Text myText = Instantiate(textPrefab).GetComponent<TMP_Text>();
  LocalizationManager.Instance.SetupForRuntimeTMPText(myText);

1. Any TMP_Text UI element instantiated by scripts will not automatically support translation.
2. Solution: Call the LocalizationManager function SetupForRuntimeTMPText(_objectNameText) in your script to configure the text for runtime localization. Example:

​

FAQs

• 1. How do I add a new language?
  1. Add the language to the Available Locales list in Unity’s Localization settings.
  2. Rebuild Addressables: Window > Asset Management > Addressables > Groups > Build > New Build.
  3. The new language will automatically appear in the language selector and other dropdowns.

• 2. What happens if the selected language isn’t in Available Locales?
  1. The system logs a warning.
  2. It falls back to the first available locale in the list.

• 3. How do I make sure my fonts support all characters in a language?
  1. Check the Font Asset Table to ensure the font supports the necessary characters.
  2. Use the Preview Window in the Localization Manager to test text in different locales.
  3. Identify and replace unsupported fonts or characters.

• 4. Do I need to manually add each text entry to the string table?
  1. No. Use the Setup Scene button in the Localization Manager to add all TMP_Text components’ text automatically.
  2. For runtime-instantiated texts, call the SetupForRuntimeTMPText() function in your script.

• 5. Can I use the same font for all languages?
  1. Yes, but ensure the font supports all required characters for every language.
  2. Add language-specific fonts to the Font Asset Table for better results.
  3. Assign the correct Font Asset ID for each locale.

• 6. Why is some text not appearing translated in the game?
  1. Verify that the text exists in the String Table for the selected language.
  2. Check if the TMP_Text component has a LocalizeStringEvent attached.
  3. Rebuild Addressables to reflect all changes.

• 7. How do I test translations in the editor?
  1. Use the Preview Window in the Localization Manager.
  2. Select the Preview Locale and Font Asset ID from the dropdowns.
  3. Check the text rendering for all supported languages.

• 8. Do I need to rebuild Addressables every time I make a change?
  1. Yes, if you’ve added new locales, updated string tables, or modified font tables.
  2. Rebuilding ensures all changes are reflected in the build.

• 9. How do I translate non-text assets like images or audio?
  1. Add these assets to an Asset Table in the Localization system.
  2. Use the Localize Asset Event component on the GameObject.
  3. Reference the Asset Table in the component.

• 10. What should I do if the font or text looks wrong in some languages?
  1. Check the Auto Size setting for TMP_Text components.
     • Some languages, like Kannada, may require it to be enabled.
  2. Perform a dry run in the Unity Editor for each locale to ensure proper formatting and appearance.

• 11. Can I dynamically switch languages in runtime?

   LocalizationSettings.SelectedLocale = LocalizationSettings.AvailableLocales.GetLocale("fr");

1. Replace "fr" with the desired locale code.
2. Yes. Use the following code to change the current locale:

• 12. What happens if I forget to add a translated text for a new language?
  1. The text will fall back to the primary locale font.
  2. If the default font doesn’t support certain characters, they will appear as boxes or garbled text.
  3. Always test each language in the editor to avoid this issue.

• 13. Can I use Google Translate to translate my texts?
  1. Export the String Table as a CSV.
  2. Use Google Sheets to apply translation formulas.
  3. Import the translated CSV back into Unity.
     • Refer to the How to Easily Translate String Table section for detailed steps.