github-actions[bot]
15c0c3b773
Created by Github action <!-- This is an auto-generated description by cubic. --> <a href="https://cubic.dev/pr/twentyhq/twenty/pull/22413?utm_source=github" target="_blank" rel="noopener noreferrer" data-no-image-dialog="true"><picture><source media="(prefers-color-scheme: dark)" srcset="https://www.cubic.dev/buttons/review-in-cubic-dark.svg"><source media="(prefers-color-scheme: light)" srcset="https://www.cubic.dev/buttons/review-in-cubic-light.svg"><img alt="Review in cubic" src="https://www.cubic.dev/buttons/review-in-cubic-dark.svg"></picture></a> <!-- End of auto-generated description by cubic. --> Co-authored-by: github-actions <github-actions@twenty.com>
112 lines
5.3 KiB
Plaintext
112 lines
5.3 KiB
Plaintext
---
|
|
title: 번역
|
|
description: 여러 언어로 앱을 출시하세요 — 단일 로케일 카탈로그에서 매니페스트 레이블과 UI 문자열을 번역하세요.
|
|
icon: language
|
|
---
|
|
|
|
Twenty 앱은 **영어**로 작성됩니다. 소스와 매니페스트의 문자열은 영어 원문이며, `en`은 번역의 기준이 되는 소스 로케일입니다. 번역되지 않은 로케일은 `en`을 기본값으로 사용합니다.
|
|
|
|
앱에는 두 가지 유형의 번역 가능한 텍스트가 있으며, 둘 다 동일한 `locales/` 카탈로그를 통해 처리됩니다.
|
|
|
|
* **매니페스트 레이블** — 오브젝트와 필드 이름, 뷰 제목, 메뉴 항목 및 앱 메타데이터에 선언된 기타 문자열.
|
|
* **Front-component 문자열** — React 프론트 컴포넌트가 렌더링하는 UI 텍스트입니다.
|
|
|
|
번역 가능한 문자열에 표시를 하고, 이를 로캘별 카탈로그로 추출한 뒤,
|
|
그 카탈로그들을 번역하면, 빌드가 현재 사용자에게 맞는 언어를 제공하므로
|
|
별도의 추가 작업이 필요 없습니다.
|
|
|
|
## Front-component 문자열 표시하기
|
|
|
|
`twenty-sdk/front-component`에서 번역 헬퍼를 import 하세요:
|
|
|
|
```tsx
|
|
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
|
|
t({ message: 'Open', context: 'door' });
|
|
t({ message: 'Open', context: 'window' });
|
|
<Trans context="card-title">Untitled</Trans>
|
|
```
|
|
|
|
## 추출 및 번역
|
|
|
|
앱 디렉터리에서 extract 명령을 실행하세요:
|
|
|
|
```bash
|
|
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
|
|
// 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`이 됩니다.
|