본문으로 건너뛰기

getLocale

사용자의 로케일 정보를 동기적으로 반환합니다. 네이티브 모듈에서 로케일 정보를 가져올 수 없는 경우 기본값으로 'ko-KR'을 반환합니다. 앱 현지화, 날짜/통화 포맷, 언어 분기 로직에 활용하세요.

시그니처​

import { getLocale } from '@apps-in-toss/web-framework';

declare function getLocale(): string;

파라미터​

없음.

반환값​

  • string — BCP 47 형식의 로케일 태그 (예: 'ko-KR', 'en-US'). 네이티브에서 읽을 수 없는 경우 'ko-KR'을 반환합니다.

권한​

권한이 필요하지 않습니다 — getLocale은 별도의 PermissionName에 바인딩되지 않습니다. 권한이 필요한 다른 네임스페이스의 일반적인 처리 흐름은 Guides — 권한 처리 패턴을 참고하세요.

예제​

최소 예제​

import { getLocale } from '@apps-in-toss/web-framework';

const locale = getLocale();
console.log('사용자 로케일:', locale); // 예: 'ko-KR'

실전 예제 — 로케일에 따른 날짜 포맷 분기​

import { getLocale } from '@apps-in-toss/web-framework';
import { useState, useEffect } from 'react';

function LocalizedDatePage() {
  const [formattedDate, setFormattedDate] = useState('');

  useEffect(() => {
    const locale = getLocale();
    const now = new Date();

    const formatted = new Intl.DateTimeFormat(locale, {
      year: 'numeric',
      month: 'long',
      day: 'numeric',
    }).format(now);

    setFormattedDate(formatted);
  }, []);

  return (
    <div>
      <p>오늘 날짜 (로케일 포맷): {formattedDate}</p>
    </div>
  );
}

직접 실행해 보기​

sdk-example의 Environment 페이지에서 getLocale 카드를 실행해 결과를 확인할 수 있습니다.

sdk-example에서 실행해 보기

관련 API​

관련 가이드​

외부 참조​

  • @apps-in-toss/web-framework — 상위 SDK 패키지. 실제 export는 내부적으로 @apps-in-toss/web-bridge에서 가져옵니다.
  • 표준 Web API 대응: navigator.language — 비슷한 역할을 하지만, 브라우저의 언어 설정을 반환하며 미니앱 런타임의 네이티브 로케일 값과 다를 수 있습니다. 미니앱 환경에서는 getLocale()이 더 신뢰할 수 있는 값을 제공합니다.