React API

tyndale-react는 Tyndale 앱에서 사용하는 런타임 provider, 번역 훅, 포맷팅 컴포넌트, 서버 헬퍼를 제공합니다.

Provider와 컨텍스트

TyndaleProvider

일반 React 앱을 위한 루트 provider입니다. 로케일 파일을 로드하고, 번역 상태를 노출하며, 모든 훅과 컴포넌트를 구동합니다.

import { TyndaleProvider } from 'tyndale-react';

export function App() {
  return (
    <TyndaleProvider defaultLocale="en" locale="fr">
      <Routes />
    </TyndaleProvider>
  );
}

Props

• defaultLocale: string
• locale?: string
• basePath?: string — 기본값은 /_tyndale
• initialTranslations?: Record<string, string>
• initialManifest?: Manifest | null
• onLocaleChange?: (locale: string) => void
• children: React.ReactNode

initialTranslations가 생략되면, provider는 브라우저에서 {basePath}/{locale}.json과 manifest.json을 가져옵니다.

TyndaleContext

현재 로케일, manifest, 로드된 번역, 로딩 상태, changeLocale() 함수를 담고 있는 React 컨텍스트입니다.

커스텀 컨텍스트 접근이 필요한 경우에만 직접 사용하세요. 대부분의 앱은 아래 훅을 사용하는 것이 좋습니다.

useTyndaleContext()

TyndaleContext를 읽고, provider가 마운트되지 않은 경우 예외를 발생시킵니다.

import { useTyndaleContext } from 'tyndale-react';

function LocaleBadge() {
  const { locale, defaultLocale, isLoading } = useTyndaleContext();
  return <span>{isLoading ? 'Loading…' : `${locale} / ${defaultLocale}`}</span>;
}

핵심 훅

useTranslation()

보간(interpolation)을 지원하는 번역 함수를 반환합니다.

import { useTranslation } from 'tyndale-react';

function Greeting({ name }: { name: string }) {
  const t = useTranslation();
  return <p>{t('Hello, {name}!', { name })}</p>;
}

시그니처:

(source: string, vars?: Record<string, string | number>) => string

useLocale()

현재 로케일 문자열을 반환합니다.

import { useLocale } from 'tyndale-react';

const locale = useLocale();

provider 밖에서 호출하면 빈 문자열을 반환하고, 개발 환경에서는 경고를 로그로 남깁니다.

useChangeLocale()

활성 로케일을 변경하는 함수를 반환합니다.

import { useChangeLocale } from 'tyndale-react';

function LocaleSwitcher() {
  const changeLocale = useChangeLocale();

  return <button onClick={() => changeLocale('es')}>Español</button>;
}

일반 React에서는 새 로케일 JSON을 가져와 provider 상태를 업데이트합니다. 반면 tyndale-next에서는 같은 훅이 라우트 변경을 트리거합니다.

useDictionary(filenameKey)

딕셔너리 파일의 엔트리를 일반 객체로 반환합니다.

import { useDictionary } from 'tyndale-react';

function Nav() {
  const labels = useDictionary('common');
  return <a href="/docs">{labels.docs}</a>;
}

시그니처:

(filenameKey: string) => Record<string, string>

이 훅은 type: 'dictionary'인 manifest 엔트리를 조회하고, 번역이 없으면 딕셔너리 키로 대체합니다.

서버 헬퍼

getTranslation(options)

디스크에서 로케일 파일을 로드하고 번역 함수를 반환하는 비동기 서버 헬퍼입니다.

tyndale-react와 서버 전용 서브패스 양쪽에서 사용할 수 있습니다:

import { getTranslation } from 'tyndale-react/server';

const t = await getTranslation({
  locale: 'fr',
  defaultLocale: 'en',
  outputPath: 'public/_tyndale',
});

const title = t('Welcome, {name}!', { name: 'Ada' });

옵션:

• locale: string
• defaultLocale?: string
• outputPath: string

locale === defaultLocale이면 파일 로딩을 건너뛰고, 보간이 적용된 원본 문자열을 반환합니다.

메시지 마커

msg(source)

컴포넌트 렌더 외부에서 추출을 위해 리터럴 문자열을 표시하고, 렌더 시점에 해석되는 React 엘리먼트를 반환합니다.

import { msg } from 'tyndale-react';

const nav = [{ href: '/', label: msg('Home') }];

msgString(source)

추출을 위해 리터럴 문자열을 표시하고, React 엘리먼트 대신 일반 문자열을 반환합니다.

import { msgString } from 'tyndale-react';

export const copy = {
  docs: msgString('Documentation'),
};

일반 TypeScript 모듈, Astro frontmatter, 서버 유틸리티 같은 non-React 컨텍스트에서는 msgString()을 사용하세요.

번역 및 포맷팅 컴포넌트

<T>

자식 요소를 직렬화하고, 번역된 wire format을 조회한 뒤, 번역 결과를 렌더링하여 JSX 콘텐츠를 번역합니다.

import { T, Var } from 'tyndale-react';

<T>
  Hello, <Var name="name">{name}</Var>!
</T>

번역이 없으면 원본 자식 요소를 렌더링합니다.

<Var>

<T> 내부의 동적 값을 표시합니다.

import { T, Var } from 'tyndale-react';

<T>
  Hello, <Var name="name">{name}</Var>!
</T>

<Num>

Intl.NumberFormat으로 숫자를 포맷합니다. <T> 내부에서는 이름 있는 플레이스홀더 역할도 합니다.

import { T, Num } from 'tyndale-react';

<T>
  You have <Num name="count" value={count} /> unread messages.
</T>

<Currency>

활성 로케일로 통화를 포맷합니다.

import { Currency } from 'tyndale-react';

<Currency value={49.99} currency="USD" />

<DateTime>

Intl.DateTimeFormat으로 날짜 또는 타임스탬프를 포맷합니다.

import { DateTime } from 'tyndale-react';

<DateTime value={new Date()} options={{ dateStyle: 'long' }} />

<Plural>

활성 로케일에 맞는 올바른 복수형 분기를 선택합니다. <T> 내부에서는 ICU 복수형 문법으로 직렬화됩니다.

import { Plural } from 'tyndale-react';

<Plural count={count} one="1 item" other="{count} items" />

고급 헬퍼

이들은 공개 export이지만, 추출 결과물이나 wire-format 내부와 통합하는 경우가 아니라면 대부분의 앱에서는 필요하지 않습니다.

computeHash(content) / hash(content)

Tyndale가 번역 조회에 사용하는 정규화된 SHA-256 해시를 계산합니다.

import { computeHash } from 'tyndale-react';

const id = computeHash('Welcome to our app.');

escapeWireFormat(text) / unescapeWireFormat(text)

Tyndale wire format용 리터럴 텍스트를 이스케이프하거나 복원합니다.

serializeChildren(children) / deserializeWireFormat(...)

React 자식 요소를 Tyndale wire format으로 변환하고 다시 되돌립니다.

parseIcuPlural(input)

ICU 복수형 블록을 변수 이름과 분기로 파싱합니다.

Tyndale의 직렬화된 번역 포맷을 중심으로 도구를 만들거나 고급 런타임 통합을 구성할 때만 사용하세요.