Localization Guide
Introduction
Localization in Highrise allows you to create multilingual experiences for your world. This guide will show you how to properly implement localization using the actual working examples from the codebase.
Accessing the Localization Editor
- Open the Localization Editor by navigating to the Highrise menu and selecting Studio > Localization Editor.
- The editor provides a user-friendly interface for managing all your localized strings.
Creating New Localization Strings
Using the Localization Editor
- In the Localization Editor, click the + button in the bottom-right corner to add a new string.
- Fill in the following fields:
- Key: A unique identifier for the string (e.g.,
welcomeUI_welcome_desc1
) - Text: The actual string content
- Placeholders: Use
{{$1}}
,{{$2}}
, etc. for dynamic values
- Key: A unique identifier for the string (e.g.,
The key must be unique and cannot contain spaces or special characters. Use consistent naming conventions (e.g.,
uiName_element_purpose
).
Manual String Creation
You can also add strings directly to the LocalizationStrings.hrstrings
file:
<?xml version="1.0" encoding="UTF-8"?>
<resources>
<string name="welcomeUI_welcome_desc1">Challenge other players! Sit at a table and join the prize pool to play!</string>
<string name="welcomeUI_welcome_desc2">Daub the numbers in time to win Free Daub Powerups! Place them Strategically to win!</string>
</resources>
Adding Languages
Supported Languages
Highrise supports the following languages and their corresponding codes:
- en: English
- de: German
- es: Spanish
- fr: French
- hi: Hindi
- it: Italian
- zh: Chinese (Simplified)
- ja: Japanese
- ko: Korean
- nl: Dutch
- ru: Russian
- ar: Arabic
- fa: Persian
- pt-BR: Portuguese (Brazilian)
- pt-PT: Portuguese (European)
- tr: Turkish
Adding a New Language
- Make a copy of
LocalizationStrings-en.stringtable
- Rename the file, replacing
en
with the language code (e.g.,de
for German) - Select the file in Unity and change the System Language in the Inspector to the corresponding language
- Open the file in a text editor and replace the text for each string with the translated version
If a player's Highrise app language doesn't have a corresponding file, the English version will be used as the default.
Localized UI Components
UILocalizedLabel
The most common component for displaying localized text:
<hr:UILocalizedLabel name="_desc1" key="welcomeUI_welcome_desc1" picking-mode="Ignore"/>
UILocalizedButton
For buttons with localized text:
<hr:UILocalizedButton name="_nextButton" key="welcomeUI_welcome_next_button">
<hr:UILocalizedLabel name="_nextButtonLabel" class="buttonLabel wrap"/>
</hr:UILocalizedButton>
UILocalizedTextField
For input fields with localized placeholder text:
<hr:UILocalizedTextField name="_inputField" key="welcomeUI_input_placeholder"/>
Implementing Localization in UI
UXML Implementation
The proper way to implement localized text in UXML is using the hr:UILocalizedLabel
element:
<hr:UILuaView class="welcome-popup">
<hr:UILocalizedLabel name="_desc1" key="welcomeUI_welcome_desc1"/>
<hr:UILocalizedLabel name="_desc2" key="welcomeUI_welcome_desc2"/>
</hr:UILuaView>
Key attributes:
name
: The identifier for the label in Luakey
: The localization key from the strings file
Lua Implementation
In Lua, you can set localized text in several ways:
- Using the
Strings
global withSetText
:
--!Bind
local _desc1 : UILocalizedLabel = nil
function self:ClientStart()
_desc1:SetText(Strings.welcomeUI_welcome_desc1)
end
- Using dynamic values with placeholders:
-- Example from ScoreHud.lua
game_state_label:SetText(Strings.scoreHud_waiting_players, playerTracker.GetReadyPlayerCount())
You don't need to use
SetText
forhr:UILocalizedLabel
elements in UXML. The localization system automatically binds the text when the UI is loaded unless you have dynamic values to set.
Best Practices
Naming Conventions
-
Use consistent prefixes for related strings:
welcomeUI_
for welcome screen stringsscoreHud_
for score HUD stringsleaderboardUI_
for leaderboard strings
-
Use descriptive suffixes:
_title
for titles_desc
for descriptions_button
for button text
Placeholder Usage
- Use
{{$1}}
format for placeholders:
<string name="scoreHud_waiting_players">Waiting for players: {{$1}} / 2</string>
- Pass values in order:
-- Correct
label:SetText(Strings.key_name, value1, value2)
-- Incorrect
label:SetText(Strings.key_name, value2, value1)
Common Patterns
Button Text
<hr:UIButton name="_nextButton">
<hr:UILocalizedLabel name="_nextButtonLabel" class="buttonLabel wrap" key="welcomeUI_welcome_next_button"/>
</hr:UIButton>
Dynamic State Updates
<string name="scoreHud_waiting_players">Waiting for players: {{$1}} / 2</string>
<string name="scoreHud_players_ready">Players ready: {{$1}} / 2</string>
function UpdateGameState(state)
if state == 1 then
game_state_label:SetText(Strings.scoreHud_waiting_players, playerCount)
elseif state == 2 then
game_state_label:SetText(Strings.scoreHud_players_ready, playerCount)
end
end
The
{{$1}}
placeholder must match the order of values passed in the Lua function. Ensure that the number of placeholders matches the number of values provided.
Testing and Maintenance
-
Always test with different languages to ensure:
- Text fits within UI elements
- Placeholders are correctly positioned
- Special characters display properly
-
Keep string files organized:
- Group related strings together
- Use consistent naming conventions
- Document any special formatting requirements
-
When adding new strings:
- Add to all language files
- Test placeholder functionality
- Verify UI layout with different text lengths
Conclusion
Proper localization implementation requires attention to detail in both the UI and code. By following these patterns and best practices, you can create a robust multilingual experience for your world. Remember to test thoroughly with different languages and text lengths to ensure a consistent user experience across all supported languages.
Updated 16 days ago