본문으로 건너뛰기

로케일 (locale)

Thumbnail Image

🚀 추가된 버전 : SDKSDKv1.11.3 AndroidAndroidv1.11.4 iOSiOSv1.11.4
🔔 최신화 일자: 2026-08-18

개요​

locale 네임스페이스는 앱에 설정된 국가 정보를 관리하는 기능을 제공합니다.

  • 앱에서 지원하는 국가 목록을 조회
  • 현재 앱에 설정된 국가코드를 조회
  • 앱의 국가코드를 변경

하나의 앱에서 국가별로 서로 다른 웹사이트 URL을 제공하는 등 다국가 지원 앱을 구현할 때 활용할 수 있습니다.
각 국가에는 ISO 3166-1 alpha-3 형식의 국가코드(ex. KOR)와 해당 국가에 대응하는 웹사이트 URL이 매핑되어 있습니다.

공지

앱 국가 설정 기능은 앱 빌드 시 국가별 URL 설정이 완료된 앱에서 사용 가능합니다.
설정이 필요한 경우 nachocode 문의를 통해 안내받으실 수 있습니다.

타입 정의​

AppCountryData​

export declare type AppCountryData = {
  countryCode: string;
  url: string;
};
속성명타입필수 여부설명
countryCodestring✅ISO 3166-1 alpha-3 형식의 국가코드 (ex. "KOR")
urlstring✅해당 국가에 대해 앱에 설정된 웹사이트 URL

GetAppCountryListResult​

앱 국가 목록 조회 결과 타입으로, 성공 시 GetAppCountryListSuccessResult, 실패 시 GetAppCountryListErrorResult를 반환합니다.

export declare type GetAppCountryListResult =
  GetAppCountryListSuccessResult | GetAppCountryListErrorResult;

GetAppCountryListSuccessResult​

export declare type GetAppCountryListSuccessResult = {
  status: 'success';
  statusCode: 200;
  message: string;
  data: AppCountryData[];
};
속성명타입필수 여부설명
status'success'✅요청 성공 상태
statusCode200✅결과 상태 코드
messagestring✅결과 메시지
dataAppCountryData[]✅앱에서 지원하는 국가 목록

GetAppCountryListErrorResult​

export declare type GetAppCountryListErrorResult = {
  status: 'error';
  statusCode: 400 | 500;
  message: string;
};
속성명타입필수 여부설명
status'error'✅요청 실패 상태
statusCode400 | 500✅에러 상태 코드
messagestring✅에러 메시지

GetAppCountryCodeResult​

현재 앱 국가코드 조회 결과 타입으로, 성공 시 GetCountryCodeSuccessResult, 실패 시 GetCountryCodeErrorResult를 반환합니다.

export declare type GetAppCountryCodeResult =
  GetCountryCodeSuccessResult | GetCountryCodeErrorResult;

GetCountryCodeSuccessResult​

export declare type GetCountryCodeSuccessResult = {
  status: 'success';
  statusCode: 200;
  message: string;
  data: string;
};
속성명타입필수 여부설명
status'success'✅요청 성공 상태
statusCode200✅결과 상태 코드
messagestring✅결과 메시지
datastring✅현재 앱에 설정된 국가코드 (alpha-3 형식, ex. "KOR")

GetCountryCodeErrorResult​

export declare type GetCountryCodeErrorResult = {
  status: 'error';
  statusCode: 400 | 500;
  message: string;
};
속성명타입필수 여부설명
status'error'✅요청 실패 상태
statusCode400 | 500✅에러 상태 코드
messagestring✅에러 메시지

SetAppCountryCodeResult​

export declare type SetAppCountryCodeResult = {
  status: 'success' | 'error';
  statusCode: number;
  message?: string;
};
속성명타입필수 여부설명
status'success' | 'error'✅국가코드 설정 성공 여부
statusCodenumber✅결과 상태 코드
messagestring❌(optional) 에러 발생 시 상세 메시지

메서드 목록​

메서드설명추가된 버전
getAppCountryList()앱에서 지원하는 국가 목록을 조회합니다.SDKSDKv1.11.3
getAppCountryCode()현재 앱에 설정된 국가코드를 조회합니다.SDKSDKv1.11.3
setAppCountryCode(countryCode)앱의 국가코드를 설정합니다.SDKSDKv1.11.3

