번역 - Twenty Documentation

Twenty 앱은 영어로 작성됩니다. 소스와 매니페스트의 문자열은 영어 원문이며, en은 번역의 기준이 되는 소스 로케일입니다. 번역되지 않은 로케일은 en을 기본값으로 사용합니다. 앱에는 두 가지 유형의 번역 가능한 텍스트가 있으며, 둘 다 동일한 locales/ 카탈로그를 통해 처리됩니다.

매니페스트 레이블 — 오브젝트와 필드 이름, 뷰 제목, 메뉴 항목 및 앱 메타데이터에 선언된 기타 문자열.
Front-component 문자열 — React 프론트 컴포넌트가 렌더링하는 UI 텍스트입니다.

번역 가능한 문자열에 표시를 하고, 이를 로캘별 카탈로그로 추출한 뒤, 그 카탈로그들을 번역하면, 빌드가 현재 사용자에게 맞는 언어를 제공하므로 별도의 추가 작업이 필요 없습니다.

Front-component 문자열 표시하기

twenty-sdk/front-component에서 번역 헬퍼를 import 하세요:

import { Trans, t, msg, useTranslate } from 'twenty-sdk/front-component';

const STATUSES = [
  { id: 'draft', label: msg('Draft') },
  { id: 'sent', label: msg('Sent') },
];

const Card = ({ count, name }: { count: number; name: string }) => {
  const { t } = useTranslate();

  return (
    <section>
      {/* Static text — reactive to the user's locale */}
      <Trans>Loading postcard…</Trans>

      {/* Disambiguate identical sources with a context */}
      <Trans context="card-title">Untitled</Trans>

      {/* Interpolation: pass values explicitly */}
      <p>{t('Hi {name}', { name })}</p>
      <p>{t('Saved {count} cards', { count })}</p>

      {/* Resolve a lazily-declared descriptor */}
      <ul>{STATUSES.map((s) => <li key={s.id}>{t(s.label)}</li>)}</ul>
    </section>
  );
};

언제 무엇을 사용할지

Trans — JSX 안의 정적 텍스트입니다. 보간을 위해 message 및 values props를 사용하세요 (Trans message="Hi {name}" values={{ name }}); children 안에서 직접 보간하는 것은 정적으로 추출할 수 없습니다.
useTranslate().t — 컴포넌트 내부에서 사용하는 동적 문자열입니다. 사용자가 언어를 전환하면 다시 렌더링됩니다. render 내부에서는 이것을 사용하는 것을 권장합니다.
t(...) (직접 import) — 이벤트 핸들러, 헬퍼, 모듈 스코프 등 render 내부뿐만 아니라 어디서든 사용할 수 있는 즉시 번역 함수입니다.
msg(...) — 데이터(상수, 설정)로 선언된 문자열을 위한 지연 평가용 서술자입니다. 나중에 t(descriptor)로 이를 해석하세요.

컨텍스트

서로 다른 방식으로 번역되는 동일한 소스 문자열을 구분하기 위해 context를 전달하세요:

t({ message: 'Open', context: 'door' });
t({ message: 'Open', context: 'window' });
<Trans context="card-title">Untitled</Trans>

추출 및 번역

앱 디렉터리에서 extract 명령을 실행하세요:

twenty dev:translations-extract                  # collect strings into locales/en.json
twenty dev:translations-extract --locale fr-FR   # also scaffold a target locale

추출 과정에서는 manifest 레이블과 front-component 소스의 t()/msg()/Trans 문자열을 모두 locales/\<locale>.json 파일에 소스 문자열을 키로 하여 수집합니다. 번역을 채워 넣으세요:

// locales/fr-FR.json
{
  "Loading postcard…": "Chargement de la carte…",
  "Hi {name}": "Bonjour {name}",
  "Saved {count} cards": "{count} cartes enregistrées"
}

{name}과 같은 플레이스홀더는 런타임에 치환되므로 — 번역문에도 그대로 유지해야 합니다. 비워 둔 문자열은 소스 텍스트를 그대로 사용합니다.

실행 방식

twenty dev:build는 카탈로그를 컴파일하고 현재 사용자에게 맞는 언어를 제공합니다. manifest 레이블은 서버 측에서 처리되고, front-component 카탈로그는 각 컴포넌트 번들에 내장됩니다. 런타임에는 컴포넌트가 실행 컨텍스트(호스트의 현재 언어)에서 로케일을 읽고, 각 문자열을 해당 카탈로그에서 찾아 해석하며, 번역이 없으면 소스 텍스트로 대체합니다. 호스트에서 언어를 전환하면 Trans와 useTranslate().t 문자열이 실시간으로 다시 렌더링됩니다. 카탈로그는 빌드 시점에 컴파일되므로, 번역을 업데이트하려면 twenty dev:build를 다시 실행하고(및 재배포) 다른 변경 사항과 마찬가지로 처리해야 합니다.

번역은 twenty dev:build(및 twenty apply)에 의해 컴파일됩니다. 연속 실행되는 twenty dev watch에서는 소스 문자열이 표시되므로, 로컬라이즈된 출력을 테스트하려면 일회성 빌드를 수행하세요.

Trans의 텍스트 children은 여러 줄에 걸쳐 있을 수 있으며 — 공백은 JSX에서와 동일한 방식으로 축약되므로, 둘 다 Welcome back 키로 추출됩니다.

<Trans>Welcome back</Trans>
<Trans>
  Welcome
  back
</Trans>

개요

앱

API

셀프 호스팅

기여

번역

Front-component 문자열 표시하기

언제 무엇을 사용할지

컨텍스트

추출 및 번역

실행 방식

​Front-component 문자열 표시하기

​언제 무엇을 사용할지

​컨텍스트

​추출 및 번역

​실행 방식

Front-component 문자열 표시하기

언제 무엇을 사용할지

컨텍스트

추출 및 번역

실행 방식