Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

게임 국제화하기

소개

Sería excelente que el mundo hablara solo un idioma(만약 세계가 오직 하나의 언어로 말할수 있었다면 굉장했을 것이다). 불행하게도, 우리 개발자들은 저러한 상황이 아닙니다. 인디 게임 혹은 틈새 게임은 보통 현지화를 필요로 하지 않습니다. 하지만 훨씬 더큰 시장을 목표로 삼은 게임들은 현지화가 자주 필요합니다. Godot는 이러한 것을 더욱 간단하게 진행하도록 만드는 많은 기능들을 제공합니다. 따라서 이번 튜토리얼은 팁과 재주의 콜랙숀과 같은 것입니다.

현지화는 일반적으로 해당 작업을 위해 고용된 특정 스튜디오에서 수행됩니다. 이를 위해 사용할 수 있는 소프트웨어와 파일 형식이 엄청나게 많음에도 불구하고 오늘날까지 현지화를 수행하는 가장 일반적인 방법은 여전히 스프레드시트를 사용하는 것입니다. 스프레드시트를 만들고 가져오는 과정은 이미 번역 가져오기 튜토리얼에서 다루었습니다. 이전에 번역 가져오기 페이지를 읽지 않았다면 이 페이지를 읽기 전에 먼저 읽어 보시기 바랍니다.

참고

우리는 예제로써 공식 데모를 사용합니다. 애셋 라이브러리에서 다운로드할 수 있습니다.

가져온 번역 구성하기

번역은 변경될 때 업데이트되고 다시 가져올 수 있지만 여전히 프로젝트에 추가해야 합니다. 프로젝트 → 프로젝트 설정 → 현지화에서 완료합니다:

위의 대화 상자는 프로젝트 전체적으로 번역을 추가 혹은 제거에 사용합니다.

리소스 현지화하기

Godot를 현재 언어에 의존하는 애셋의 버전을 오가며 사용할 수 있도록 구성하는 것도 가능합니다.

리맵 탭이 이를 위해 사용됩니다:

다시 매핑할 리소스를 선택한 다음 각 로캘에 대한 몇 가지 대안을 추가합니다.

참고

DynamicFonts에는 리소스 재매핑 시스템이 지원되지 않습니다. 언어의 스크립트에 따라 다른 글꼴을 사용하려면 원하는 만큼 많은 대체 글꼴을 정의할 수 있는 DynamicFont 대체 시스템을 대신 사용하세요.

DynamicFont 폴백 시스템의 장점은 현재 언어와 관계없이 작동하므로 텍스트 언어가 클라이언트 언어와 일치하지 않을 수 있는 멀티플레이어 채팅과 같은 작업에 이상적이라는 것입니다.

자동으로 언어 설정하기

디폴트로 OS.get_locale_language()를 통해 얻을 수 있는 사용자가 선호하는 언어로 설정하는 것을 권장합니다. 게임이 해당 언어로 사용할 수 없는 경우, 프로젝트 설정 > 국제화 > 로케일의 폴백으로 , 또는 비어 있는 경우 en으로 폴백됩니다. 그렇지만 (번역 품질이나 플레이어 선호도 등) 여러 가지 이유로 플레이어가 게임 내에서 언어를 변경할 수 있도록 하는 것이 좋습니다.

var language = "automatic"
# Load here language from the user settings file
if language == "automatic":
   var preferred_language = OS.get_locale_language()
   TranslationServer.set_locale(preferred_language)
else:
   TranslationServer.set_locale(language)

로케일 대 언어

locale은 일반적으로 언어와 지역 또는 국가의 조합이지만, 스크립트나 변종과 같은 정보도 포함할 수 있습니다.

예시:

en: 영어
en_GB: 영국의 영어 / 영국 영어
en_US: 미국의 영어 / 미국 영어
en_DE: 독일의 영어

인디 게임은 일반적으로 언어만 신경 쓰면 되지만, 자세한 정보는 계속 읽어보세요.

