# Localization

## Overview

Localization is a feature designed to provide a consistent experience for players using different languages.

It allows you to translate and display not only out-of-game texts such as **world names and descriptions**, but also **in-game texts** including UI, interaction messages, and system prompts.

By leveraging this feature, you can deliver a more natural experience to players from various countries, improve world accessibility, **increase user acquisition**, and **maximize revenue**.

## Features

This system provides the following features:

* Automatically collects text displayed in UI and ProximityPrompt and registers it in the Creator Hub
* Translation data is centrally managed in the Creator Hub
* Automatically applies translations based on the player's language settings using the registered translation data
* Supports translation of dynamic text via scripts

## Supported Languages

Currently, OVERDARE supports **English, Hindi, and Portuguese (Brazil)**.

Similar languages are automatically mapped to supported languages. For example, British English is mapped to English, and European Portuguese is mapped to Brazilian Portuguese.

Unsupported languages may be displayed in the original text.

| Language            | Language Code | Similar Language Variants |
| ------------------- | ------------- | ------------------------- |
| English             | `en`          | `en-us`, `en-gb`, etc.    |
| Hindi               | `hi`          | `hi-in`, etc.             |
| Portuguese (Brazil) | `pt-br`       | `pt`, `pt-pt`, etc.       |

If translation text is not provided for a language, the content may be displayed in the default language (source text). To ensure proper world activation and a consistent user experience, **it is recommended to provide translations for all supported languages**.

## How to Use

1. The Localization feature is **available after publishing** your world.\
   (If your world has not been published, you must publish it first.)

   <figure><img src="/files/h2GquEsJeerpchGepWUM" alt=""><figcaption></figcaption></figure>
2. In Studio, go to **Game Settings > Localization** and enable **Automatic Text Collection (ATC)** and **Use Translated Content**.\
   (Clicking the Edit in Hub button will take you to the Localization management page in the Creator Hub.)

   <figure><img src="/files/EUPoYmVlO7oEuAyryQD3" alt=""><figcaption></figcaption></figure>
3. Run a **play test**.
4. During the test, when text appears in UI or ProximityPrompt, it is **automatically registered for collection**.\
   (The collection process is handled internally, and there is a limit to the number of texts that can be collected in a single play test. If this limit is exceeded, additional texts will not be collected and a warning log will be generated.)
5. **When the play test ends**, the collected texts are **automatically adde**d to the translation table in the Creator Hub, and translation entries are created for all supported languages.

   <figure><img src="/files/2PYgB8zEdHlSkXeUti9w" alt=""><figcaption></figcaption></figure>
6. You can review the registered texts in the Creator Hub and **enter/manage translations for each language**.\
   (Be sure to click the **Save button** after entering translations.)

   <figure><img src="/files/50kM5JeEEq5rvYmiKnFl" alt=""><figcaption></figcaption></figure>
7. Low-frequency or conditional texts that are difficult to collect via ATC can be manually added via CSV in the **Table Management tab** of the Creator Hub.

   <figure><img src="/files/Rtx9iS3GZyZP2bewArqJ" alt=""><figcaption></figcaption></figure>
8. World metadata such as the world name and description is provided by default.

   <figure><img src="/files/7Y2nBoV4gKzOO5IetecN" alt=""><figcaption></figcaption></figure>

## Translation Testing

You can preview translations by selecting a language in **Localization Preview**, and you can also change the language during gameplay.

<figure><img src="/files/5klibLff78N9Bs0HPe1k" alt=""><figcaption></figcaption></figure>

## 상세

### Automatic Text Collection (ATC)

During play tests in the Studio environment, when text is displayed in UI or ProximityPrompt, it is automatically collected. The collected text is then registered in the Creator Hub’s translation table **when the play session ends**.

#### Collection Targets

* Text properties of TextLabel and TextButton (Text)
* Interaction text properties of ProximityPrompt (ActionText, ObjectText)

#### Collection Conditions

Text is collected only when the following conditions are met:

* **Automatic Text Collection (ATC) is enabled**
* **The environment is a Studio play test** (not supported in mobile environments)
* The **AutoLocalize property is enabled** for UI or ProximityPrompt
  * For UI, AutoLocalize must be enabled on both parent and child UI elements

#### How It Works

* Text displayed on the screen is collected **in real time during gameplay**
  * In the Hub, the Location field records the path where the text was collected\
    (e.g., StarterGui.ScreenGui.TextButton)
* **Text dynamically assigned** via scripts is also included in the collection
* Text that is already registered in the Hub will not be duplicated
* Collected text is sent to the Hub **when the play session ends**

#### Collection Limits

* There is a limit to the number of texts that can be collected in a single play test
* If the limit is exceeded, additional texts will not be collected and a **warning log** will be generated
* If excessive text generation occurs (e.g., repeatedly assigning text in a loop), review the structure and rerun the play test
* **For texts that should not be collected, make sure to disable the AutoLocalize property**

### Applying Translated Text

