> ## Documentation Index
> Fetch the complete documentation index at: https://twenty-c--pull-3-cli.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 翻訳

> 複数の言語でアプリを提供できます — 単一の locales カタログで、マニフェストのラベルと UI 文字列を翻訳します。

Twenty のアプリは **英語** で作成されています。ソースやマニフェスト内の文字列は英語のソーステキストであり、`en` は翻訳の元となるソースロケールです。未翻訳のロケールは `en` にフォールバックします。

アプリには 2 種類の翻訳可能なテキストがあり、どちらも同じ `locales/` カタログを通じて処理されます。

* **Manifest labels** — オブジェクト名とフィールド名、ビュータイトル、メニュー項目、その他アプリのメタデータで宣言される文字列。
* **Front-component strings** — React のフロントコンポーネントがレンダリングするUIテキスト。

翻訳可能な文字列にマークを付けてロケールごとのカタログに抽出し、それらのカタログを翻訳すれば、ビルドが現在のユーザーに適切な言語を提供します — 追加の設定は不要です。

## フロントコンポーネント文字列のマーク

`20-sdk/front-component` から翻訳ヘルパーをインポートします。

```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>
  );
};
```

### When to use which

* **`Trans`** — JSX 内の静的テキストです。 補間には `message` と `values` の props を使用します。
  例: `Trans message="Hi {name}" values={{ name }}` のようにします。
  子要素内で直接補間すると、静的に抽出できません。
* **`useTranslate().t`** — コンポーネント内の動的文字列。
  ユーザーが言語を切り替えたときに再レンダリングします。 これをレンダリング内で好みます。
* **`t(...)`** (imported directly) — eager translation used **anywhere** ,
  including event handlers, helpers, module scope — だけでなく、render内だけでなく。
* **`msg(...)`** — dataとして宣言された文字列の遅延記述子 (定数、
  config)。 後で`t(descriptor)`で解決します。

### コンテキスト

異なる変換元文字列を曖昧にするために `context` を渡します。

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

コンテキスト付きの文字列は、ロケールカタログ内ではそのコンテキストをキーとしたグループとして表示されます:
`"\<context>": { "\<message>": "\<translation>" }`。 マニフェストのラベルは、設計上コンテキスト付きになっています — それぞれが果たすメタデータ上の役割（`objectMetadata.labelSingular`、`fieldMetadata.label`、`view.name` など）を保持しているため、同じ語でもオブジェクト名として訳す場合とビュー名として訳す場合で、異なる訳語になる可能性があります。

## 抽出と翻訳

アプリディレクトリから抽出コマンドを実行します。

```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
```

抽出処理では、マニフェストのラベルとフロントコンポーネントのソース内にある `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",
  "door": {
    "Open": "Ouvrir"
  },
  "objectMetadata.labelSingular": {
    "Postcard": "Carte postale"
  }
}
```

コンテキストに依存しない文字列はフラットなエントリです。コンテキスト付きの文字列（すべての
マニフェストラベルを含む）は、そのコンテキストキーの下にネストされます。

`{name}`のようなプレースホルダは、実行時に置き換えられます —
翻訳でそれらを維持します。 空の文字列はすべて元のテキストに戻ります。

## 動作方法

`twenty dev:build` はカタログをコンパイルし、現在のユーザーに対して適切な言語を提供します。マニフェストのラベルはサーバー側で解決され、フロントコンポーネントのカタログは各コンポーネントバンドルに組み込まれます。 実行時には、コンポーネントが実行コンテキスト（ホストの現在の言語）からロケールを読み取り、そのカタログに対して各文字列を解決し、翻訳が存在しない場合はソースにフォールバックします。 ホスト側で言語を切り替えると、`Trans` と
`useTranslate().t` の文字列が即時に再レンダリングされます。

マニフェストラベルは、すべての同期時にコンパイルされます。`twenty dev:build`、`twenty apply`
および継続的な `twenty dev` の監視も同様です。そのため、ロケールファイルを編集して
同期するだけで、新しいテキストを確認できます。 フロントコンポーネントカタログはビルド時に
各コンポーネントバンドルに組み込まれるため、それらのいずれかを変更した場合も
`twenty dev:build` の再実行（および再デプロイ）が必要です。

`Trans` のテキスト子要素は複数行にまたがってもかまいません — 空白は JSX と同じように折りたたまれるため、どちらもキー `Welcome back` として抽出されます:

```tsx theme={null}
<Trans>Welcome back</Trans>
<Trans>
  Welcome
  back
</Trans>
```