로케일의 존재 이유는 미국과 영국을 통해 설명할 수 있습니다. 두 나라는 같은 언어(영어)를 사용하지만 여러 측면에서 차이가 있습니다:

철자: 예: gray (미국), grey (영국)
단어의 사용: 예: eggplant (미국), aubergine (영국)
단위 또는 통화: 예: feet/inches (미국), meters/cm (영국)

하지만 상황은 더 복잡해질 수 있습니다. (예: MMO에서) 유럽과 중국에서 서로 다른 내용을 제공한다고 가정해 보겠습니다. 해당 내용 변종을 여러 언어 안으로 번역하고 그에 따라 저장 및 불러와야 합니다.

키를 텍스트로 변환하기

Button과 Label과 같은 일부 컨트롤은 만약 그 텍스트가 번역 키와 일치하면 자동으로 번역을 가져옵니다. 예로 들어, 레이블의 텍스트가 "MAIN_SCREEN_GREETING1"이고 해당 키가 현재 번역에 존재한다면, 텍스트는 자동으로 번역됩니다.

이 자동 번역은 특정 상황에서는 바람직하지 않을 수 있습니다. 예를 들어, 레이블을 사용하여 플레이어의 이름을 표시할 때, 플레이어의 이름이 번역 키와 일치하면 번역되는 것을 원하지 않을 것입니다. 특정 노드에서 자동 번역을 비활성화하려면 인스펙터에서 현지화 > 자동 번역을 비활성화하세요.

코드에서는 Object.tr() 함수를 사용될 수 있습니다. 이것은 번역에서 텍스트를 찾아 찾으면 이를 변환합니다.

level.text = tr("LEVEL_5_NAME")
status.text = tr("GAME_STATUS_%d" % status_index)

level.Text = Tr("LEVEL_5_NAME");
status.Text = Tr($"GAME_STATUS_{statusIndex}");

참고

언어를 변경한 후에도 텍스트가 표시되지 않으면 다른 글꼴을 사용해 보세요. 기본 프로젝트 글꼴은 러시아어나 중국어와 같은 언어를 표시하는 데 사용할 수 없는 Latin-1 문자 집합의 하위 집합만 지원합니다.

다국어 글꼴에 대한 좋은 리소스는 `Noto Fonts <https://www.google.com/get/noto/>`__입니다. 덜 일반적인 언어를 사용하는 경우 올바른 변형을 다운로드하십시오.

글꼴을 다운로드한 후 TTF 파일을 DynamicFont 리소스에 로드하고 이를 Control 노드의 사용자 정의 글꼴로 사용하십시오. 재사용성을 높이려면 새 테마 리소스를 루트 컨트롤 노드에 연결하고 테마에서 DynamicFont를 기본 글꼴로 정의하세요.

자리표시자

번역된 문자열에 자리 표시자를 포함하려면 GDScript 형식 문자열 또는 C#의 동등한 기능을 사용하세요. 이를 통해 번역자는 문자열에서 자리 표시자의 위치를 자유롭게 이동할 수 있으므로 번역이 더 자연스럽게 들릴 수 있습니다. String.format() 기능이 있는 명명된 자리 표시자는 번역자가 자리 표시자가 나타나는 *순서*를 선택할 수 있도록 허용하므로 가능할 때마다 사용해야 합니다.

# The placeholder's locations can be changed, but not their order.
# This will probably not suffice for some target languages.
message.text = tr("%s picked up the %s") % ["Ogre", "Sword"]

# The placeholder's locations and order can be changed.
# Additionally, this form gives more context for translators to work with.
message.text = tr("{character} picked up the {weapon}").format({character = "Ogre", weapon = "Sword"})

번역 맥락

일반 영어를 소스 문자열로 사용하는 경우(메시지 코드 LIKE_THIS 대신) 동일한 영어 문자열을 특정 대상 언어의 다른 문자열로 번역해야 할 때 모호함에 빠질 수 있습니다. 선택적으로 *번역 컨텍스트*를 지정하여 이 모호성을 해결하고 소스 문자열이 동일하더라도 대상 언어가 다른 문자열을 사용하도록 허용할 수 있습니다.

