# LocalizationService

LocalizationService : `Instance`

## Overview

LocalizationService is a service object that provides automatic translation (Auto Translation) and client locale/region information for the game.

Only one instance exists per world. It is a non-creatable service type and can only be accessed through `game:GetService("LocalizationService")`.

Based on translation tables registered in the cloud, it asynchronously provides Translator objects corresponding to specific locales, and also offers a feature for retrieving a player's country/region code.

Unsupported language codes fall back to English (`en`). Prefix-based similarity matching is applied for English-family (`en-us`, `en-gb` → `en`), Portuguese-family (`pt-br`, `pt-pt` → `pt-br`), and Hindi-family (`hi-in` → `hi`) locales. However, locale values directly exposed by the client (ClientLocaleId, Player.LocaleId) return the original device/Studio setting as-is; the fallback applies only to a Translator's LocaleId.

## Properties

### ClientLocaleId

`string`

A read-only property that returns the client locale ID used for localization, formatted like `en-us`.

* In mobile environments, the display language of the OVERDARE Player app is returned.
* In Studio environments, the language set in Studio Setting > Language is returned. If unset, the default is `en-us`, and when using the emulator the language specified there is returned.

This value is recommended for client-side use only, as invalid values may be returned on the server.

In addition, on the same client, `LocalizationService.ClientLocaleId` and `Translator.LocaleId` have the same value, namely the language set in Studio/the app.

#### Code Samples

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

print(LocalizationService.ClientLocaleId)
```

### SystemLocaleId

`string`

A read-only property that returns the locale ID set in the local player's operating system (OS), formatted like `en-us`.

While ClientLocaleId reflects the language set in the app/Studio, SystemLocaleId reflects the device OS language setting. Therefore, the two values may differ.

This value is recommended for client-side use only, as invalid values may be returned on the server.

#### Code Samples

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

print(LocalizationService.SystemLocaleId)
```

## Methods

### GetCountryRegionForPlayerAsync

Returns a country/region code string based on the geographic location of the player's client IP.

If a cached value exists on the server, it is returned immediately; otherwise, the calling script yields until the external API response arrives.

The returned value is an uppercase country code such as `KR`, `BR`, or `IN`, and an empty string may be returned on failure.

Because this method is asynchronous, it must be called from a script (coroutine) context.

#### Parameters

| `Instance` Player | The target player whose country/region information will be retrieved. |
| ----------------- | --------------------------------------------------------------------- |

#### Return

| `string` | An uppercase country/region code (e.g., `KR`, `BR`, `IN`). |
| -------- | ---------------------------------------------------------- |

#### Code Samples

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

local function OnPlayerAdded(player)
    local region = LocalizationService:GetCountryRegionForPlayerAsync(player)
    print(player.Name, "is from", region)
end
Players.PlayerAdded:Connect(OnPlayerAdded)
```

### GetTranslatorForLocaleAsync

Takes a locale code as argument, waits until the cloud translation table for that locale is loaded, and, if available, returns a Translator object that can be used to perform translations for that locale.

If the provided locale is not supported, a Translator fallen back to English (`en`) is returned. Prefix-based similarity matching is applied for English-family (`en-us`), Portuguese-family (`pt-pt`), and Hindi-family (`hi-in`) locales.

Repeated calls for the same locale return the cached Translator instance as-is.

If the cloud translation table is not yet loaded, the calling script yields until the load completes.

#### Parameters

| `string` Locale | A locale ID string (e.g., `ko-kr`, `pt-br`, `hi-in`, `en`). |
| --------------- | ----------------------------------------------------------- |

#### Return

| `Translator` | A Translator object corresponding to the given locale. |
| ------------ | ------------------------------------------------------ |

#### Code Samples

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

local translator = LocalizationService:GetTranslatorForLocaleAsync("ko-kr")
local translated = translator:Translate(game, "Hello, world!")
print(translated)
```

### GetTranslatorForPlayerAsync

Takes a player as argument, waits until the cloud translation table for the locale set in that player's operating system is loaded, and, if available, returns a Translator object that can be used to perform translations for that locale.

Internally, it works the same way as GetTranslatorForLocaleAsync() based on the player's locale ID, and unsupported locales fall back to `en`.

If the cloud translation table is not yet loaded, the calling script yields until the load completes.

#### Parameters

| `Instance` Player | The target player whose Translator will be retrieved. |
| ----------------- | ----------------------------------------------------- |

#### Return

| `Translator` | A Translator object corresponding to the player's locale. |
| ------------ | --------------------------------------------------------- |

#### Code Samples

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

local function OnPlayerAdd(player)
    local translator = LocalizationService:GetTranslatorForPlayerAsync(player)
    print(translator:Translate(game, "Welcome!"))
end
Players.PlayerAdded:Connect(OnPlayerAdd)
```

## Events

## See also

{% content-ref url="/pages/WVDYnBXcYq2kgHJVufk9" %}
[Localization](/manual/studio-manual/game-development/localization.md)
{% endcontent-ref %}


---

# 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/development/api-reference/classes/localizationservice.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.