국가/언어

이해하기

글로벌 언어 정책

스토브 플랫폼 및 게임 이용자에게 노출되는 언어는 기본적으로 스토브가 정한 글로벌 언어 운영 정책에 따라 제공해요. 아래 상위 정책을 기준으로 적용하며, 세부 사항은 현업에 맞추어 조정할 수 있으니 퍼블리싱 기술 담당자를 통해 논의해 주세요.

글로벌 언어 상위 정책

스토브 서비스 언어 노출 기준

국가/언어 서비스란?

스토브 SDK는 현재 접속한 이용자의 국가 정보(GDS)와 파트너스에 등록된 게임 상수 정보를 초기화 이후 조회할 수 있는 기능을 제공해요.
또한 스토브 플랫폼의 표시 언어를 게임 언어에 맞춰 변경할 수 있어, 플레이어가 경험하는 언어를 일관되게 유지할 수 있어요.
모든 기능은 SDK initialize 완료 이후에 동작해요.

기능 구성

플랫폼 표시 언어 지원 목록

총 10개 언어를 지원해요.

개발하기

국가/게임 정보 얻기

이 섹션에서는 두 가지 정보를 가져오는 방법을 다뤄요.

• GDS 획득: 현재 접속한 이용자의 국가 정보(Global Domain Service)를 가져와요. nation, lang, regulation, timezone 등을 포함해요. (Mobile / PC 모두 지원)
• 게임 상수 정보 획득: 파트너스에 등록한 key-value를 클라이언트에서 조회해요. (Mobile 전용, PC 환경 미지원)

GDS 응답 예시: {"is_default":false,"nation":"KR","lang":"ko","regulation":"KOREA","timezone":"Asia/Seoul","utc_offset":540,"ip":"211.34.57.xxx"}

모바일

사전 준비

• SDK 초기화(initialize)가 완료된 이후에 호출해요.
• Constants.get은 동기 함수예요. 별도 콜백 등록이 필요 없어요.
• 게임 상수 정보 획득 사용 시 추가 준비: 파트너스 SDK Config에 game_config 모듈을 추가해야 해요.
  • 위치: 파트너스 > GM > SDK Config 설정 > 게임 별 Config 관리(mo) > game_config 모듈

개발 흐름

GDS 획득

1. SDK 초기화 완료 콜백 안에서 Constants.get("gds", "")를 호출해 GDS 정보를 조회해요.
2. 반환값(JSON 문자열)에서 nation, lang, regulation, timezone 등을 파싱해 사용해요.
3. 국가 코드만 필요하면 Constants.get("nation", "")로 간단히 조회할 수 있어요.
4. is_default가 true면 IP로 국가 판별이 어려워 스토브 기본값이 반환된 상태예요. 분기 로직에서 기본값 처리나 재시도 정책을 적용해요.

게임 상수 정보 획득

1. 파트너스 game_config 모듈에 게임이 사용할 key-value 항목을 등록해요.
2. SDK 초기화 완료 콜백 안에서 Constants.get("game_config", "")를 호출해 등록된 값을 JSON 문자열로 받아요.
3. JSON을 파싱해 필요한 key 값을 사용해요.

트러블슈팅

GDS 획득

게임 상수 정보 획득

샘플 코드

GDS 획득

public void GetGds() {
    string gds = Constants.Get("gds");
    //ex) {"is_default":false,"nation":"KR","lang":"ko","regulation":"KOREA","timezone":"Asia/Seoul","utc_offset":540,"ip":"211.34.57.xxx"}
    string nation = Constants.Get("nation"); // ex) KR
}

게임 상수 정보 획득

public void GetGameConstants() {
    string gameConfig = Constants.Get("game_config");
}

PC (PCSDK)

사전 준비

• BaseSDK 초기화(Base_Initialize)가 완료된 이후에 호출해요. 초기화 전에 호출하면 BASE_NOT_INITIALIZED(16) 에러가 반환돼요.
• Base_GetGds는 동기 함수예요. 콜백 등록이 필요 없어요.
• 게임 상수 정보(game_config)는 PCSDK에서 제공하지 않아요. 모바일 전용 기능이에요.

개발 흐름

