Localisation

Localization V2 is the current VRseBuilder workflow for translating story voiceovers, UI text, and localized VO audio from inside Unity. Use it for new projects and for existing projects that are moving away from the previous localization workflow.

Open the setup window from:

VRseBuilder > LocalizationV2 > Setup Window

The window guides you through locales, string tables, story extraction, scene text extraction, translation, VO audio generation, status checks, and Addressables debugging.

tip

For the fastest setup, work through the tabs from left to right. Start with locales and tables, extract strings, translate them, generate VO audio, then use Status and Debug to fix anything Unity reports.

Quick Path

1. Choose locales

   Select the target languages, keep the source locale set to en unless your story was authored in another language, then sync the selected languages to RoomManagerConfig.

2. Create tables

   Set the VO, UI, and VO Asset table names, then click Ensure String Tables.

3. Extract story text

   Use the Story tab to extract voiceover lines and story UI strings from the active StoryCreator.

4. Extract scene UI text

   Optionally scan scene UI text under QueryObjects, select the entries you want, then run Extract & Setup.

5. Translate tables

   Translate the VO table first, then translate the UI table for the selected target locales.

6. Generate VO audio

   Generate TTS clips for translated VO entries and link them to the VO Asset table.

7. Check status

   Use Status to confirm every selected locale is complete. Use Debug to analyze and fix Addressables when runtime loading fails.

What Localization V2 Handles

Localization V2 covers three connected pieces of a VRseBuilder module:

Area	What it manages
Voiceover strings	Story Graph narration text extracted from the active StoryCreator into the VO string table.
UI strings	Story UI strings and selected scene UI text extracted into the UI string table.
VO audio	Generated TTS audio clips linked through the VO Asset table so runtime playback can load localized audio.

The setup window assumes Unity Localization package tables and Addressables are part of the project. The Status and Debug sections help keep those assets ready for runtime loading.

Supported and Default Localized Prefabs

Use the UniText prefab variants when your module needs reliable font rendering across the supported languages. These prefabs are supported or localized by default:

Use case	Prefabs
Checklists	ChecklistUI.prefab, ChecklistUI_UniText_Variant.prefab, Checklist-VRseUI.prefab, Checklist-VRseUI UniText.prefab
MCQ panels	MCQ EVALUATION PANEL_NEW.prefab, MCQ EVALUATION PANEL_NEW_UniText_Variant.prefab, MCQ Panel-VRseUI.prefab, MCQ Panel-VRseUI UniText.prefab
Experience panels	EXPERIENCE PANEL_NEW.prefab, EXPERIENCE PANEL_NEW_UniText.prefab, EXPERIENCE PANEL-VRseUI.prefab, EXPERIENCE PANEL-VRseUI UniText.prefab
Text panels	TextPanel.prefab, TextPanelMetaXR.prefab, TextPanel UniText.prefab, TextPanelMetaXR_UniText.prefab
Story navigation	StoryNavigationController.prefab, StoryNavigationController UniText.prefab

The following items are not part of the default localized prefab set yet:

• Metalayer Action Label
• Evaluation Panel
• Toast Message

Supported and Tested Languages

Localization V2 has been tested with these languages:

Language	Notes
English	Common source locale, usually en.
Hindi	Supported target locale.
Tamil	Supported target locale.
Marathi	Supported target locale.
Telugu	Supported target locale.
Kannada	Supported target locale.
Odisha	Supported target locale as listed in the source setup guide.
Malayalam	Supported target locale.
Bangla	Supported target locale.
Gujarati	Supported target locale.
Punjabi	Supported target locale.

note

Locales must exist in Unity Localization Settings before the setup window can use them. Add missing locales there first, then return to Localization V2.

Testing Localization

Localization V2 doesn't use the previous editor-only testing toggle. Test localized content through Play Mode or through the runtime locale switcher.

Editor Game View

1. Enter Play Mode.
2. Use the language dropdown in the top-right of the Game View.
3. Change the active language.
4. Confirm text and VO both change to the selected language.

If a VO clip is playing when the locale changes, LocalizedVO controls what happens next:

Setting	Behavior
Restart On Locale Change enabled	Stops the current VO and restarts it in the selected language.
Restart On Locale Change disabled	Keeps the current playback behavior and uses the new language from the next VO.

Runtime Locale Switcher

Place the LocaleSwitcher prefab in the scene when you need in-headset testing. During runtime, press X on the right controller to change locale.

