Next.js에서 Langsys 사용하기

패턴은 어디서나 같습니다. 서버가 카탈로그를 한 번 가져오고(쓰기 키는 서버에만 보관), 클라이언트는 그 시드로 읽기 전용 키를 사용해 langsys-js-react를 초기화합니다. 중복 요청은 없습니다. 번역 자체는 브라우저에서 이루어집니다. 서버가 보내는 HTML은 기본 언어로 되어 있고 검색 엔진도 이를 색인하며, 페이지는 로드되면서 방문자의 언어로 전환됩니다.

1 · 서버에서 카탈로그 가져오기

서버 컴포넌트가 raw fetch로 카탈로그를 가져옵니다. 서버에서는 SDK가 필요하지 않습니다. 쓰기 키는 서버에만 보관하고, 클라이언트에는 읽기 전용 키를 제공합니다. 양쪽 모두 같은 카탈로그를 사용하며, 클라이언트는 초기 fetch만 건너뜁니다.

// app/layout.tsx (Server Component)
import type { iCategories } from 'langsys-js-react';
import { LangsysClient } from './LangsysClient';

async function getTranslations(locale: string): Promise<iCategories> {
  const res = await fetch(
    `https://api.langsys.dev/api/projects/${process.env.LANGSYS_PROJECT_ID}/translations?locale=${locale}`,
    { headers: { 'x-Authorization': process.env.LANGSYS_API_KEY! } }
  );
  const result = await res.json();
  return result.data as iCategories;
}

export default async function RootLayout({ children }: { children: React.ReactNode }) {
  const locale = 'en-US'; // from cookie / Accept-Language / route segment
  const translations = await getTranslations(locale);

  return (
    <html lang={locale}>
      <body>
        <LangsysClient
          locale={locale}
          translations={translations}
          projectId={process.env.LANGSYS_PROJECT_ID!}
          apiKey={process.env.NEXT_PUBLIC_LANGSYS_API_KEY!} // read-only
        >
          {children}
        </LangsysClient>
      </body>
    </html>
  );
}

2 · 클라이언트에서 초기화하기

작은 'use client' 래퍼가 시드된 카탈로그로 브라우저에서 SDK를 초기화하므로, 아무것도 가져오지 않고도 시작됩니다. 이 효과가 실행되면 텍스트가 기본 언어에서 방문자의 언어로 전환됩니다.

// app/LangsysClient.tsx
'use client';

import { useEffect, type ReactNode } from 'react';
import { LangsysApp, useLocaleStore, type iCategories } from 'langsys-js-react';

export function LangsysClient(props: {
  locale: string;
  translations: iCategories;
  projectId: string;
  apiKey: string;
  children: ReactNode;
}) {
  const [, , localeStore] = useLocaleStore(props.locale);

  useEffect(() => {
    LangsysApp.init({
      projectid: props.projectId,
      key: props.apiKey,
      UserLocaleStore: localeStore,
      initialTranslations: props.translations,
      initialTranslationsLocale: props.locale,
      ssrTokenStrategy: 'client',
    });
  }, [localeStore, props.projectId, props.apiKey, props.translations, props.locale]);

  return <>{props.children}</>;
}

3 · 아래 어디서나 사용하기

여기서부터는 일반 React SDK와 같습니다. 모든 클라이언트 컴포넌트에서 useT()를 사용하고, 동일한 스토어를 통해 로케일을 전환합니다. 서로 관련 없는 트리마다 새 스토어를 만들지 말고, 앱 전체에서 로케일 스토어를 하나만 유지하세요(init을 호출하는 곳에서 생성). 그리고 setLocale을 하위로 전달하세요.

'use client';
import { useT } from 'langsys-js-react';

export function Hero() {
  const t = useT();
  return <h1>{t('Welcome to our store', 'Home')}</h1>;
}