# Translator

Translator : `Instance`

## Overview

Translator is a translator object corresponding to a specific locale. It converts entries registered in cloud translation table into that locale and returns the results.

It cannot be created directly and can only be obtained through LocalizationService:GetTranslatorForLocaleAsync() or LocalizationService:GetTranslatorForPlayerAsync(). For the same locale, a cached instance is reused.

Use `Translate()` to look up entries by source string, and use `FormatByKey()` to use an explicitly specified key and format parameters.

## Properties

### LocaleId

`string`

A read-only property that returns the locale ID applied to translated strings, formatted like `en-us`. The default is `en-us`.

When a Translator is obtained via LocalizationService:GetTranslatorForLocaleAsync() or LocalizationService:GetTranslatorForPlayerAsync(), if the requested locale is unsupported, this value reflects the fallback to English (`en`). Prefix-based similarity matching (e.g., `en-us` → `en`) is also reflected in this value.

#### Code Samples

```lua
local LocalizationService = game:GetService("LocalizationService")
local translator = LocalizationService:GetTranslatorForLocaleAsync("pt-br")

print(translator.LocaleId) -- "pt-br"
```

## Methods

### FormatByKey

Returns a localized text string from a cloud translation table by the given key, based on the Translator's locale.

Format parameters in the source text can be filled in by passing them through args, which should be specified as a key-value table.

The supported argument data types are:

* `number`
* `string`
* `bool`
* `Instance` (its name is used)
* `CFrame`
* `Vector3`
* `Vector2`
* `Color3`
* `BrickColor`
* `MenuItem`

An error is raised if the number or names of the provided `args` do not match the formatting tokens in the original `Source`, or if the key is valid but the translated text for the locale is empty.

#### Parameters

| `string` Key | The Key value of the entry to look up and translate.                                                              |
| ------------ | ----------------------------------------------------------------------------------------------------------------- |
| `Value` Args | The parameters to fill into the format string. Provided as a number-indexed array or a table of named parameters. |

#### Return

| `string` | The translated and formatted text string. |
| -------- | ----------------------------------------- |

#### Code Samples

```lua
local LocalizationService = game:GetService("LocalizationService")
local translator = LocalizationService:GetTranslatorForLocaleAsync("ko-kr")

local message = translator:FormatByKey("greeting", { name = "Cheolsu", lv = 4 })
print(message)
```

### Translate

Looks up the cloud translation table by the original Source text based on the Translator's locale and returns the localized text string.

Unlike `FormatByKey()`, which looks up entries by Key, `Translate()` uses the Source text itself as the lookup key.

For the context argument, pass a game-internal Instance used for context override. If no context override is needed, passing `game` is recommended. When passing an instance inside PlayerGui, only the path under PlayerGui is used as context.

Even if a context is passed, if there is no entry matching that context, it may fall back to matching by Source alone.

#### Parameters

| `Instance` Context | The instance to use for context matching. If no override is needed, pass `game`. |
| ------------------ | -------------------------------------------------------------------------------- |
| `string` Source    | The Source text to look up and translate.                                        |

#### Return

| `string` | The translated text string. |
| -------- | --------------------------- |

#### Code Samples

```lua
local LocalizationService = game:GetService("LocalizationService")
local translator = LocalizationService:GetTranslatorForLocaleAsync("ko-kr")

print(translator:Translate(game, "Hello, world!"))
```

## 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/translator.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.