Language Selection Panel

The language selection panel is enabled by default. To show it when the application starts, enable Enable Language Selection in the relevant runtime configuration.

Use this panel when learners should choose their language before the training starts. If your module should always start in a fixed language, keep the panel hidden and set the starting locale through project or runtime config instead.

Setup Window Tabs

The setup window is organized as workflow tabs and diagnostic sections. Most projects should start with Locales and move toward Status. Use Debug when Status shows Addressables or runtime loading problems.

Tab or section	Use it when	Main result
Status	You need to validate localization readiness.	Completeness ratios, missing keys, Addressables status, and fix actions.
Locales	You are setting up a module or changing supported languages.	Selected target locales, source locale, and runtime config sync.
Tables	Locales are selected and tables need to exist.	VO, UI, and VO Asset tables are created or configured.
Story	Story Graph content changes.	VO and UI strings are extracted from StoryCreator.
Scene	Scene UI text changes.	Selected TMP_Text and UniText entries get extracted and configured.
Translate	Source entries exist and target translations are needed.	Empty target-locale entries are filled through VRseTranslatorAPI.
VO Audio	VO translations exist and localized clips are needed.	TTS clips are generated and linked in the VO Asset table.
Debug	Addressables or runtime localized asset loading needs investigation.	Analyze, fix, and rebuild tools for localized assets.

Detailed Setup Checklist

Locales

Use Locales to choose supported languages and define the source-of-truth language for authored content.

• Select target locales with the locale toggles.
• Use Select All or Deselect All when configuring many locales.
• Use Add Locale if a needed locale is missing from Unity Localization Settings.
• Keep Source Locale Code as en unless the module was authored in another language.
• Click Sync to RoomManagerConfig so runtime language config matches the selected locales.

warning

Run Sync to RoomManagerConfig from a module scene. It relies on scene-based config location and doesn't work from Menu or unrelated scenes.

Tables

Use Tables to create or configure the three table collections Localization V2 expects.

Table	Purpose
VO Table	Stores voiceover script text by key and locale.
UI Table	Stores labels, buttons, instructions, and other localizable UI text.
VO Asset Table	Stores generated localized audio clip references.

Check Scene Status for LocalizationV2Bootstrap. A bootstrap is optional, but recommended because it stores scene-specific localization configuration. Confirm the table names, click Ensure String Tables, then use Open to inspect collections and locale columns.

Story

Use Story after tables exist and whenever Story Graph text changes.

• Confirm the active scene has a StoryCreator component.
• Click Extract VO Strings from Story to write narration lines into the VO table.
• Click Extract UI Strings from Story to write story UI text into the UI table.
• Review the Extraction Report before translating.

The source locale determines where extracted text is written.

Scene

Use Scene for UI text that lives directly in the scene rather than in the Story Graph.

The scan looks for TMP_Text and UniText under QueryObjects. It skips known system or default UI parents, including:

• Vrse System
• Default Query Objects
• MCQ EVALUATION PANEL_NEW
• MCQ EVALUATION PANEL_NEW_UniText_Variant
• ChecklistUI

Click Scan Scene, select the text entries you want to localize, then click Extract & Setup. The setup step adds or configures LocalizedText so the scene text can update with the active locale.

Translate

Use Translate after story or scene extraction has created source entries.

• Choose the target locales mask.
• Click Translate VO Table for narration text.
• Click Translate UI Table for UI text.
• Use Open Translation Window when you need to inspect or edit table entries manually.

Localization V2 only translates empty target-locale entries. Existing translations are kept. Watch the async status in the window before moving on to VO audio.

VO Audio

Use VO Audio after the VO string table has translated text for the target locales.

• Choose the target locales mask.
• Click Generate VO Audio to create TTS clips from translated VO entries.
• Click Link Audio to Asset Table to connect clips to the VO Asset table.
• Use Generate & Link for the normal combined flow.
• Use Cleanup Unused VO Assets after deleting or changing VO keys.

Generated audio is written to an output folder based on the scene path. Linking expects the bootstrap-configured VO Asset table. Cleanup only deletes VO assets that are no longer referenced by the VO Asset table.

Status

Use Status before handing off a localized module.

Status validates the VO string table, UI string table, and VO Asset table. It shows per-locale completion ratios, missing counts, and Addressables state.

Color	Meaning
Green	100 percent complete.
Yellow	50 to 99 percent complete.
Red	0 to 49 percent complete.

