텍스트 현지화

언리얼 엔진 4 (UE4) 의 텍스트는 현지화를 위한 기본 구성 요소입니다. C++ 에서 FText 유형으로 표현되는 특수 스트링입니다. 사용자가 보게 되는 현지화가 필요한 텍스트에 사용해야 합니다.

내부적으로 FText 는 ITextData 로의 TSharedRef 로 구현됩니다. 그러면 매우 낮은 비용으로 복사할 수 있으며, FTextSnapshot 유틸리티를 통해 캐시에 저장된 FText 값이 실제로 바뀌었는지 효율적으로 감지할 수 있습니다.

FText 인스턴스 안에 저장된 데이터는 FText 생성 방식에 따라 다양합니다. 이 다양성은 내부 "텍스트 히스토리" (FTextHistory) 로 처리합니다. 텍스트 히스토리는 컬처에 맞는 텍스트 리빌드를 지원하며, 다음에 대한 핵심 구성 요소를 형성하기도 합니다.

• 컬처를 라이브로 전환합니다.

• 네트워크를 통해 FText 를 전송합니다.

• 컬처 무관 소스를 생성합니다.

FText 를 FString 으로 변환하는 것은 일반적으로 텍스트 히스토리를 잃어버리는 손실성 작업입니다. 현지화 데이터가 더이상 필요치 않은 경우에만 수행해야 합니다. 예를 들어, 하위 API 가 있는데 스트링에 작동하고, 그 스트링은 텍스트 변경을 감시하는 상위 API 에 관리받는 경우입니다 (예: STextBlock). 이 변환은 스트링만 받는 외부 API 로 데이터를 전달할 때도 사용할 수 있습니다.

현지화되지 않는 텍스트(, 예로 플레이어 이름을 외부 API 에서 UI 에 표시할 수 있는 형태로 변환한 텍스트)가 필요한 경우, FText::AsCultureInvariant 를 사용하여 현지화 데이터가 없(고 현지화할 수도 없)는 FText 인스턴스를 만듭니다. INVTEXT 매크로는 리터럴 스트링에 대해서도 똑같이 할 수 있습니다.

텍스트 리터럴

현지화가능 텍스트는 세 가지 구성 요소로 이루어집니다. namespace (네임스페이스), (정체성을 형성하는) key (키), (번역되는 내용의 기초이자 "stale" (구버전) 번역에 대한 유효성 검사 역할을 하는) source string (소스 스트링)입니다. 가장 흔한 방법은 UE4 에서 현지화가능 텍스트를 텍스트 리터럴로 만드는 것입니다.

C++ 에서 텍스트 리터럴 생성

C++ 로 텍스트 리터럴을 만들려면 LOCTEXT 매크로 군을 사용합니다.

텍스트 리터럴 매크로

예:

	// LOCTEXT 에 사용할 네임스페이스 정의
	// 단일 파일 안에서만 유효하며, 파일이 끝나기 전 정의해야 합니다.
	#define LOCTEXT_NAMESPACE "MyNamespace"
	// 텍스트 리터럴을 생성합니다.
	constFTextHelloWorld= NSLOCTEXT("MyOtherNamespace","HelloWorld","Hello World!")
	constFTextGoodbyeWorld= LOCTEXT("GoodbyeWorld","Goodbye World!")
	// 파일이 끝나기 전 네임스페이스 정의를 해제합니다.
	#undef LOCTEXT_NAMESPACE
Copy full snippet

// LOCTEXT 에 사용할 네임스페이스 정의 // 단일 파일 안에서만 유효하며, 파일이 끝나기 전 정의해야 합니다. #define LOCTEXT_NAMESPACE "MyNamespace" // 텍스트 리터럴을 생성합니다. constFTextHelloWorld= NSLOCTEXT("MyOtherNamespace","HelloWorld","Hello World!") constFTextGoodbyeWorld= LOCTEXT("GoodbyeWorld","Goodbye World!") // 파일이 끝나기 전 네임스페이스 정의를 해제합니다. #undef LOCTEXT_NAMESPACE

INI 파일에서 텍스트 리터럴 생성