메서드 상세​

getAppCountryList()​

타입 정의​

function getAppCountryList(): Promise<GetAppCountryListResult>;

설명​

앱에서 지원하는 국가 목록을 조회합니다.
각 항목은 국가코드와 해당 국가에 설정된 웹사이트 URL로 구성됩니다.

국가 선택 화면을 구현할 때, 선택 가능한 국가 목록을 구성하는 용도로 활용할 수 있습니다.

반환 값​

타입설명
Promise<GetAppCountryListResult>앱 국가 목록 조회 결과

사용 예제​

// 앱에서 지원하는 국가 목록 조회
const result = await Nachocode.locale.getAppCountryList();

if (result.status === 'success') {
  result.data.forEach(country => {
    console.log(country.countryCode, country.url);
    // ex. "KOR", "https://nachocode.io"
  });
} else {
  console.error('국가 목록 조회 실패: ', result.message);
}

getAppCountryCode()​

타입 정의​

function getAppCountryCode(): Promise<GetAppCountryCodeResult>;

설명​

현재 앱에 설정되어 있는 국가코드를 조회합니다.
성공 시 data 값으로 ISO 3166-1 alpha-3 형식의 국가코드(ex. "KOR")를 반환합니다.

앱 최초 실행 시 스토어 계정의 국가코드를 확인하여 해당 국가코드를 반환하며,
스토어 국가코드 조회에 실패할 경우 디바이스 언어 기준으로 변환하여 반환됩니다.

store.getStoreCountryCode()와의 차이
  • store.getStoreCountryCode() : 디바이스의 앱 스토어 계정 국가코드를 조회합니다.
  • locale.getAppCountryCode() : 앱에 설정되어 있는 국가코드를 조회합니다.

반환 값​

타입설명
Promise<GetAppCountryCodeResult>앱 국가코드 조회 결과

사용 예제​

// 현재 앱에 설정된 국가코드 조회
const result = await Nachocode.locale.getAppCountryCode();

if (result.status === 'success') {
  console.log('현재 앱 국가코드:', result.data); // ex. "KOR"
} else {
  console.error('국가코드 조회 실패: ', result.message);
}

setAppCountryCode(countryCode)​

타입 정의​

function setAppCountryCode(
  countryCode: string
): Promise<SetAppCountryCodeResult>;

설명​

앱의 국가코드를 설정합니다. 설정된 국가코드는 앱에 영구 저장되어 재실행 시에도 유지됩니다.

사용자가 국가를 직접 선택하는 화면 등에서 호출하여 앱의 국가코드를 변경할 수 있습니다.

주의사항

getAppCountryList()로 조회한 국가 목록에 포함된 국가코드를 전달해야 합니다.
지원하지 않는 국가코드를 전달할 경우 에러가 반환됩니다.

매개변수​

파라미터타입필수 여부설명
countryCodestring✅설정할 국가코드 (alpha-3 형식, ex. "KOR")

반환 값​

타입설명
Promise<SetAppCountryCodeResult>앱 국가코드 설정 결과

사용 예제​

// 앱 국가코드 설정
const result = await Nachocode.locale.setAppCountryCode('KOR');

if (result.status === 'success') {
  console.log('앱 국가코드가 설정되었습니다.');
} else {
  console.error('앱 국가코드 설정 실패: ', result.message);
}
// 국가 선택 화면 구현 예시
async function selectCountry() {
  // 1. 지원하는 국가 목록 조회
  const listResult = await Nachocode.locale.getAppCountryList();
  if (listResult.status !== 'success') {
    console.error('국가 목록 조회 실패: ', listResult.message);
    return;
  }

  // 2. 현재 설정된 국가코드 조회
  const currentResult = await Nachocode.locale.getAppCountryCode();
  const currentCode =
    currentResult.status === 'success' ? currentResult.data : null;

  // 3. 사용자가 선택한 국가로 변경
  const selectedCode = 'USA'; // ex. 사용자가 선택한 국가코드
  if (selectedCode !== currentCode) {
    const setResult = await Nachocode.locale.setAppCountryCode(selectedCode);

    if (setResult.status === 'success') {
      console.log('앱 국가가 변경되었습니다.');
    } else {
      console.error('앱 국가 변경 실패: ', setResult.message);
    }
  }
}