# "Close", as in an action (to close something).
button.set_text(tr("Close", "Actions"))

# "Close", as in a distance (opposite of "far").
distance_label.set_text(tr("Close", "Distance"))

// "Close", as in an action (to close something).
GetNode<Button>("Button").Text = Tr("Close", "Actions");

// "Close", as in a distance (opposite of "far").
GetNode<Label>("Distance").Text = Tr("Close", "Distance");

복수형

대부분의 언어에서는 객체가 단수형인지 복수형인지에 따라 다른 문자열이 필요합니다. 그러나 객체가 2개 이상인지 여부에 따라 "복수형" 조건을 하드코딩하는 것은 모든 언어에서 유효하지 않습니다.

일부 언어에는 2개 이상의 복수형이 있으며 각 복수형에 필요한 개체 수에 대한 규칙이 다릅니다. Godot는 대상 로케일이 자동으로 처리할 수 있도록 복수화 지원을 제공합니다.

복수형은 양수(또는 0) 정수에만 사용됩니다. 음수 및 부동 소수점 값은 일반적으로 단수 및 복수가 명확하게 적용되지 않는 물리적 엔터티를 나타냅니다.

var num_apples = 5
label.text = tr_n("There is %d apple", "There are %d apples", num_apples) % num_apples

int numApples = 5;
GetNode<Label>("Label").Text = string.Format(TrN("There is {0} apple", "There are {0} apples", numApples), numApples);

필요한 경우 맥락과 결합할 수 있습니다:

var num_jobs = 1
label.text = tr_n("%d job", "%d jobs", num_jobs, "Task Manager") % num_jobs

int numJobs = 1;
GetNode<Label>("Label").Text = string.Format(TrN("{0} job", "{0} jobs", numJobs, "Task Manager"), numJobs);

컨트롤 크기 조정 가능

다른 언어로 된 동일한 텍스트의 길이는 크게 다를 수 있습니다. 이를 위해서는 컨트롤 크기를 동적으로 조정하는 데 도움이 될 수 있으므로 :ref:`doc_size_and_anchors`의 튜토리얼을 읽어보세요. :ref:`Container <class_Container>`도 유용할 수 있으며, :ref:`Label <class_Label>`에서 사용할 수 있는 텍스트 줄 바꿈 옵션도 사용할 수 있습니다.

UI가 원본보다 긴 문자열이 포함된 번역을 수용할 수 있는지 확인하려면 고급 프로젝트 설정에서 :ref:`pseudolocalization <doc_pseudolocalization>`을 활성화하면 됩니다. 이렇게 하면 현지화 가능한 모든 문자열이 더 긴 버전으로 바뀌고, 원래 문자열의 일부 문자가 악센트 표시된 버전으로 대체됩니다(계속 읽을 수 있음). 자리 표시자는 있는 그대로 유지되므로 의사 지역화를 활성화해도 계속 작동합니다.

예를 들어, 의사 지역화가 활성화되면 문자열 ``Hello world, this is %s!``는 ``[Ĥéłłô ŵôŕłd́, ŧh̀íš íš %s!]``가 됩니다.

처음에는 이상해 보이지만 의사 위치 파악에는 여러 가지 이점이 있습니다.

지역화할 수 없는 문자열을 빠르게 찾아낼 수 있으므로 이를 검토하고 지역화할 수 있도록 만들 수 있습니다(해당하는 경우).
긴 문자열에 맞지 않는 UI 요소를 확인할 수 있습니다. 많은 언어에서는 원본 텍스트보다 훨씬 긴 번역을 제공하므로 UI가 평소보다 긴 문자열을 수용할 수 있는지 확인하는 것이 중요합니다.
이를 통해 글꼴에 다양한 언어를 지원하는 데 필요한 모든 문자가 포함되어 있는지 확인할 수 있습니다. 그러나 의사 지역화의 목표는 원본 문자열을 읽기 쉽게 유지하는 것이므로 글꼴이 CJK 또는 오른쪽에서 왼쪽으로 쓰는 언어를 지원할 수 있는지 확인하는 효과적인 테스트는 아닙니다.