텍스트 리터럴은 NSLOCTEXT 매크로 문법을 사용하여 INI 파일에서 만들 수 있습니다.

애셋에서 텍스트 리터럴 생성

텍스트 리터럴은 FText 프로퍼티를 사용해서 만들 수 있습니다. 키는 자동 생성되지만, 텍스트 칸 옆 고급 콤보 박스로 텍스트에 커스텀 네임스페이스 또는 키를 정의할 수 있습니다. 기본 네임스페이스 또는 키를 사용해도 괜찮습니다.

텍스트 포맷

텍스트 포맷에 제공되는 방법으로 텍스트를 조합하면 현지화가 쉬워집니다. 현지화가능 포맷 패턴을 사용해서 자리표시자에 실제 텍스트를 주입하는 식입니다.

포맷 자리표시자는 한 짝의 중괄호 안에 포함되며, 그 이름은 (인덱스 기반 포맷의 경우) 숫자 또는 (이름 기반 포맷의 경우) 스트링이 될 수 있습니다. 예:

"생명력이 {0} 남았습니다." "생명력이 {CurrentHealth} 남았습니다."

포맷 자리표시자는 인수 데이터에 실행시킬 ("인수 수정자"라고도 하는) 함수를 지정할 수도 있습니다. 파이프(|)에 함수 이름과 인수를 붙여 지정합니다. 예:

"{NumCats} {NumCats}|plural(one=cat,other=cats)"

C++ 의 텍스트 포맷

C++ 에서의 텍스트 포맷 처리는 FText::Format 함수 군으로 합니다. 각 함수는 FTextFormat 패턴을 받는데, FText 인스턴스에서 묵시적으로 생성한 뒤, 아래 표에 정의된 것과 같은 추가 인수가 붙습니다.

자주 사용하는 포맷 패턴은 FTextFormat 로 미리 컴파일해 두어야 포맷 퍼포먼스가 빨라집니다. 컴파일된 패턴은 활성 컬처가 변경되면 자동 리컴파일합니다.

블루프린트의 텍스트 포맷

블루프린트의 텍스트 포맷은 Format Text 노드로 처리합니다. 이 노드는 리터럴 포맷 패턴을 받을 수도, 다른 텍스트 핀에 연결된 패턴을 가질 수도 있습니다.

• 리터럴 포맷 패턴을 지정하면, 포맷 인수 핀은 자동 생성됩니다.

• 포맷 패턴을 다른 텍스트 핀에 연결하면, 그 노드의 디테일 패널에서 포맷의 인수를 수동 지정해야 합니다.

인수 수정자

인수 수정자(argument modifier)는 인수를 포맷 스트링에 추가하기에 앞서 전처리하는 방법을 제공합니다. 인수 수정자는 확장 가능합니다. 인수 수정자를 만들려면 ITextFormatArgumentModifier 인터페이스를 구현하고, 지정한 키워드에 대한 팩토리 함수를 등록합니다 (FTextFormatter::RegisterTextArgumentModifier 참고).

UE4 에는 복수, 성별, 한글 조사 처리와 같은 기본 인수 수정자를 제공합니다.

복수 형태

Plural (복수) 형태는 텍스트 포맷에 지정한 숫자 변수에 따라 다른 텍스트를 사용할 수 있습니다. 복수 형태는 ("There is 1 cat" 또는 "There are 4 cats" 와 같은) 기수일 수도, ("You finished 1st!" 또는 "You finished 2nd!" 와 같은) 서수일 수도 있습니다. 복수 형태는 키-값 짝으로 지정하며, (CLDR 데이터로 컬처에 정의된) 다음과 같은 키워드를 지원합니다: zero, one, two, few, many, other. 옵션으로 값을 따옴표로 묶을 수 있으며, 포맷 마커를 포함할 수도 있습니다.

기수 포맷 예제:

	"There {NumCats}|plural(one=is,other=are) {NumCats} {NumCats}|plural(one=cat,other=cats)"
Copy full snippet

"There {NumCats}|plural(one=is,other=are) {NumCats} {NumCats}|plural(one=cat,other=cats)"

