> For the complete documentation index, see [llms.txt](https://docs.overdare.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.overdare.com/korean/development/api-reference/classes/translator.md).

# 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 %}