사용자 지정 로캘 리졸버

알파

Lingo.dev Compiler는 현재 알파 단계입니다. 아직 안정적이지 않아 프로덕션 환경에서는 권장되지 않으며, 릴리스마다 API가 변경될 수 있습니다.

사용자 지정 로캘 리졸버를 사용하면 Lingo.dev Compiler가 사용자의 로캘을 감지하고 유지하는 방식을 재정의할 수 있습니다. 기본적으로 Compiler는 localePersistence 옵션으로 설정된 쿠키 기반 유지 방식을 사용합니다. URL 기반 라우팅, 헤더 감지, localStorage 또는 그 외 사용자 지정 로직까지 더 세밀하게 제어하려면 .lingo/ 디렉터리에 리졸버 파일을 추가하세요.

리졸버 파일#

Compiler는 다음 두 개의 선택적 파일을 확인합니다:

파일	환경	내보내기
`.lingo/locale-resolver.server.ts`	서버 측(SSR, RSC)	`resolveLocale(request: Request): string`
`.lingo/locale-resolver.client.ts`	클라이언트 측(브라우저)	`resolveLocale(): string` 및 `persistLocale(locale: string): void`

리졸버 파일이 있으면 Compiler는 기본 쿠키 기반 동작 대신 해당 파일을 사용합니다. 한쪽 파일만 있으면 다른 환경에서는 기본 동작으로 대체됩니다.

서버 측 리졸버#

서버 리졸버는 들어오는 Request 객체를 받아 로캘 코드 문자열을 반환합니다:

// .lingo/locale-resolver.server.ts

export function resolveLocale(request: Request): string {
  const url = new URL(request.url);

  // Check URL path prefix: /es/about -> "es"
  const pathLocale = url.pathname.split("/")[1];
  const supportedLocales = ["en", "es", "de", "fr", "ja"];

  if (supportedLocales.includes(pathLocale)) {
    return pathLocale;
  }

  // Fall back to Accept-Language header
  const acceptLanguage = request.headers.get("Accept-Language");
  if (acceptLanguage) {
    const preferred = acceptLanguage.split(",")[0].split("-")[0];
    if (supportedLocales.includes(preferred)) {
      return preferred;
    }
  }

  return "en";
}

클라이언트 측 리졸버#

클라이언트 리졸버에는 두 가지 함수가 있습니다. 하나는 현재 로캘을 읽고, 다른 하나는 로캘 변경 사항을 유지합니다:

// .lingo/locale-resolver.client.ts

export function resolveLocale(): string {
  // Check URL path prefix
  const pathLocale = window.location.pathname.split("/")[1];
  const supportedLocales = ["en", "es", "de", "fr", "ja"];

  if (supportedLocales.includes(pathLocale)) {
    return pathLocale;
  }

  // Fall back to localStorage
  const stored = localStorage.getItem("locale");
  if (stored && supportedLocales.includes(stored)) {
    return stored;
  }

  return "en";
}

export function persistLocale(locale: string): void {
  localStorage.setItem("locale", locale);

  // Navigate to the locale-prefixed URL
  const path = window.location.pathname.replace(/^\/[a-z]{2}/, "");
  window.location.href = `/${locale}${path}`;
}

자주 쓰는 리졸버 패턴#

URL 경로 접두사(/es/about, /de/pricing)를 기준으로 라우팅:

// .lingo/locale-resolver.server.ts
export function resolveLocale(request: Request): string {
  const url = new URL(request.url);
  const locale = url.pathname.split("/")[1];
  const supported = ["en", "es", "de", "fr"];
  return supported.includes(locale) ? locale : "en";
}

// .lingo/locale-resolver.client.ts
export function resolveLocale(): string {
  const locale = window.location.pathname.split("/")[1];
  const supported = ["en", "es", "de", "fr"];
  return supported.includes(locale) ? locale : "en";
}

export function persistLocale(locale: string): void {
  const path = window.location.pathname.replace(/^\/[a-z]{2}/, "");
  window.location.href = `/${locale}${path}`;
}

resolveLocale 함수는 설정된 targetLocales 또는 sourceLocale 중 하나와 일치하는 로캘 코드를 반환해야 합니다. 지원되지 않는 로캘 코드를 반환하면 Compiler는 소스 로캘로 폴백합니다.

다음 단계#

Next.js에서 서버 측 로캘 결정하기

알파