서수 포맷 예제:

	"You came {Place}{Place}|ordinal(one=st,two=nd,few=rd,other=th)!"
Copy full snippet

"You came {Place}{Place}|ordinal(one=st,two=nd,few=rd,other=th)!"

성별 형태

성별 형태는 텍스트 포맷에 지정한 ETextGender 값에 따라 다른 텍스트를 사용할 수 있습니다. 예: "Le guerrier est fort" 또는 "La guerrière est forte". 성별 형태는 값의 목록으로 지정되며, [남성, 여성, 중성] 순이고, 중성은 옵션입니다. 옵션으로 값을 따옴표로 묶을 수 있으며, 포맷 마커를 포함할 수도 있습니다.

예:

	"{Gender}|gender(Le,La) {Gender}|gender(guerrier,guerrière) est {Gender}|gender(fort,forte)"
Copy full snippet

"{Gender}|gender(Le,La) {Gender}|gender(guerrier,guerrière) est {Gender}|gender(fort,forte)"

한글 조사

hpp(Hangul Post-Positions)는 한국어에서 선행하는 낱말 끝 글자의 종성 유무에 따라 바뀌는 조사를 자동으로 처리해 줍니다. 문법은 {Arg}|hpp(자음,모음) 이며, 값을 따옴표로 묶을 수도 있습니다. 예를 들어 (은,는) (이,가) (을,를) (과,와) (아,야) (이어,여) (이에,예) (이었,였) (으로,로) 같은 표준 조사는 물론, ('으로,'로) 도 가능하며, 공백이 포함되는 경우 따옴표로 묶어 주면 됩니다.

포맷 예제:

	노티파이 트랙 이름을 '{0}|hpp('으로,'로) 변경
Copy full snippet

노티파이 트랙 이름을 '{0}|hpp('으로,'로) 변경

텍스트 포맷 모범 사례

• 문장에 영향을 주는 숫자를 주입할 때는, 코드로 분기하기 보다는 plural(복수) 형태를 사용해서 변형을 처리합니다. 그러면 원본 언어의 복수형 규칙이 같지 않은 언어로도 올바르게 번역할 수 있습니다.

• 개인 명사를 주입할 때는, 그 개인의 성별에 대한 인수를 포함시켜야 합니다. 성별 문법 규칙이 있는 언어에는 중요한 부분으로, 번역가가 성별에 따라 번역이 바뀌도록 할 수 있습니다 (성별 형태 참고).

• ("table", "door", "chair" 같은) 사물에 대한 명사 주입은 피하거나, 다른 현지화 방법을 준비해야 합니다. 이와 같은 명사는 언어마다 성별이 다를 수 있습니다. 그러면 컬처 별 메타데이터 없이는 포맷 패턴 스트링의 정확한 현지화가 불가능할 것입니다. 이상적으로는, 명사만이 아닌 전체 문장을 포함시켜야 합니다. 그러면 정확한 번역을 보장할 수 있습니다.

앞으로의 UE4 버전에는 번역가가 명사를 나타내는 텍스트에 메타데이터 태그를 붙여, 나중에 그 포맷 패턴에 따라 정확한 번역이 나오도록 하는 기능을 추가할 예정입니다.

• 끊어진 문장을 연결하는 것은 피하세요. 문제가 생길 수 있습니다. 각 절이나 구의 정확한 번역이 불가능해 전체 번역이 올바르게 나오지 않을 수 있습니다. 텍스트를 전체 문장 단위로 다시 써서, 올바른 번역이 될 수 있도록 하는 것이 좋습니다.

텍스트 생성

텍스트 생성(generation)은 국제화 데이터를 사용하여 직접 현지화에 의존하지 않는 컬처에 맞는 텍스트를 만들 수 있습니다. 텍스트 생성 유형은 세 가지, 숫자(numerical), 연대(chronological), 변환(transformative)입니다.

숫자 텍스트 생성

숫자 생성은 숫자 유형을 사람이 읽기 좋은 텍스트 표현으로 변환하는 데 사용됩니다. 그 정확한 규칙은 컬처에 따라 다르며, 보다 구체적인 제어가 필요한 경우 생성 단위에 따라 조정할 수도 있습니다.