Click Refresh Status after any extraction, translation, or VO generation step. Use the missing-key foldouts to inspect gaps. If Addressables entries are missing or stale, use the fix action shown in Status.

Debug

Use Debug for Addressables and runtime loading problems.

• Analyze checks Unity Addressables rules for localized assets.
• Fix All or Fix resolves common localization Addressables configuration problems.
• Build Addressable Content rebuilds content that runtime localized asset or audio loading depends on.
• Advanced Addressables Analyze opens Unity's native diagnostics for deeper inspection.

Migration from the Old Localization Flow

Projects on 0.6.5 or earlier may still contain components from the old localization workflow. Remove those before using Localization V2.

1. Undo the old localization setup

   Open the old Localization window and click Undo Localization to remove old localization components.

2. Replace TMP text with UniText where needed

   Go to VRseBuilder > Tools > Replace TextMeshPro with UniText.

3. Assign the font stack

   Assign the font stack that covers your target languages, then scan the scene.

4. Replace selected text components

   Select the TMP entries to replace and click Replace Checked with UniText.

5. Update custom scripts

   Change scripts that set TMP text directly so they call LocalizedText.SetText() instead.

Custom text keys still need matching entries in the string table. For programmatic patterns, inspect the SDK source examples in TextStoryExtractor.cs and StringTableWriterV2.cs.

Troubleshooting

LocalizationV2Bootstrap not found in scene

The Tables tab can still auto-generate table names from the scene path, but a LocalizationV2Bootstrap is recommended for scene-specific configuration. Add or configure the bootstrap when a module needs stable table references.

Missing tables or locale columns

Selected locales don't have table entries yet. Use Ensure String Tables from the Tables tab, then open the table collections to confirm every selected locale exists.

Addressable warnings

Localized assets need valid Addressables entries for runtime loading. Use the Status fix action first. If warnings remain, use Debug to Analyze, Fix All, and Build Addressable Content.

VO audio generation fails

Confirm the VO string table has translated text for the target locales. Also check that the same locales are selected in the VO Audio tab before generating clips.

VO doesn't play in the selected language

Confirm LocalizedVO is attached to VOPlayer. Then check that VO clips exist, the VO Asset table is linked, and the audio assets are Addressable. Use Status and Debug to fix missing entries or rebuild Addressables content.

Version-Control Notes

Commit localization and Addressables configuration with the module. At minimum, review changes under:

• AddressableAssetsData
• EditorBuildSettings.asset
• ProjectSettings.asset

If VO clips are generated into project assets, commit those assets and their .meta files too. Don't commit editor-only service assets that store personal tokens, such as the Excel Online service asset described below.

Excel Online Synchronization

warning

Excel Online synchronization is experimental. Use it when a team needs spreadsheet review, but keep Unity string tables as the source you verify before build handoff.

The Excel Online extension can sync Unity String Table Collections with Excel spreadsheets stored on OneDrive. It supports pushing Unity keys and locale values to Excel, then pulling reviewed values back into Unity.

Setup

1. In Unity, find Assets/VRseBuilder/Core/Editor/LocalizationV2/ExcelOnlineExtension/Excel Online Service.asset.
2. Open the asset in the Inspector.
3. Authorize the Microsoft login.
4. Confirm tokens are stored automatically.
5. Open the Unity Localization window.
6. Select a String Table Collection.
7. Add the Excel Online Extension and assign the service asset.

danger

Don't commit Excel Online Service.asset. It stores authentication tokens.

Column Mapping

Map the Excel key column and each Excel locale column to the Unity table collection. Auto mapping places keys in column A and creates locale columns for the project locales.

Push and Pull

Action	Behavior
Push	Writes the header row and localization rows from Unity to Excel.
Pull	Reads the header row, first column as keys, and locale columns as values.
Remove Missing Pulled Keys	Deletes Unity keys that are absent from Excel when enabled.

Key resolution tracks both key names and IDs in the note field, which helps with renames and duplicate handling. Worksheet names are capped at 31 characters, and invalid characters such as :, \\, /, ?, [, and ] are replaced with _.

Excel Sync Troubleshooting

Problem	What to check
Not authenticated	Reopen the service asset and authorize Microsoft login again.
Failed sharing URL	Confirm the spreadsheet is stored on OneDrive and the account has access.
Missing key column	Check the key column mapping before pulling.
Pull shows no data	Wait for Excel or OneDrive sync, then close and reopen the Unity table collection if values still don't appear.