During a play test, when text is displayed in UI or ProximityPrompt, if that text is registered in the Creator Hub and a translated version exists, the translation is automatically applied.

#### Translation Targets

* Text in TextLabel and TextButton
* Interaction text in ProximityPrompt

#### Conditions for Applying Translation

* **Use Translated Content is enabled**
* The translation is applied when **running a play test in Studio** or when the **world is accessed from a mobile environment**
* The **AutoLocalize option is enabled** for UI or ProximityPrompt
  * For UI, translation is applied only when AutoLocalize is enabled on both parent and child UI elements

#### When Changes Are Applied

* Changes to translation data are applied after **restarting the play test** or **rejoining the world**
* In mobile environments, changes may not appear immediately and can take up to **about 5 minutes to be reflected**

#### Context-Based Translation Rules

Translations are applied based on the **Context value** and the **location** of the UI or ProximityPrompt, as follows:\
(This rule also applies when using the Translate method.)

For example, if the following entries are registered in the Hub:

<table><thead><tr><th width="107.666748046875">Source</th><th width="117.3333740234375">Translated Text</th><th width="387.9998779296875">Context</th><th>Notes</th></tr></thead><tbody><tr><td>강화</td><td>Enhance</td><td></td><td>Default translation</td></tr><tr><td>강화</td><td>Item Enhance</td><td>PlayerGui.ScreenGui.ItemPopup.EnhanceButton</td><td>UI-specific</td></tr><tr><td>강화</td><td>Enhance Monster</td><td>ServerStorage.Monster.NameTag.GradeLabel</td><td></td></tr></tbody></table>

* If the **Context matches**, the corresponding translation is applied
  * For example, if the path of the UI or ProximityPrompt is PlayerGui.ScreenGui.ItemPopup.EnhanceButton,\
    → **Item Enhance** is applied
* If the **Context does not match**, the translation with only the Source (default translation) is applied
  * If the UI or ProximityPrompt path does not match any Context above,\
    → The default translation **("강화")** is applied
* If there is **no default translation**, a Context-based translation may be applied instead
  * For example, if there is no default translation for “강화” but only Context-based translations exist,\
    → **Item Enhance** or **Enhance Monster** may be applied

## Managing Translation Data

### Localization Page

In Studio, go to Game Settings > Localization and click the **Edit in Hub button** to navigate to the Localization management page in the Creator Hub.

<figure><img src="/files/NdPd4sFDFUzoaz48uiPL" alt=""><figcaption></figcaption></figure>

Alternatively, you can access it from the **Localization tab** by selecting your world in the Dashboard of the Creator Hub.

<figure><img src="/files/M2xMi8vH8qsSOkGd5jf6" alt=""><figcaption></figcaption></figure>

### Managing Translation Text

In the **Languages tab**, selecting a language will take you to a page where you can manage translations for both **world information** and **in-game text** for that language.

Alternatively, you can navigate to the **Translation Workspace tab**.

<figure><img src="/files/eBWa3zLjGxHFxZ6tgHbs" alt=""><figcaption></figcaption></figure>

#### Managing World Information

In the **Information tab**, you can enter translated text for the **World Name** and **Description** for each supported language. All changes are recorded in the Translation History.

<figure><img src="/files/eohiOTk37eTO99zg2pKk" alt=""><figcaption></figcaption></figure>

#### Managing In-Game Text

In the **Strings tab**, you can enter translated text for in-game data for each supported language.\
All changes are recorded in the Translation History.

By selecting an entry, you can edit or delete the registered translation data.

<figure><img src="/files/iZ8Opgp6yr5tU8HWciFU" alt=""><figcaption></figcaption></figure>

By default, texts collected during play tests via ATC are automatically registered. You can also manually add entries using the **Add Entry button**.

<figure><img src="/files/mNBjpCfGCyPBplUMSAQg" alt=""><figcaption></figcaption></figure>

When adding entries manually, the input fields are structured as follows. After entering the required information, click the **Add button** to register the translation entry.

Texts with the same source can only be registered multiple times if their **Context** values are different.

<table><thead><tr><th width="167">Name</th><th width="364.6666259765625">Description</th><th>Example</th></tr></thead><tbody><tr><td>Text to translate</td><td>Source text used as the basis for translation</td><td>Level</td></tr><tr><td>Key</td><td>Unique identifier for the translation entry (optional)</td><td>UI_Text_Level</td></tr><tr><td>Context</td><td>UI location where the text is used (optional)</td><td>PlayerGui.PlayerHUD.TopFrame.Lv</td></tr><tr><td>Example</td><td>Additional description for translation reference (optional)</td><td>Text displayed for player level UI</td></tr></tbody></table>

### Managing Settings

In the **Settings tab**, you can enable or disable options for Automatic Text Collection and Use Translated Content.

These settings are synchronized with Studio, and any changes made in Studio are also reflected in the Hub.

<figure><img src="/files/olgRaa9oP45afL4QcK8n" alt=""><figcaption></figcaption></figure>

