# Translator

Translator : `Instance`

## Overview

Translator는 특정 로케일에 대응되는 번역기 객체로, 클라우드 번역 테이블에 등록된 항목을 해당 로케일로 변환하여 반환합니다.

직접 생성할 수 없으며, LocalizationService:GetTranslatorForLocaleAsync() 또는 LocalizationService:GetTranslatorForPlayerAsync()를 통해서만 획득할 수 있습니다. 동일 로케일에 대해서는 캐싱된 인스턴스가 재사용됩니다.

원본 문자열 자체를 키로 조회하려면 `Translate()`를, 별도로 지정된 키와 포맷 매개변수를 사용하려면 `FormatByKey()`를 사용합니다.

## Properties

### LocaleId

`string`

번역된 문자열에 적용되는 로케일 ID로 `en-us` 형식의 문자열을 반환하는 읽기 전용 속성입니다. 기본값은 `en-us`입니다.

LocalizationService:GetTranslatorForLocaleAsync() 또는 LocalizationService:GetTranslatorForPlayerAsync()로 Translator를 가져올 때, 요청한 로케일이 지원되지 않으면 영어(`en`)로 fallback된 값이 반환되며, prefix 기준 유사 매칭(예: `en-us` → `en`)도 이 값에 반영됩니다.

#### Code Samples

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

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

## Methods

### FormatByKey

Translator 로케일에 따라 지정된 key로 클라우드 번역 테이블에서 지역화된 텍스트 문자열을 반환합니다.

원본 텍스트의 형식 매개변수를 args로 전달하여 채워 넣을 수 있으며, args는 키-값 테이블 형태로 지정합니다.

지원하는 인자 데이터 타입은 다음과 같습니다.

* `number`
* `string`
* `bool`
* `Instance` (이름이 사용됨)
* `CFrame`
* `Vector3`
* `Vector2`
* `Color3`
* `BrickColor`
* `MenuItem`

전달된 args의 개수 또는 이름이 원본 Source의 포매팅 토큰과 일치하지 않거나, Key는 유효하지만 해당 로케일의 번역 텍스트가 비어 있으면 에러가 출력됩니다.

#### Parameters

| `string` Key | 조회 및 번역할 항목의 Key 값입니다.                                      |
| ------------ | ----------------------------------------------------------- |
| `Value` Args | 형식 문자열에 채워 넣을 매개변수입니다. 숫자 인덱스 배열 또는 명명된 매개변수 테이블 형태로 전달합니다. |

#### Return

| `string` | 번역되고 포맷된 텍스트 문자열입니다. |
| -------- | -------------------- |

#### Code Samples

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

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

### Translate

Translator 로케일에 따라 원본 Source 텍스트로 클라우드 번역 테이블을 조회하여 지역화된 텍스트 문자열을 반환합니다.

`FormatByKey()`가 Key를 기반으로 조회하는 것과 달리, `Translate()`는 Source 텍스트 원문을 그대로 조회 키로 사용합니다.

context 인수에는 컨텍스트 오버라이드에 사용할 게임 내 Instance를 전달하며, 별도의 컨텍스트 오버라이드가 필요하지 않으면 `game`을 전달하는 것을 권장합니다. PlayerGui 내부 인스턴스를 전달할 경우 PlayerGui 이하의 경로만 컨텍스트로 사용됩니다.

context를 전달하더라도 해당 컨텍스트와 일치하는 항목이 없을 경우, 단일 Source 매칭으로 fallback되어 표시될 수 있습니다.

#### Parameters

| `Instance` Context | 컨텍스트 매칭에 사용할 인스턴스입니다. 별도 오버라이드가 필요 없으면 `game`을 전달합니다. |
| ------------------ | ----------------------------------------------------- |
| `string` Source    | 조회 및 번역할 Source 텍스트입니다.                               |

#### Return

| `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/s8jDFPa97Wp49c1BRCXN" %}
[Localization](/korean/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/korean/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.