> ## Documentation Index
> Fetch the complete documentation index at: https://docs.twenty.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 번역

> 여러 언어로 앱을 출시하세요 — 단일 로케일 카탈로그에서 매니페스트 레이블과 UI 문자열을 번역하세요.

Twenty 앱은 **영어**로 작성됩니다. 소스와 매니페스트의 문자열은 영어 원문이며, `en`은 번역의 기준이 되는 소스 로케일입니다. 번역되지 않은 로케일은 `en`을 기본값으로 사용합니다.

앱에는 두 가지 유형의 번역 가능한 텍스트가 있으며, 둘 다 동일한 `locales/` 카탈로그를 통해 처리됩니다.

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

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

## Front-component 문자열 표시하기

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

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

### 컨텍스트

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

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

## 추출 및 번역

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

```bash theme={null}
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` 파일에 소스 문자열을 키로 하여 수집합니다. 번역을 채워 넣으세요:

```json theme={null}
// 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`를 다시 실행하고(및 재배포) 다른 변경 사항과 마찬가지로 처리해야 합니다.

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

`<Trans>`의 텍스트 children은 여러 줄에 걸쳐 있을 수 있으며 — 공백은 JSX에서와 동일한 방식으로
축약되므로, `<Trans>Welcome\n  back</Trans>`과 추출된 key는 모두 `Welcome back`이 됩니다.