프로젝트 설정을 사용하면 의사 현지화 동작을 조정하여 원하는 경우 일부를 비활성화할 수 있습니다.

번역서버

Godot에는 :ref:`TranslationServer <class_TranslationServer>`라는 낮은 수준의 번역 관리를 처리하는 서버가 있습니다. 런타임 중에 번역을 추가하거나 제거할 수 있습니다. 현재 언어는 런타임 시 변경될 수도 있습니다.

양방향 텍스트 및 UI 미러링

아랍어와 히브리어는 오른쪽에서 왼쪽으로 작성되며(숫자와 라틴어 단어가 혼합된 경우는 제외) 이러한 언어에 대한 사용자 인터페이스도 미러링되어야 합니다. 일부 언어에서는 주변 문자에 따라 문자 모양이 변경됩니다.

양방향 쓰기 시스템 및 UI 미러링에 대한 지원은 투명하므로 일반적으로 아무것도 변경하거나 특정 쓰기 시스템에 대한 지식이 필요하지 않습니다.

RTL 언어의 경우 Godot는 자동으로 UI를 다음과 같이 변경합니다:

왼쪽/오른쪽 앵커와 여백을 미러링합니다.
왼쪽과 오른쪽 텍스트 정렬을 바꿉니다.
컨테이너에 있는 하위 컨트롤과 Tree/ItemList 컨트롤에 있는 항목의 가로 순서를 미러링합니다.
내부 제어 요소의 미러링된 순서를 사용합니다(예: OptionButton 드롭다운 버튼, CheckBox/CheckButton 정렬, 목록 열 순서, TreeItem 아이콘 및 연결선 정렬). 어떤 경우에는 미러링된 컨트롤이 별도의 테마 스타일을 사용합니다.
좌표계 (2D)
UI가 아닌 노드(스프라이트 등)는 영향을 받지 않습니다.

다음 컨트롤 속성을 사용하여 텍스트를 재정의하고 레이아웃 방향을 제어할 수 있습니다.

text_direction, 기본 텍스트 방향을 설정합니다. "auto"로 설정하면 유니코드 양방향 알고리즘에 따라 텍스트의 첫 번째 강력한 방향 문자에 따라 방향이 달라집니다.
``language``는 현재 프로젝트 로캘을 재정의합니다.
structured_text_bidi_override 속성과 _structured_text_parser 콜백을 사용하면 구조화된 텍스트에 대한 특수 처리가 가능합니다.
``layout_direction``는 제어 미러링을 재정의합니다.

이 문서 외에 여러가지 Godot 데모 프로젝트들도 살펴보면 좋습니다.

함수에 이 코드를 추가하세요:

일부 언어는 공백 없이 작성됩니다. 이러한 언어에서는 단어와 줄 바꿈에는 문자 순서에 대한 규칙 이상의 것이 필요합니다. Godot에는 ICU 규칙 및 사전 기반 중단 반복자 데이터가 포함되어 있지만 이 데이터는 기본적으로 내보낸 프로젝트에 포함되지 않습니다.

이를 포함하려면 :menu:`프로젝트 > 프로젝트 설정 > 일반 > 국제화 > 로캘`로 이동하여 :ui:`텍스트 서버 데이터 포함`을 활성화한 다음 프로젝트를 내보냅니다. Break 반복자 데이터의 크기는 약 4MB입니다.

구조화된 텍스트 BiDi 재정의

유니코드 BiDi 알고리즘은 자연 텍스트와 함께 작동하도록 설계되었으며 파일 이름, URI, 이메일 주소, 정규식 또는 소스 코드와 같은 더 높은 수준의 순서로 텍스트를 처리할 수 없습니다.