1. 게임 시작 시 Base_RestartAppIfNecessary 콜백 → Base_Initialize 완료 이후 Base_GetGds(&gds)를 호출해 GDS 정보를 조회해요.
2. 반환된 결과(Result)를 IsSuccessful()로 검증해요.
3. 성공 시 StovePCGds 객체에서 GetNation(), GetLanguage(), GetRegulation(), GetTimeZone(), GetUtcOffset(), IsDefault() 값을 사용해요.
4. 실패 시 에러 코드별 처리(트러블슈팅 표 참고)를 진행해요.

트러블슈팅

샘플 코드

// BaseSDK 초기화 완료 콜백 안에서 호출 (기존 구 API)
Stove::PCSDK::Base::StovePCGds gds;
auto result = Stove::PCSDK::Base::Base_GetGds(&gds);
if (result.IsSuccessful())
{
    const wchar_t* nation = gds.GetNation();
    const wchar_t* language = gds.GetLanguage();
    // 국가/언어에 따른 분기 로직을 구현해 주세요.
}
else
{
    // 실패 시 로직을 구현해 주세요. (에러 코드별 처리 참고)
}

플랫폼 표시 언어변경

모바일

사전 준비

• SDK 초기화 완료 이후에 호출해요.
• 지원 언어는 총 10개이며, Language.System을 전달하면 디바이스 설정 언어를 따라요.
• 지원하지 않는 언어로 설정을 시도하면 디폴트 언어인 영어(English)로 노출돼요.

개발 흐름

1. 게임 내 언어 설정이 변경되거나, 게임 시작 시 이용자 언어를 적용할 때 Localization.setLanguage(...)를 호출해요.
2. 명시적 언어로 변경하려면 원하는 Language 값을 인자로 전달해요. (예: Language.English)
3. 디바이스 언어로 되돌리려면 Language.System을 전달해요. (게임에서 별도로 언어를 지정하지 않거나 초기화 상태로 돌리고 싶을 때 사용)

트러블슈팅

샘플 코드

언어 설정하기

원하는 언어 코드를 전달해 플랫폼 언어를 명시적으로 변경해요.

public void SetLanguage(Localization.Language language)
{
    Localization.SetLanguage(language);
}

디바이스 언어로 변경하기

Language.System을 전달해 디바이스 기본 언어를 따르도록 설정해요.

public void SetDefaultLanguage()
{
    Localization.SetLanguage(Localization.Language.System);
}

PC (PCSDK)

사전 준비

• BaseSDK 초기화 완료 이후에 호출해요.
• 언어는 enum 또는 문자열(ISO 639-1)로 지정할 수 있어요.
  • enum 기반: Base_SetLanguage(StoveLanguage) — 미리 정의된 StoveLanguage enum 값을 전달해요.
  • 문자열 기반: Base_SetLanguageEx(C/C++ const wchar_t*, C# string) — 게임에서 사용하는 ISO 639-1 언어 코드를 그대로 전달해요.
• PCSDK는 12개 언어를 지원해요(system / en / ko / ja / zh-cn / zh-tw / de / fr / es / pt / th / vi).

개발 흐름

1. 게임 내 언어 설정이 변경되거나, 게임 시작 시 이용자 언어를 적용할 때 호출해요.
2. 문자열(ISO 639-1)로 언어를 지정해 Base_SetLanguageEx를 호출하거나, enum 값으로 Base_SetLanguage를 호출해요.
3. 디바이스 언어로 되돌리려면 문자열 "system"을 전달해요.
4. 반환된 결과를 IsSuccessful()로 검증해요.

트러블슈팅

샘플 코드

// enum 기반 (기존 구 API)
auto result = Stove::PCSDK::Base::Base_SetLanguage(Stove::PCSDK::Base::StoveLanguage::ko);
if (result.IsSuccessful())
{
    // 성공 시 로직을 구현해 주세요.
}
else
{
    // 실패 시 로직을 구현해 주세요.
}

// 문자열 기반 (ISO 639-1)
Stove::PCSDK::Base::Base_SetLanguageEx(L"ko");

// 디바이스 언어로 복귀
Stove::PCSDK::Base::Base_SetLanguageEx(L"system");

자주 묻는 질문