로캘 전환

알파

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

Lingo.dev Compiler는 런타임에 활성 로캘을 읽고 변경할 수 있는 useLingoContext() 훅을 제공합니다. 언어 전환기, 로캘 인식 컴포넌트, 또는 사용자의 언어 설정에 따라 반응하는 UI를 만들 때 활용할 수 있습니다.

useLingoContext() 훅#

이 훅은 현재 로캘과 로캘을 변경하는 함수를 담은 객체를 반환합니다:

tsx

import { useLingoContext } from "@lingo.dev/compiler/react";

const { locale, setLocale } = useLingoContext();

속성	유형	설명
`locale`	`string`	현재 활성화된 로캘 코드입니다(예: `"en"`, `"es"`).
`setLocale`	`(locale: string) => void`	새 로캘을 설정합니다. 기본적으로 지속성 저장과 페이지 새로고침이 함께 수행됩니다.

언어 전환기 예제#

드롭다운 언어 전환기 컴포넌트 예시입니다:

tsx

"use client"; // Required for Next.js App Router

import { useLingoContext } from "@lingo.dev/compiler/react";

const localeLabels: Record<string, string> = {
  en: "English",
  es: "Espanol",
  de: "Deutsch",
  fr: "Francais",
  ja: "日本語",
};

export function LanguageSwitcher() {
  const { locale, setLocale } = useLingoContext();

  return (
    <select value={locale} onChange={(e) => setLocale(e.target.value)}>
      {Object.entries(localeLabels).map(([code, label]) => (
        <option key={code} value={code}>
          {label}
        </option>
      ))}
    </select>
  );
}

Next.js에서는 React 훅을 사용하므로 언어 전환기는 Client Component("use client")여야 합니다.

setLocale 호출 시 일어나는 일#

로캘이 저장됩니다

기본적으로 새 로캘은 locale라는 이름의 쿠키에 최대 1년 동안 저장됩니다. 따라서 페이지를 새로고침하거나 브라우저를 다시 시작해도 설정이 유지됩니다.

페이지가 새로고침됩니다

새 로캘로 모든 컴포넌트를 다시 렌더링하기 위해 페이지가 새로고침됩니다. Server Components는 서버에서 새 로캘의 번역을 가져오고, Client Components는 업데이트된 사전을 전달받습니다.

이후 요청부터 새 로캘이 적용됩니다

다음 페이지 로드부터 compiler가 저장된 로캘을 읽고, 그에 맞는 번역을 제공합니다.

지속성 옵션#

기본 지속성 메커니즘은 쿠키 기반이며, localePersistence를 통해 설정합니다:

{
  localePersistence: {
    type: "cookie",
    config: {
      name: "locale",       // Cookie name
      maxAge: 31536000,     // 1 year in seconds
    },
  },
}

옵션	기본값	설명
`type`	`"cookie"`	지속성 메커니즘입니다.
`config.name`	`"locale"`	쿠키 이름입니다.
`config.maxAge`	`31536000`	쿠키 유지 기간(초)입니다.

커스텀 지속성#

URL 기반 로캘 라우팅, localStorage, 또는 커스텀 헤더 기반 감지를 사용하려면 커스텀 로캘 resolver를 만드세요. 클라이언트 resolver의 persistLocale export는 setLocale가 호출될 때 어떤 동작이 일어날지 제어합니다:

// .lingo/locale-resolver.client.ts
export function resolveLocale(): string {
  return localStorage.getItem("locale") || "en";
}

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

URL 기반, 쿠키 기반, 헤더 기반 패턴의 전체 예시는 Custom Locale Resolvers에서 확인하세요.

전환 없이 로캘 읽기#

전환기를 제공하지 않고 현재 로캘을 표시하거나 조건부 렌더링에 활용해야 한다면, 같은 훅을 사용하면 됩니다:

tsx

"use client";

import { useLingoContext } from "@lingo.dev/compiler/react";

export function LocaleBadge() {
  const { locale } = useLingoContext();
  return <span>{locale.toUpperCase()}</span>;
}

다음 단계#

Custom Locale Resolvers

URL 기반, localStorage, 헤더 기반 지속성

Configuration Reference

localePersistence 옵션

Next.js Integration

Server 및 Client Component 동작

Vite + React

클라이언트 측 로캘 전환

알파