예를 들어, 기본 생성 규칙에 따라 부동소수점 수치 "1234.5" 는 영어에서 "1,234.5" 로, 프랑스어에서 "1 234,5" 로, 아랍어에서 "١٬٢٣٤٫٥" 로 생성됩니다.

C++ 에서 숫자 생성

C++ 에서의 숫자 생성을 처리하는 함수는 다음과 같습니다.

위 표의 함수 대부분은 옵션인 FNumberFormattingOptions 를 받아 (기본값을 활성 로케일에서 받는) 출력, 역시 옵션인 (기본값은 활성 로케일인) 컬처를 제어합니다.

블루프린트에서 숫자 생성

블루프린트에서의 숫자 생성을 처리하는 노드는 다음과 같습니다.

테이블의 노드 대부분은 출력을 제어하는 고급 인수를 받습니다.

연대

연대 생성은 날짜와 시간 유형을 사람이 읽기 좋은 텍스트 표현으로 변환하는 데 사용합니다. 그 정확한 규칙은 컬처에 따라 다르며, 보다 구체적인 제어가 필요한 경우 날짜/시간 스타일을 생성 단위 별로 조절할 수 있습니다.

기본 생성 규칙에 따라, 1998 년도 5 번째 달 22 번째 날을 나타내는 연대는 미국 영어에서 "May 22, 1998", 영국 영어에서 "22 May 1998", 프랑스어에서 "22 mai 1998", 아랍어에서 "٢٢‏/٠٥‏/١٩٩٨" 이 됩니다.

C++ 에서 연대 생성

C++ 에서 연대 생성을 처리하는 함수는 다음과 같습니다.

위 대부분은 EDateTimeStyle 를 받아 출력을 제어합니다 (기본값은 활성 로케일에서 구하지만, "short", "medium", "long", "full" 로 설정할 수도 있습니다).