### Table Management

In the **Table Management** **tab**, you can download translation data as a CSV file or upload a CSV file to modify it.

For low-frequency UI or conditional UI, it may be difficult to collect text using ATC alone. In such cases, it is recommended to define the required data in advance in a CSV file and upload it, rather than relying solely on ATC.

<figure><img src="/files/muoFx9YqK3zu3w76TU5V" alt=""><figcaption></figcaption></figure>

* **Upload CSV**: Upload a CSV file to add or modify in-game text and translation data. Only changes based on existing data are applied.
* **Download CSV**: Download the current translation table as a CSV file. You can review the translation status or modify the file and upload it again.
* **Delete Table**: Deletes all in-game data registered in the translation table. This action cannot be undone, so use it with caution.

## Script Features

### Checking Locale Information

You can use LocalizationService to retrieve language-related information for both the player and the system.

This allows you to handle logic differently based on the player’s language settings or region.

```lua
local LocalizationService = game:GetService("LocalizationService")

local PlayerLocaleId = Player.LocaleId -- Language set in the player’s account
local ClientLocaleId = LocalizationService.ClientLocaleId -- Language currently used by the client
local SystemLocaleId = LocalizationService.SystemLocaleId -- OS language of the player’s device
local CountryRegion = LocalizationService:GetCountryRegionForPlayerAsync(Player) -- Player’s region (country code) based on their connection location
```

ClientLocaleId and SystemLocaleId return the locale of the execution environment. While they reflect the player's locale on the client, they return the server's locale when used on the server.

Therefore, they are not recommended for use on the server when player-specific locale handling is required.

### Getting a Translator

A Translator is an object used to perform translations based on a specific language. It is used to retrieve translated text.

```lua
-- You can obtain a Translator based on the player’s language settings
local Translator1 = LocalizationService:GetTranslatorForPlayerAsync(Player)
print(Translator1.LocaleId)

-- You can also obtain a Translator for a specific locale using a language code
local Translator2 = LocalizationService:GetTranslatorForLocaleAsync("en")
print(Translator2.LocaleId)
```

### Handling Translation via Script

When text varies depending on variables (such as item names or levels), or when the same source text requires different translations depending on context, you can handle translation through scripts.

#### Key-Based Translation (FormatByKey)

FormatByKey retrieves translated text based on a Key. Values that need to be substituted within the sentence (such as item name, level, etc.) are passed through Args.

This method is suitable for handling text where the sentence structure changes depending on context, such as item names, levels, or quantities.

<pre class="language-lua"><code class="lang-lua"><strong>local Translator = LocalizationService:GetTranslatorForPlayerAsync(Player)
</strong>
local Key = "ITEM_LEVEL_UP" -- The Key is used to look up translation data
local Args = { ItemName = "Sword", PrevLv = 1, NextLv = 2 } -- Args contains values to be substituted into the translated sentence
local TranslatedText = Translator:FormatByKey(Key, Args)

SomeUI.Text = TranslatedText
</code></pre>

The names and number of values passed in Args must exactly match those defined in the translation data in the Hub.

<figure><img src="/files/uzhJttOINfQHPCz9xgJ4" alt=""><figcaption></figcaption></figure>

The following data types can be passed to Args.

* number
* string
* bool
* instance (name)
* CFrame
* Vector3
* Vector2
* Color3
* BrickColor
* MenuItem

#### Context-Based Translation (Translate)

```lua
local Translator = LocalizationService:GetTranslatorForPlayerAsync(Player)

local Context = PlayerGui.ScreenGui.ItemPopup.EnhanceButton -- Path where the text is used (Context)
local Source = "강화" -- Source text used as the basis for translation
local TranslatedText = Translator:Translate(Context, Source)

SomeUI.Text = TranslatedText
```

In general, the source text used as the basis for translation must be unique. However, if the Context differs, multiple entries can be registered as separate translation data.

This allows the same source text “강화” to be translated differently depending on the situation, such as item enhancement (Enhance), skill enhancement (Upgrade), or enchanted enemies (Enchanted), with Context used to distinguish between them.

<figure><img src="/files/AN9AWC6kS4NNLfC1ToTr" alt=""><figcaption></figcaption></figure>

### Retrieving Translated Text with LocalizedText

LocalizedText is a property that returns the translated text based on the current language.

It can be used to verify the actual translated text displayed in the UI.\
(It is not available for ProximityPrompt.)

```lua
print(SomeUI.LocalizedText .. "(Source: " .. SomeUI.Text .. ")")
```

## Use Cases

* Providing world names and descriptions in multiple languages helps effectively expose your world to global users and increase user acquisition.
* Providing UI, buttons, and guidance messages in the player’s language improves game understanding and reduces churn.
* Even in multilingual environments where sentence structures differ, using FormatByKey allows you to construct natural sentences for each language.
* Applying context-based translations (Context) to identical text enables more natural expressions and improves user experience.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.overdare.com/manual/studio-manual/game-development/localization.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.