예를 들어, 표시된 디렉터리 구조의 경로는 잘못 표시됩니다(상위 "LineEdit" 컨트롤). "파일" 유형의 구조화된 텍스트 재정의는 텍스트를 세그먼트로 분할한 다음 각 세그먼트에 BiDi 알고리즘을 개별적으로 적용하여 모든 언어로 디렉터리 이름을 올바르게 표시하고 폴더의 올바른 순서를 유지합니다(하단 "LineEdit" 컨트롤).

사용자 정의 콜백은 다른 유형의 구조화된 텍스트에 대해 BiDi를 재정의하는 방법을 제공합니다.

숫자 현지화하기

숫자 입력 또는 출력을 위해 특별히 설계된 컨트롤(예: ProgressBar, SpinBox)은 현지화된 번호 매기기 시스템을 자동으로 사용합니다. 다른 컨트롤의 경우 :ref:`TextServer.format_number(string, 언어) <class_TextServer_method_format_number>`을 사용하여 서부 아라비아 숫자(0..9)를 현지화된 번호 매기기 시스템으로 변환하고 :ref:`TextServer.parse_number(string, 언어) <class_TextServer_method_parse_number>`를 사용하여 다시 변환합니다.

씬과 인스턴스 편집하기

이동 또는 방향(예: 뒤로/앞으로 버튼)을 나타내는 경우 아랍어 및 히브리어 로케일에 대해 방향을 바꿔야 할 수 있는 왼쪽 및 오른쪽 화살표가 있는 아이콘입니다. 그렇지 않으면 동일하게 유지될 수 있습니다.

번역 가져오기

프로젝트를 출시하기 전에 프로젝트의 번역을 테스트할 수 있습니다. Godot는 이를 수행하는 세 가지 방법을 제공합니다.

프로젝트 > 프로젝트 설정 > 일반 > 국제화 > 로캘`(고급 설정 사용) 아래에는 :ui:`Test 속성이 있습니다. 이 속성을 테스트하려는 언어의 로캘 코드로 설정하세요. Godot는 프로젝트가 실행될 때(편집기에서 또는 내보낼 때) 해당 로케일로 프로젝트를 실행합니다.

이는 프로젝트 설정이므로 비어 있지 않은 값으로 설정되면 버전 제어에 표시됩니다. 따라서 버전 제어에 변경 사항을 적용하기 전에 빈 값으로 다시 설정해야 합니다.

둘째, 편집기 내에서 상단 표시줄로 이동하여 상단 표시줄에서 :button:`보기`를 클릭한 다음 :ui:`Preview Translation`으로 이동하여 미리 보려는 언어를 선택합니다.

../../_images/locale_editor_preview.webp

이제 편집기에서 장면의 모든 텍스트가 선택한 언어를 사용하여 표시됩니다.

:ref:`명령줄에서 Godot를 실행 <doc_command_line_tutorial>`할 때 번역을 테스트할 수도 있습니다. 예를 들어 프랑스어로 게임을 테스트하려면 다음 인수를 제공할 수 있습니다.

godot --language fr

프로젝트 이름 번역

프로젝트 이름은 다른 운영 체제 및 플랫폼으로 내보낼 때 앱 이름이 됩니다. 두 개 이상의 언어로 프로젝트 이름을 지정하려면 프로젝트 > 프로젝트 설정 > 일반 > Application > Config`로 이동하세요. 여기에서 :button:`Localised String (Size 0) 버튼을 클릭한 다음 번역 추가 버튼을 클릭하세요. 프로젝트 이름 번역을 위한 언어(필요한 경우 국가)를 선택할 수 있는 페이지로 이동합니다. 그런 다음 이제 현지화된 이름을 입력할 수 있습니다.

사용할 언어 코드가 확실하지 않은 경우 :ref:`로케일 코드 목록 <doc_locales>`을 참조하세요.