시간 생성에서 기본으로 기대하는 값은 UTC 기반 시간입니다 (이것을 현지 시간대로 변환합니다). 지정한 시간이 UTC 기반이 아니면 (즉 이미 현지 시간이면), [FText::GetInvariantTimeZone()](https://api.unrealengine.com/INT/API/Runtime/Core/Internationalization/FText/GetInvariantTimeZone/index.html) 을 시간대 인수로 전달해야 합니다.

블루프린트에서 연대 생성

블루프린트에서 연대 생성을 처리하는 노드는 다음과 같습니다.

변환

변환 생성은 텍스트를 다른 표현으로 변환하는 데 사용합니다. 예를 들어 소문자 텍스트를 대문자로, 또는 대문자를 소문자로 변환할 수 있습니다.

C++ 에서 변환 생성

C++ 에서 변환 생성을 처리하는 함수는 다음과 같습니다.

블루프린트에서 변환 생성

블루프린트에서 변환 생성을 처리하는 노드는 다음과 같습니다.

스트링 테이블

String Table(스트링 테이블)은 현지화 텍스트를 하나( 또는 다수)의 알려진 위치로 집중시킨 뒤, 스트링 테이블 안의 항목을 다른 애셋이나 코드에서 참조하는 안전한 방식으로 현지화 텍스트를 쉽게 재사용할 수 있습니다.

스트링 테이블은 C++ 에서 정의할 수 있으며, CSV 파일로 로드하거나 애셋으로 생성할 수 있습니다. 자세한 정보는 스트링 테이블 문서를 참고하세요.

텍스트 값 마셜링

텍스트 값은 스트링으로 무손실 마셜링(marshall)할 수 있습니다 (FTextStringHelper, 또는 UTextProperty 의 ImportText 및 ExportText 함수 사용).

지원 포맷은 다음과 같습니다.

"Raw" (원시) 스트링 역시 임포트할 수 있지만, 임포트할 때마다 새 키가 생성됩니다. 현지화에 쓸 키가 불안정해 집니다.

데이터 테이블

현지화 키가 불안정해 지는 일반적인 원인 중 하나는, CSV 파일에서 원시 스트링을 데이터 테이블로 반복해서 임포트하는 것인데, 그 때마다 새 키가 생성되기 때문입니다. 그에 대한 해법은 임포트한 키를 임포트 이후 결정론적 키에 할당하면 되는데, 행 구조체에서 OnPostDataImport 함수를 오버라이드한 뒤 FText::ChangeKey 를 호출하여 새 키를 할당하면 됩니다.

일반적으로 데이터 테이블 이름을 네임스페이스로, 행 이름과 프로퍼티 이름 조합을 키로 사용합니다. 예:

	voidFMyTableRow::OnPostDataImport(constUDataTable*InDataTable,constFNameInRowName,TArray&OutCollectedImportProblems)
	{
	#if WITH_EDITOR
		MyTextProperty = FText::ChangeKey(
		InDataTable->GetName(),
		FString::Printf(TEXT("%s_%s"),*InRowName.ToString(), GET_MEMBER_NAME_STRING_CHECKED(FMyTableRow,MyTextProperty)),
		MyTextProperty
		);
	#endif// WITH_EDITOR
	}
Copy full snippet

voidFMyTableRow::OnPostDataImport(constUDataTable*InDataTable,constFNameInRowName,TArray&OutCollectedImportProblems) { #if WITH_EDITOR MyTextProperty = FText::ChangeKey( InDataTable->GetName(), FString::Printf(TEXT("%s_%s"),*InRowName.ToString(), GET_MEMBER_NAME_STRING_CHECKED(FMyTableRow,MyTextProperty)), MyTextProperty ); #endif// WITH_EDITOR }

4.22 릴리즈에서 결정론적 키는 이미 데이터 테이블에 임포트하는 원시 키에 적용되지만, 키 설정 방식을 사용자 정의할 필요가 있는 경우 여전히 OnPostDataImport 를 오버라이드하면 됩니다.

다언어 데이터

Polyglot(다언어) 데이터는 런타임에 새로운 현지화 데이터를 추가할 수 있는데, 외부 시스템으로 인터페이스를 통할 수도 있고, 새로운 LocRes 파일을 만들지 않는 핫픽스 현지화를 사용할 수도 있습니다.

다언어 데이터는 네임스페이스와 키(정체성), 네이티브 스트링, 다언어 데이터 사용 시점 제어를 위한 텍스트의 카테고리 (예: 게임, 엔진, 에디터), 옵션 네이티브 컬처 (카테고리가 설정되지 않은 경우 예비 전환할 네이티브 컬처), 일련의 컬처 별 번역으로 이루어집니다.

다언어 데이터를 사용하여 기존 번역을 오버라이드하려면, 다언어 데이터의 네임스페이스, 키, 네이티브 스트링이 대체하려는 소스 텍스트에 일치하는지 확인해야 합니다.

C++ 에서 다언어 데이터

C++ 에서 다언어 데이터는 FPolyglotTextData 유형으로 나타나며, (FPolyglotTextData::GetText 를 사용해서 다언어 데이터를 텍스트 인스턴스로 해석하여) 직접 사용할 수도 있고, FTextLocalizationManager::RegisterPolyglotTextData 로 전달(하여 기존 텍스트 항목을 패치)할 수도 있습니다.

블루프린트에서 다언어 데이터

블루프린트에서 다언어 데이터는 Polyglot Text 데이터 유형으로 나타나며, Polyglot Data to Text 함수와 함께 사용하여 다언어 데이터를 텍스트 인스턴스로 해석(resolve)할 수 있습니다.

현지화 텍스트 소스

현지화 텍스트 소스는 UE4 텍스트 현지화 매니저가 현지화 텍스트 데이터를 발견하고 처리하는 주요 방법입니다. UE4 는 기본적으로 두 가지를 제공합니다. (LocRes 지원을 호스팅하는) FLocalizationResourceTextSource, (다언어 데이터 지원을 호스팅하는) FPolyglotTextSource 입니다.

현지화 텍스트 소스는 외부 시스템과의 인터페이스를 쉽게 할 수 있는 방법을 제공하며, ILocalizedTextSource 에서 파생되는 유형을 생성 및 등록하여 프로젝트 단위로 추가할 수 있습니다.