snapshot of https://github.com/twentyhq/twenty.git (main, 2026-09-17; blobs > 131072B omitted)

packages/twenty-docs/l/ja/developers/extend/apps/operations/cli.mdx

@@ -0,0 +1,131 @@
+---
+title: CLI
+description: 関数の実行、ログのストリーミング、アプリのインストール管理、リモートの切り替えを行う yarn twenty のコマンド。
+icon: terminal
+---
+
+`yarn twenty` CLI は、アプリ関連のすべてを操作するためのインターフェースです。 コマンド一覧:
+
+| コマンド                                            | 機能                                                             | 参照ドキュメント                                                                                           |
+| ----------------------------------------------- | -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| `dev`                                           | ソースファイルを監視し、変更をライブ同期します                                        | [クイックスタート](/l/ja/developers/extend/apps/getting-started/quick-start)                                    |
+| `plan`                                          | メタデータの変更を適用せずにプレビュー                                            | [Syncing & recovery](/l/ja/developers/extend/apps/operations/sync-and-recovery#previewing-changes-plan) |
+| `apply`                                         | プランを表示した後にメタデータの変更を適用                                          | [Syncing & recovery](/l/ja/developers/extend/apps/operations/sync-and-recovery)                         |
+| `dev:build`                                     | アプリをコンパイルし、API クライアントを生成します（`.tgz` にパッケージするには `--tarball` を使用） | [公開](/l/ja/developers/extend/apps/operations/publishing)                                                |
+| `dev:typecheck`                                 | TypeScript の型チェックを実行                                           | [テスト](/l/ja/developers/extend/apps/operations/testing)                                                  |
+| `dev:add`                                       | 新しいエンティティのスキャフォールドを作成                                          | [スキャフォールディング](/l/ja/developers/extend/apps/getting-started/scaffolding)                                 |
+| `dev:generate-client`                           | 型付き API クライアントを再生成                                             | このページ                                                                                              |
+| `dev:function:exec` / `dev:function:logs`       | 関数を実行し、そのログをストリーミング                                            | このページ                                                                                              |
+| `dev:translations-extract`                      | 翻訳可能な文字列を `locales/` カタログに抽出                                   | [翻訳](/l/ja/developers/extend/apps/operations/translations)                                                |
+| `dev:catalog-sync`                              | マーケットプレイスのカタログ同期をトリガー                                          | [公開](/l/ja/developers/extend/apps/operations/publishing#how-marketplace-discovery-works)                |
+| `app:publish` / `app:install` / `app:uninstall` | リリースライフサイクル                                                    | [公開](/l/ja/developers/extend/apps/operations/publishing) とこのページ                                         |
+| `docker:*`                                      | ローカルの Twenty サーバーコンテナを管理                                       | [ローカルサーバー](/l/ja/developers/extend/apps/getting-started/local-server)                                   |
+| `remote:*`                                      | サーバー接続を管理                                                      | このページ                                                                                              |
+
+すべてのコマンドは、デフォルトではない特定のリモートを対象にするために `-r, --remote \<name>` を受け付けます。
+
+## 関数の実行（`yarn twenty dev:function:exec`）
+
+HTTP、cron、データベースイベントを介さずに、ロジック関数を手動で実行します：
+
+```bash filename="Terminal"
+# Execute by function name
+yarn twenty dev:function:exec -n create-new-post-card
+
+# Execute by universalIdentifier
+yarn twenty dev:function:exec -u e56d363b-0bdc-4d8a-a393-6f0d1c75bdcf
+
+# Pass a JSON payload
+yarn twenty dev:function:exec -n create-new-post-card -p '{"name": "Hello"}'
+
+# Execute the install and uninstall hooks
+yarn twenty dev:function:exec --postInstall
+yarn twenty dev:function:exec --preInstall
+yarn twenty dev:function:exec --uninstall
+```
+
+## 関数ログの表示（`yarn twenty dev:function:logs`）
+
+アプリのロジック関数の実行ログをストリーミング表示します：
+
+```bash filename="Terminal"
+# Stream all function logs
+yarn twenty dev:function:logs
+
+# Filter by function name
+yarn twenty dev:function:logs -n create-new-post-card
+
+# Filter by universalIdentifier
+yarn twenty dev:function:logs -u e56d363b-0bdc-4d8a-a393-6f0d1c75bdcf
+```
+
+<Note>
+これは Docker コンテナのログを表示する `yarn twenty docker:logs` とは異なります。 `yarn twenty dev:function:logs` は、Twenty サーバーからアプリの関数実行ログを表示します。
+</Note>
+
+## 型付きクライアントを生成する（`yarn twenty dev:generate-client`）
+
+アプリをビルドしたり同期したりすることなく、アクティブなリモートのスキーマから型付き API クライアント（`twenty-client-sdk`）を再生成します。 これを使用すると、別リポジトリにあるバックエンドサービスのような、Twenty インスタンスと通信する任意のプロジェクトで型付きクライアントを取得できます：
+
+```bash filename="Terminal"
+# In your project (no Twenty app definition required)
+yarn add twenty-sdk twenty-client-sdk
+
+# Connect to the Twenty instance to generate the client from
+yarn twenty remote:add
+
+# Generate the typed client into node_modules/twenty-client-sdk
+yarn twenty dev:generate-client
+```
+
+次に、クライアントをコードでインポートします：
+
+```typescript
+import { CoreApiClient } from 'twenty-client-sdk/core';
+```
+
+データモデルが変更されるたびにコマンドを再実行して、生成された型を更新してください。
+
+<Note>
+クライアントは `node_modules` 内に生成されるため、コードと一緒にはコミットされません。 インストールのたびに（たとえば `postinstall` スクリプトや CI で）`yarn twenty dev:generate-client` を実行してください。
+</Note>
+
+## アプリのアンインストール（`yarn twenty app:uninstall`）
+
+アクティブなワークスペースからアプリを削除します：
+
+```bash filename="Terminal"
+yarn twenty app:uninstall
+
+# Skip the confirmation prompt
+yarn twenty app:uninstall --yes
+```
+
+## リモートの管理
+
+**remote** とは、アプリが接続する Twenty サーバーのことです。 セットアップ中に、スキャフォルダーが自動的にリモートを作成します。 リモートはいつでも追加や切り替えができます。
+
+```bash filename="Terminal"
+# Add a new remote (opens a browser for OAuth login)
+yarn twenty remote:add
+
+# Connect to a local Twenty server (auto-detects port 2020 or 3000)
+yarn twenty remote:add --local
+
+# Add a remote non-interactively (useful for CI)
+yarn twenty remote:add --url https://your-twenty-server.com --api-key $TWENTY_API_KEY --as my-remote
+
+# List all configured remotes
+yarn twenty remote:list
+
+# Set the active remote
+yarn twenty remote:use <name>
+
+# Check that the active remote's authentication is still valid
+yarn twenty remote:status
+
+# Remove a remote
+yarn twenty remote:remove <name>
+```
+
+認証情報は `~/.twenty/config.json` に保存されます。

packages/twenty-docs/l/ja/developers/extend/apps/operations/overview.mdx

@@ -0,0 +1,32 @@
+---
+title: 概要
+description: アプリのビルド、テスト、リリース — CLI コマンド、統合テスト、CI、サーバーまたは npm への公開。
+icon: rocket
+---
+
+**オペレーションレイヤー** とは、アプリを使って *何かをする* のではなく、アプリに対して *行う* あらゆる操作を指します。具体的には、CLI コマンドの実行、実際の Twenty サーバーに対する統合テストの実行、CI の設定、そしてリリースの提供です — 単一サーバーにデプロイする tarball として、またはマーケットプレイスに掲載される npm パッケージとして行われます。
+
+```text
+   develop ─▶ test ─▶ build ─▶ deploy / publish
+   ───────    ────    ─────    ─────────────────
+   yarn       yarn    yarn     yarn twenty app:publish --private  (tarball → one server)
+   twenty     test    twenty
+   dev                dev:build    yarn twenty app:publish         (npm → marketplace)
+```
+
+## このセクションについて
+
+<CardGroup cols={2}>
+  <Card title="CLI" icon="terminal" href="/l/ja/developers/extend/apps/operations/cli">
+    `yarn twenty` リファレンス — exec、logs、uninstall、remotes。
+  </Card>
+  <Card title="同期と復旧" icon="compass" href="/l/ja/developers/extend/apps/operations/sync-and-recovery">
+    どのコマンドをいつ使うか、同期の差分の読み方、そして復旧の手順。
+  </Card>
+  <Card title="テスト" icon="flask" href="/l/ja/developers/extend/apps/operations/testing">
+    Vitest のセットアップ、統合テスト、型チェック、CI ワークフロー。
+  </Card>
+  <Card title="公開" icon="upload" href="/l/ja/developers/extend/apps/operations/publishing">
+    ビルド、tarball のデプロイ、npm への公開、インストール。
+  </Card>
+</CardGroup>

packages/twenty-docs/l/ja/developers/extend/apps/operations/publishing.mdx

@@ -0,0 +1,293 @@
+---
+title: 公開
+icon: upload
+description: Twenty アプリをマーケットプレイスに公開するか、社内向けにデプロイします。
+---
+
+## 概要
+
+[ローカルでビルドとテストが完了](/l/ja/developers/extend/apps/getting-started/concepts)したら、配布方法は次の2通りです:
+
+* **tarball をデプロイ** — 内部またはプライベート用途のために、特定の Twenty サーバーにアプリを直接アップロードします。
+* **npm に公開** — Twenty マーケットプレイスにアプリを掲載し、任意のワークスペースが見つけてインストールできるようにします。
+
+どちらの方法も同じ**ビルド**手順から始まります。
+
+## アプリのビルド
+
+build コマンドを実行してアプリをコンパイルし、配布可能な `manifest.json` を生成します:
+
+```bash filename="Terminal"
+yarn twenty dev:build
+```
+
+これにより、TypeScript ソースがコンパイルされ、ロジック関数とフロントエンドコンポーネントがトランスパイルされ、すべてが `.twenty/output/` に書き込まれます。 手動配布または公開コマンド用の `.tgz` パッケージも生成するには、`--tarball` を追加します。
+
+## サーバーへのデプロイ（tarball）
+
+一般公開したくないアプリ（プロプライエタリなツール、エンタープライズ専用の連携、実験的ビルドなど）の場合は、tarball を Twenty サーバーに直接デプロイできます。
+
+### 前提条件
+
+デプロイ前に、対象サーバーを指すリモートを設定しておく必要があります。 リモートは、サーバーの URL と認証情報をローカルの `~/.twenty/config.json` に保存します。
+
+リモートを追加:
+
+```bash filename="Terminal"
+yarn twenty remote:add --url https://your-twenty-server.com --as production
+```
+
+### デプロイ
+
+アプリをビルドしてサーバーにアップロードするまでを1ステップで実行します:
+
+```bash filename="Terminal"
+yarn twenty app:publish --private
+# To deploy to a specific remote:
+# yarn twenty app:publish --private --remote production
+```
+
+### デプロイ済みアプリの共有
+
+tarball アプリは公開マーケットプレイスには掲載されないため、同じサーバー上の他のワークスペースは、ブラウズしてもそれらを見つけられません。 デプロイ済みアプリを共有するには:
+
+1. **設定 > アプリケーション > 登録** に移動して、あなたのアプリを開きます
+2. **Distribution** タブで、**Copy share link** をクリックします
+3. このリンクを他のワークスペースのユーザーと共有すると、アプリのインストールページに直接移動できます。
+
+共有リンクはサーバーのベース URL（ワークスペースのサブドメインなし）を使用するため、サーバー上のどのワークスペースでも機能します。
+
+### バージョン管理
+
+既にデプロイ済みの tarball アプリを更新する場合、サーバーは、`package.json` の `version` が、現在デプロイされているバージョンよりも **厳密に大きい** ([semver](https://semver.org) の順序に従って) ことを要求します。 同じバージョンを再デプロイする、またはそれより低いバージョンをプッシュする操作は、tarball が保存される前に拒否されます—CLI から `VERSION_ALREADY_EXISTS` エラーが表示されます。
+
+アップデートをリリースするには:
+
+1. `package.json` の `version` フィールドを更新してください（例：`1.2.3` → `1.2.4`、`1.3.0`、または `2.0.0`）
+2. `yarn twenty app:publish --private`（または `yarn twenty app:publish --private --remote production`）を実行します。
+3. アプリがインストールされ、「Settings」タブで自動アップグレードが有効になっているワークスペースは、バックグラウンドで自動的にアップグレードされます。それ以外のワークスペースでは、設定内で利用可能なアップグレードが表示されます。
+
+<Note>
+プレリリースタグは期待どおりに動作します。`1.0.0-rc.1` → `1.0.0-rc.2` への引き上げは許可され、`1.0.0` のような最終リリースは `1.0.0-rc.5` よりも高いバージョンとして正しく認識されます。 `package.json` のバージョンは、それ自体が有効な semver 文字列でなければなりません。
+</Note>
+
+{/* TODO: add screenshot of the Upgrade button */}
+
+### サーバーバージョンの互換性
+
+特定の Twenty サーバーバージョンで導入された機能（例: v2.3.0 で追加された OAuth プロバイダー）をアプリで使用している場合、`package.json` の `engines.twenty` フィールドを使用して、アプリが必要とする最小サーバーバージョンを宣言してください:
+
+```json filename="package.json"
+{
+  "name": "twenty-my-app",
+  "version": "1.0.0",
+  "engines": {
+    "node": "^24.5.0",
+    "twenty": ">=2.3.0"
+  }
+}
+```
+
+値は標準的な [SemVer の範囲](https://github.com/npm/node-semver#ranges) です。 よくあるパターン:
+
+| 範囲                                 | 意味                                     |
+| ---------------------------------- | -------------------------------------- |
+| `>=2.3.0`                          | 2.3.0 以降のどのサーバーでも                      |
+| `>=2.3.0 \<3.0.0` | 2.3.0 以上（次のメジャーバージョン未満）                |
+| `^2.3.0`                           | `>=2.3.0 \<3.0.0` と同じ |
+
+**デプロイ時とインストール時に起こること:**
+
+* `engines.twenty` が設定されていて、ターゲットサーバーのバージョンがその範囲を満たさない場合、デプロイ（tarball のアップロード）またはインストールは `SERVER_VERSION_INCOMPATIBLE` エラーと、要求される範囲と実際のサーバーバージョンの双方を示すメッセージとともに拒否されます。
+* `engines.twenty` が**未設定**の場合、アプリはどのサーバーバージョンでも受け入れられます（既存のアプリとの後方互換性）。
+* サーバーで `APP_VERSION` が設定されていない場合、このチェックはスキップされます。
+
+<Note>
+サーバーが最終的な判定を行い、tarball のアップロードとワークスペースへのインストールの両方で `engines.twenty` を検証します。 tarball を別経路でデプロイする場合やマーケットプレイスからインストールする場合でも、サーバーは互換性を引き続き強制します。
+</Note>
+
+## 自動化された CI/CD（スキャフォールド済みのワークフロー）
+
+`create-twenty-app` で生成されたアプリには、`.github/workflows/` 配下に GitHub Actions のワークフローが 3 つ、最初から同梱されています。 CI はセットアップ不要で実行でき、CD には 1 つのシークレットを設定するだけでよく、npm への公開には 1 回だけの npm trusted-publisher セットアップが必要です。
+
+### CI — `ci.yml`
+
+`main` へのプッシュやプルリクエストのたびに、統合テストを自動実行します。
+
+**機能:**
+
+1. アプリのソースをチェックアウトします。
+2. `twentyhq/twenty/.github/actions/spawn-twenty-app-dev-test@main` 複合アクションを使って、分離された Twenty のテスト用インスタンスを起動します（`yarn twenty docker:start --test` の CI 版）。
+3. Corepack を有効化し、`.nvmrc` に基づいて Node.js をセットアップし、`yarn install --immutable` で依存関係をインストールします。
+4. `yarn test` を実行し、起動したインスタンスから `TWENTY_API_URL` と `TWENTY_API_KEY` を渡すことで、テストが実サーバーと通信できるようにします。
+
+**設定項目:**
+
+* `TWENTY_VERSION`（env、デフォルトは `latest`）— `ci.yml` でこれを編集して、CI で使用する Twenty サーバーのバージョンを固定します。
+* 同時実行は `github.ref` 単位でグループ化され、新しいプッシュ時に進行中の実行をキャンセルします。
+
+シークレットは不要です。テスト用インスタンスは一時的で、ジョブの実行中のみ存続します。
+
+### CD — `cd.yml`
+
+`main` へのプッシュのたびに、設定済みの Twenty サーバーへアプリをデプロイします。また、`deploy` ラベルが付与されたプルリクエストからのデプロイにも対応します（任意）。
+
+**機能:**
+
+1. （ラベル付き PR の場合は）PR のヘッド、またはプッシュされたコミットをチェックアウトします。
+2. `twentyhq/twenty/.github/actions/deploy-twenty-app@main` を実行します（`yarn twenty app:publish --private` の CI 版）。
+3. `twentyhq/twenty/.github/actions/install-twenty-app@main` を実行し、新しくデプロイしたバージョンを対象ワークスペースにインストールします。
+
+**必須の設定:**
+
+| 設定                      | 場所                                                           | 目的                                                 |
+| ----------------------- | ------------------------------------------------------------ | -------------------------------------------------- |
+| `TWENTY_DEPLOY_URL`     | `cd.yml` の `env`（デフォルトは `http://localhost:3000`）             | デプロイ先の Twenty サーバー。 初回利用前に、実際のサーバーの URL に変更してください。 |
+| `TWENTY_DEPLOY_API_KEY` | GitHub リポジトリの **Settings → Secrets and variables → Actions** | 対象サーバーでデプロイ権限を持つ API キー。                           |
+
+<Note>
+デフォルトの `TWENTY_DEPLOY_URL`（`http://localhost:3000`）はプレースホルダーであり、GitHub ホストランナーからは到達できません。 CD を有効化する前に、サーバーの公開 URL に更新するか、ネットワークアクセス可能なセルフホストランナーを使用してください。
+</Note>
+
+**PR からプレビューデプロイをトリガーする:**
+
+プルリクエストに `deploy` ラベルを追加します。 `cd.yml` の `if:` ガードにより、その PR のヘッドコミットを使ってジョブが実行され、マージ前に対象サーバー上で変更を検証できます。
+
+### 公開 — `publish.yml`
+
+バージョンタグ（例: `v1.0.0`）をプッシュしたとき、または Actions タブからワークフローを手動実行したときに、プロビナンス付きでアプリを npm に公開します。
+
+**機能:**
+
+1. あなたのアプリをチェックアウトし、Node.js をセットアップして npm を更新します（信頼できる公開には npm 11.5.1 以降が必要です）。
+2. `yarn twenty app:publish` を実行します。これによりアプリがビルドされ、`.twenty/output` が npm に公開されます。 CI 環境では自動的に `--provenance` と `--access public` が追加されるため、ワークフロー内でフラグを指定する必要はありません。
+
+**一度きりのセットアップ:**
+
+npmjs.com で自分のパッケージを開き、**Settings → Trusted Publisher** から、このリポジトリを `publish.yml` ワークフローで登録します（詳しくは [npm trusted publishing docs](https://docs.npmjs.com/trusted-publishers) を参照してください）。 provenance 付きで公開すると、どの GitHub リポジトリがそのパッケージをビルドしたかが証明されます。これは、Twenty マーケットプレイスでアプリの所有権を主張する方法にもなります。
+
+<Note>
+npm は **public** なソースリポジトリからの provenance しか受け付けません。 private リポジトリから publish しようとすると、npm は OIDC provenance バンドルを `E422 ...` エラーで拒否します。 「Unsupported GitHub Actions source repository visibility: "private"」というエラー。 private リポジトリから publish するには、publish ステップの `env` で `TWENTY_APP_PUBLISH_DISABLE_PROVENANCE: 'true'` を設定して provenance を無効化します（コメントアウトされたヒントが scaffold された `publish.yml` に含まれています）。
+
+```yaml filename=".github/workflows/publish.yml"
+      - name: Publish to npm
+        env:
+          TWENTY_APP_PUBLISH_DISABLE_PROVENANCE: 'true'
+        run: yarn twenty app:publish
+```
+</Note>
+
+### 再利用可能なアクションのバージョン固定
+
+`ci.yml` と `cd.yml` のワークフローは、`@main` の再利用可能なアクションを参照しているため、`twentyhq/twenty` リポジトリでのアクションの更新が自動的に取り込まれます。 ビルドを決定的にしたい場合は、各 `uses:` 行の `@main` をコミット SHA またはリリースタグに置き換えてください。
+
+## npm への公開
+
+npm に公開すると、Twenty マーケットプレイスでアプリが見つけられるようになります。 任意の Twenty ワークスペースは、UI からマーケットプレイスのアプリを参照、インストール、およびアップグレードできます。
+
+### 要件
+
+* [npm](https://www.npmjs.com) アカウント
+* `package.json` の `keywords` 配列にある `twenty-app` キーワード（手動で追加してください — `create-twenty-app` テンプレートにはデフォルトで含まれていません）
+
+```json filename="package.json"
+{
+  "name": "twenty-app-postcard-sender",
+  "version": "1.0.0",
+  "keywords": ["twenty-app"]
+}
+```
+
+### マーケットプレイスのメタデータ
+
+`defineApplication()` の設定は、マーケットプレイスでのアプリの表示方法を制御する任意のフィールドをサポートします。 `public/` フォルダー内の画像を参照するには、`logo` と `galleryImages` を使用します:
+
+```ts src/application-config.ts
+export default defineApplication({
+  universalIdentifier: '...',
+  displayName: 'My App',
+  description: 'A great app',
+  logo: 'public/logo.png',
+  galleryImages: [
+    'public/screenshot-1.png',
+    'public/screenshot-2.png',
+  ],
+});
+```
+
+マーケットプレイスのフィールド（`author`、`category`、`aboutDescription`、`websiteUrl`、`termsUrl` など）の完全な一覧は、Building Apps ページの[defineApplication アコーディオン](/l/ja/developers/extend/apps/config/application#marketplace-metadata)を参照してください。
+
+#### 推奨されるギャラリー画像のサイズ
+
+マーケットプレイスでは、`galleryImages` は固定の `8:5` コンテナ内で表示されます（例：`1600×1000 px`）。
+
+<Note>
+どのようなアスペクト比でもギャラリー画像は全体が表示され、トリミングされることはありません。ただし、`8:5` よりも著しく縦長の場合は、左右に空白の帯が表示されます。
+</Note>
+
+#### 画像サイズの上限
+
+`logo` と各 `galleryImages` ファイルは **10 MB** を超えてはいけません。 マーケットプレイスが公開済みアセットを再ホスティングする際、サイズが大きすぎるファイルはスキップされるため、表示されません。
+
+### 公開
+
+```bash filename="Terminal"
+yarn twenty app:publish
+```
+
+特定の dist-tag（例: `beta` や `next`）で公開するには:
+
+```bash filename="Terminal"
+yarn twenty app:publish --tag beta
+```
+
+### マーケットプレイスの検出の仕組み
+
+Twenty サーバーは、npm レジストリからマーケットプレイスのカタログを**毎時**同期します。
+
+待たずにすぐに同期をトリガーできます:
+
+```bash filename="Terminal"
+yarn twenty dev:catalog-sync
+# To target a specific remote:
+# yarn twenty dev:catalog-sync --remote production
+```
+
+マーケットプレイスに表示されるメタデータは、`defineApplication()` 設定から取得されます。上記の [Marketplace metadata](#marketplace-metadata) を参照してください。
+
+<Note>
+アプリで`defineApplication()`内に`aboutDescription`が定義されていない場合、マーケットプレイスはnpm上のパッケージの`README.md`を概要ページのコンテンツとして自動的に使用します。 つまり、npm と Twenty のマーケットプレイスの両方に対して、1 つの README を維持できます。 マーケットプレイスで異なる説明文を使用したい場合は、`aboutDescription` を明示的に設定してください。
+</Note>
+
+### CI での公開
+
+上で説明したスキャフォールド済みの `publish.yml` ワークフローは、バージョンタグが付けられたときに provenance 情報付きで自動的に npm へ公開します。 `yarn twenty app:publish` は CI で実行される際に `--provenance` と `--access public` を自動的に追加するため、ワークフローで npm フラグを指定する必要はありません。一度きりの trusted-publisher セットアップだけが必要です。
+
+その他の CI システム（GitLab CI、CircleCI など）の場合は、`yarn install` を実行してから `yarn twenty app:publish` を実行します。 環境が OIDC トークンを発行できる場合は provenance が生成され、それ以外の場合は自動的にスキップされます。
+
+<Note>
+**npm provenance** により npm のリスティングにトラストバッジが追加され、公開 CI パイプライン上の特定のコミットからビルドされたパッケージであることをユーザーが検証できるようになります。 また、これにより Twenty マーケットプレイスでアプリの所有権を主張できるようになります。 詳細は [npm provenance のドキュメント](https://docs.npmjs.com/generating-provenance-statements)を参照してください。
+</Note>
+
+## アプリのインストール
+
+アプリが公開（npm）またはデプロイ（tarball）されると、ワークスペースは UI からインストールできます。
+
+Twenty の **設定 > アプリケーション** ページに移動すると、マーケットプレイスと tarball でデプロイされたアプリの両方を参照してインストールできます。
+
+{/* TODO: add screenshot of the UI when the app is registered */}
+
+コマンドラインからアプリをインストールすることもできます:
+
+```bash filename="Terminal"
+yarn twenty app:install
+```
+
+<Note>
+サーバーはインストール時に semver によるバージョニングを強制し、デプロイ時の規則を反映しています:
+
+* ワークスペースに既にインストールされているものと同じバージョンをインストールしようとすると、`APP_ALREADY_INSTALLED` エラーで拒否されます。
+* 現在インストールされているものより低いバージョンをインストールしようとすると、`CANNOT_DOWNGRADE_APPLICATION` エラーで拒否されます。
+
+より新しいバージョンをインストールするには、まずデプロイまたは公開してから、`yarn twenty app:install` を再実行してください。
+</Note>

packages/twenty-docs/l/ja/developers/extend/apps/operations/sync-and-recovery.mdx

@@ -0,0 +1,126 @@
+---
+title: 同期と復旧
+description: どのコマンドをいつ使うか、同期の出力の読み方、そしてローカルのメタデータがずれたときに完全リセットへ到達する前に行うべき復旧手順の段階的な手引きについて説明します。
+icon: compass
+---
+
+ローカルでのアプリ開発は**同期**を中心に回ります。CLI がマニフェストを再ビルドし、サーバーはそれと、すでにワークスペースに存在するメタデータとの差分だけを適用します。 このページでは、どのコマンドを使うべきか、同期で何が変更されたのかをどう読み取るか、そしてローカルの状態が一貫していないように見えるときに取るべき手順を（順番に）説明します。
+
+## どのコマンドをいつ使うか
+
+<Note>
+日々のローカルでの反復開発では、ほとんどの場合 `yarn twenty dev` を使うことになります。 デプロイと公開はリリースのためのものであり、ローカルでの開発ループのためのもの**ではありません**。
+</Note>
+
+| やりたいこと…                        | コマンド                                | ノート                                                                                                               |
+| ------------------------------ | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| ライブ同期でローカルに反復開発する              | `yarn twenty dev`                   | ファイルを監視し、変更のたびに同期します。                                                                                             |
+| 1 回だけ同期して終了（CI、スクリプト、フック向け）    | `yarn twenty apply`                 | 1 回ビルドして同期し、その後終了します。 破壊的変更の確認をスキップするには、`--force` を追加します。                                                         |
+| 変更を**適用せずに**プレビュー              | `yarn twenty plan`                  | 差分を計算して表示しますが、何も書き込みません。                                                                                          |
+| ワークスペースからアプリを削除する              | `yarn twenty app:uninstall`         | プロンプトをスキップするには、`--yes` を追加します。                                                                                    |
+| サーバーに tarball をアップロードする        | `yarn twenty app:publish --private` | `package.json` のバージョンが**厳密により高い**必要があります — [Publishing](/l/ja/developers/extend/apps/operations/publishing) を参照してください。 |
+| マーケットプレイス（npm）に公開する            | `yarn twenty app:publish`           | —                                                                                                                 |
+| デプロイ済みバージョンをインストール / アップグレードする | `yarn twenty app:install`           | 現在デプロイされているバージョンをインストールします。                                                                                       |
+| ローカルサーバーを消去してクリーンに開始する         | `yarn twenty docker:reset`          | ローカルデータを**すべて**削除します — 最終手段です。                                                                                    |
+
+<Note>
+`yarn twenty dev --once` および `yarn twenty dev --once --dry-run` は、`yarn twenty apply` と `yarn twenty plan` の非推奨エイリアスとして依然として動作します。
+</Note>
+
+### ローカル同期ではバージョンの更新は不要
+
+厳密に増加する `version` のルール（デプロイ時の `VERSION_ALREADY_EXISTS`、インストール時の `APP_ALREADY_INSTALLED` / `CANNOT_DOWNGRADE_APPLICATION`）は、リリースパスである **`app:publish` / `app:install`** に適用されます。 `yarn twenty dev` はマニフェストをその場で同期し、バージョン変更を要求することはないため、反復するのに `package.json` を触る必要はありません。 ローカルの変更をテストするためにバージョンを上げている場合は、開発ループが必要なところでリリース経路を使ってしまっています。
+
+## 同期出力の読み方
+
+各同期では、適用した（`plan` の場合は適用される）メタデータの変更が出力されます。Terraform と同様に、エンティティごとにその属性を含むブロックが 1 つずつ表示され、その後にサマリー行が続きます。
+
+```text filename="Terminal"
+  # objectMetadata "rocket" will be created
+  + icon          = "IconRocket"
+  + labelSingular = "Rocket"
+  + ...
+
+  # fieldMetadata "launchedAt" will be updated
+  ~ isNullable = false -> true
+
+Plan: 2 to add, 1 to change, 1 to destroy.
+
+✓ Synced My App (4 files)
+```
+
+これは最初の診断手段です。どのオブジェクト、フィールド、レイアウトが変更されたかを正確に示すので、UI を確認する前に、同期が想定どおりに動作したかを確認できます。
+
+破壊的変更（`to destroy`）は、何を削除するかとあわせて一覧表示され（例: `objectMetadata "auditNote" — drops the table and all its rows`）、対話的な確認、またはスクリプト内での `--force` が必要です。
+
+同期が単一のエンティティで失敗した場合、エラーには問題のエンティティとその `universalIdentifier` が、次のように示されます。
+
+```text
+Migration action 'create' for 'fieldMetadata' (universalIdentifier: 2020...4337) failed
+```
+
+その識別子を使って、推測で衝突元を探すのではなく、マニフェスト内（必要であればワークスペース内）のエンティティを特定してください。
+
+## 変更内容のプレビュー（プラン）
+
+`yarn twenty plan` はマニフェストをビルドし、サーバーにマイグレーションプランを問い合わせ、その内容を **何も適用せずに** 表示します。 コミットする前に「この同期は何を変更するか？」という問いに安全に答える方法です。
+
+```bash filename="Terminal"
+yarn twenty plan
+```
+
+```text filename="Terminal"
+Building manifest...
+Computing metadata plan (read-only, nothing will be applied)...
+
+  # fieldMetadata "crewCapacity" will be created
+  + ...
+
+Plan: 1 to add, 1 to change, 0 to destroy.
+
+✓ Plan complete for My App — no changes were applied
+```
+
+プランの例:
+
+* **何も書き込みません** — メタデータマイグレーション、アプリケーションレコードの更新、デフォルトのロール / タブの変更、API クライアントの生成は一切行いません。
+* 実際の同期が適用するのと**同じ差分**を返すため、作成 / 更新 / 削除されるエンティティを事前に確認できます。
+* リスクの高い変更の前や、AI 生成の変更をレビューするとき、または予期せぬ変更が行われそうな場合にスクリプトを失敗させたいときなどに有用です。
+
+<Note>
+プランでは **メタデータ** の変更のみがプレビューされます。また、アプリが少なくとも一度は同期されている（ワークスペース側がその存在を知っている）必要があります。 一度も同期されていないアプリに対して実行すると、サーバーはそのアプリがインストールされていないと報告します — まず一度 `yarn twenty dev` を実行してください。
+</Note>
+
+## リカバリーラダー
+
+ローカルのメタデータが正しくないように見える場合は、次の順番でエスカレートし、問題が解消したところで止めてください。 各ステップは前のものよりも影響が大きくなります。
+
+1. **再同期。** `yarn twenty apply` を再度実行します。 同期はべき等であり、クリーンなマニフェストを再実行しても安全で、多くの場合は一時的な不具合が解消されます。
+2. **プランをプレビュー。** `yarn twenty plan` を実行して、次の同期が何を変更しようとしているのかを、適用せずに正確に確認します。
+3. **名前付きエラーを読む。** 同期が失敗した場合は、メッセージ内のメタデータタイプと `universalIdentifier`（上記参照）を確認し、そのエンティティをマニフェスト内で特定します。 コンフリクトは、重複または再利用された識別子を指していることがほとんどです。
+4. **アンインストールして再インストール。** `yarn twenty app:uninstall` を実行し、その後再度同期します（`yarn twenty dev`）。 これにより、ワークスペースの残りを維持したまま、アプリのメタデータをクリーンな状態から再構築します。
+5. **フルリセット（最後の手段）。** `yarn twenty docker:reset` を実行し、その後再シードと再同期を行います。
+
+<Warning>
+`yarn twenty docker:reset` はローカルインスタンス内のデータを**すべて**削除します — すべてのワークスペース、レコード、アプリが消去されます。 それまでの手順がすべて失敗した場合にのみ使用してください。
+</Warning>
+
+<Note>
+メタデータエラーが発生しましたか？ [issue を作成](https://github.com/twentyhq/twenty/issues/new/choose)し、失敗したマイグレーションメッセージ（メタデータタイプと `universalIdentifier` を含む）、同期時の `Metadata changes` の出力、および実行したコマンドを記載してください。
+</Note>
+
+## 1 つのワークスペースでの同時同期を避ける
+
+同期ではメタデータマイグレーションが適用されます。 **同じワークスペースに対して同時に**複数の同期、デプロイ、インストール操作を実行すると（たとえば、複数のターミナルや AI エージェントが並行して反復している場合）、それらのマイグレーションが入り混じり、メタデータが一部だけ適用された状態のままになってしまう可能性があります。
+
+サーバーはワークスペースごとに同期を直列化してこれを防いでいますが、それでも、センシティブなメタデータ操作は同時に実行するのではなく、**単一の**プロセスに集約するべきです。 複数のエージェントで開発をオーケストレーションしている場合は、それらの sync / deploy / install 呼び出しを 1 つのキューに流し込み、同時ではなく一度に 1 つだけ実行されるようにしてください。
+
+## 失敗の切り分け
+
+問題が発生したときは、メタデータの差分と名前付きエラーによって、どこで失敗したかを特定できます。
+
+* **マニフェストビルドエラー** — CLI が同期前に失敗します（`MANIFEST_BUILD_FAILED`、`TYPECHECK_FAILED`）。アプリのソースを修正してください。
+* **同期 / マイグレーションエラー** — ビルドは成功しますが、差分の適用が失敗し、エンティティと `universalIdentifier` が示されます。そのコンフリクトしているメタデータを修正してください。
+* **依存関係サイズエラー** — 同期またはインストールが失敗しました。アプリの本番用 `dependencies` がランタイムレイヤーとしてインストールするには大きすぎるためです（`LOGIC_FUNCTION_DEPENDENCIES_SIZE_EXCEEDED`）。ランタイムでロジック関数がインポートしないパッケージ（UI ライブラリ、開発ツール類）は `devDependencies` に移動してください。
+* **アプリコードの実行時エラー** — 同期自体は成功しているものの、ロジック関数やコンポーネントが実行時に正しく動作しません。[function logs](/l/ja/developers/extend/apps/operations/cli) を確認してください。
+* **ローカルインスタンスの状態** — 上記のいずれにも当てはまらないのにワークスペースの見た目が依然としておかしい場合は、リカバリーラダーに従って下の段階へ進んでください。

packages/twenty-docs/l/ja/developers/extend/apps/operations/testing.mdx

@@ -0,0 +1,264 @@
+---
+title: テスト
+description: Vitest のセットアップ、実際の Twenty サーバーに対する統合テスト、型チェック、および GitHub Actions を使った CI。
+icon: flask
+---
+
+SDK は、テストコードからアプリのビルド、デプロイ、インストール、アンインストールを可能にするプログラム用 API を提供します。 [Vitest](https://vitest.dev/) と型付き API クライアントを組み合わせることで、実際の Twenty サーバーに対してエンドツーエンドで動作を検証する統合テストを作成できます。
+
+## npm パッケージの使用
+
+アプリで任意の npm パッケージをインストールして使用できます。 ロジック関数とフロントコンポーネントはどちらも [esbuild](https://esbuild.github.io/) でバンドルされ、依存関係は出力にインライン化されます—実行時に `node_modules` は不要です。
+
+### パッケージのインストール
+
+```bash filename="Terminal"
+yarn add axios
+```
+
+次に、コードでインポートします：
+
+```ts src/logic-functions/fetch-data.ts
+import { defineLogicFunction } from 'twenty-sdk/define';
+import axios from 'axios';
+
+const handler = async (): Promise<any> => {
+  const { data } = await axios.get('https://api.example.com/data');
+
+  return { data };
+};
+
+export default defineLogicFunction({
+  universalIdentifier: '...',
+  name: 'fetch-data',
+  description: 'Fetches data from an external API',
+  timeoutSeconds: 10,
+  handler,
+});
+```
+
+フロントコンポーネントでも同様に機能します：
+
+```tsx src/front-components/chart.tsx
+import { defineFrontComponent } from 'twenty-sdk/define';
+import { format } from 'date-fns';
+
+const DateWidget = () => {
+  return <p>Today is {format(new Date(), 'MMMM do, yyyy')}</p>;
+};
+
+export default defineFrontComponent({
+  universalIdentifier: '...',
+  name: 'date-widget',
+  component: DateWidget,
+});
+```
+
+### バンドルの仕組み
+
+ビルドステップでは esbuild を使用して、各ロジック関数および各フロントコンポーネントごとに自己完結した単一ファイルを生成します。 インポートされたパッケージは、以下に一覧表示されているものを除き、バンドル内にインライン化されます。
+
+**ロジック関数**は Node.js 環境で実行されます。 Node の組み込みモジュール（`fs`、`path`、`crypto`、`http` など） は利用可能で、インストールは不要です。
+
+**フロントコンポーネント**は Web Worker で実行されます。 Node の組み込みモジュールは利用できません—ブラウザー環境で動作する npm パッケージのみが使用できます。 サンドボックスは *一部のみ* の DOM を実装しているため、パッケージはクリーンにビルドできても実行時に失敗する可能性があります。詳しくは [Current limitations](/l/ja/developers/extend/apps/layout/front-components#current-limitations) を参照してください。
+
+どちらの環境でも、`twenty-client-sdk/core` および `twenty-client-sdk/metadata` が事前提供モジュールとして利用可能です—これらはバンドルされず、実行時にサーバーによって解決されます。
+
+フロントコンポーネントは、[共有依存関係バンドル](/l/ja/developers/extend/apps/layout/front-components#sharing-dependencies-across-front-components) を通じて依存関係を共有することもできます。 アプリの package.json の `frontComponentSharedDependencies` フィールドに記載されたパッケージは、1 回だけビルドされて別ファイルにまとめられ、各コンポーネントにインライン化される代わりに実行時にそのファイルから読み込まれます。そのため、共有パッケージのみをインポートするコンポーネントは、それ自身の依存コードをほとんど持ちません。
+
+## セットアップ
+
+スキャフォルドされたアプリにはすでに Vitest が含まれています。 手動で設定する場合は、依存関係をインストールしてください：
+
+```bash filename="Terminal"
+yarn add -D vitest vite-tsconfig-paths
+```
+
+アプリのルートに `vitest.config.ts` を作成します：
+
+```ts vitest.config.ts
+import tsconfigPaths from 'vite-tsconfig-paths';
+import { defineConfig } from 'vitest/config';
+
+const TWENTY_API_URL = process.env.TWENTY_API_URL ?? 'http://localhost:2020';
+const TWENTY_API_KEY = process.env.TWENTY_API_KEY ?? '<the pre-seeded local dev key>';
+
+// Make env vars available to globalSetup (test.env only applies to workers)
+process.env.TWENTY_API_URL = TWENTY_API_URL;
+process.env.TWENTY_API_KEY = TWENTY_API_KEY;
+
+export default defineConfig({
+  plugins: [
+    tsconfigPaths({
+      projects: ['tsconfig.spec.json'],
+      ignoreConfigErrors: true,
+    }),
+  ],
+  test: {
+    testTimeout: 120_000,
+    hookTimeout: 120_000,
+    fileParallelism: false,
+    include: ['src/**/*.integration-test.ts'],
+    globalSetup: ['src/__tests__/global-setup.ts'],
+    env: {
+      TWENTY_API_URL,
+      TWENTY_API_KEY,
+    },
+  },
+});
+```
+
+サーバーに到達可能であることを検証し、SDK 用のテスト設定（`~/.twenty/config.test.json`）を書き込み、テストの実行前にアプリを同期するグローバルセットアップファイルを作成します。
+
+```ts src/__tests__/global-setup.ts
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+
+import { appDevOnce, appUninstall } from 'twenty-sdk/cli';
+
+const APP_PATH = process.cwd();
+const CONFIG_DIR = path.join(os.homedir(), '.twenty');
+
+export async function setup() {
+  const apiUrl = process.env.TWENTY_API_URL!;
+  const apiKey = process.env.TWENTY_API_KEY!;
+
+  // Verify the server is running
+  const response = await fetch(`${apiUrl}/healthz`);
+  if (!response.ok) {
+    throw new Error(`Twenty server is not reachable at ${apiUrl}.`);
+  }
+
+  // Write the SDK's test config (the CLI reads config.test.json when NODE_ENV=test)
+  fs.mkdirSync(CONFIG_DIR, { recursive: true });
+  fs.writeFileSync(
+    path.join(CONFIG_DIR, 'config.test.json'),
+    JSON.stringify({
+      remotes: { local: { apiUrl, apiKey } },
+      defaultRemote: 'local',
+    }, null, 2),
+  );
+
+  // Start from a clean slate, then sync the app
+  await appUninstall({ appPath: APP_PATH }).catch(() => {});
+
+  const result = await appDevOnce({ appPath: APP_PATH });
+  if (!result.success) {
+    throw new Error(`Dev sync failed: ${result.error?.message}`);
+  }
+}
+
+export async function teardown() {
+  await appUninstall({ appPath: APP_PATH });
+}
+```
+
+## プログラム用 SDK API
+
+`twenty-sdk/cli` サブパスは、テストコードから直接呼び出せる関数をエクスポートします：
+
+| 関数             | 説明                                           |
+| -------------- | -------------------------------------------- |
+| `appBuild`     | アプリをビルドし、必要に応じて tarball にパッケージ化              |
+| `appDeploy`    | tarball をサーバーにアップロード                         |
+| `appDevOnce`   | アプリを 1 回ビルドして同期します（`yarn twenty apply` と同じ）。 |
+| `appInstall`   | アクティブなワークスペースにアプリをインストール                     |
+| `appUninstall` | アクティブなワークスペースからアプリをアンインストール                  |
+
+各関数は、`success: boolean` と `data` または `error` のいずれかを含む結果オブジェクトを返します。
+
+## 統合テストの作成
+
+アプリをビルド、デプロイ、インストールし、その後ワークスペースに表示されることを検証する完全な例を次に示します：
+
+```ts src/__tests__/app-install.integration-test.ts
+import { APPLICATION_UNIVERSAL_IDENTIFIER } from 'src/application-config';
+import { appBuild, appDeploy, appInstall, appUninstall } from 'twenty-sdk/cli';
+import { MetadataApiClient } from 'twenty-client-sdk/metadata';
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+
+const APP_PATH = process.cwd();
+
+describe('App installation', () => {
+  beforeAll(async () => {
+    const buildResult = await appBuild({
+      appPath: APP_PATH,
+      tarball: true,
+      onProgress: (message: string) => console.log(`[build] ${message}`),
+    });
+
+    if (!buildResult.success) {
+      throw new Error(`Build failed: ${buildResult.error?.message}`);
+    }
+
+    const deployResult = await appDeploy({
+      tarballPath: buildResult.data.tarballPath!,
+      onProgress: (message: string) => console.log(`[deploy] ${message}`),
+    });
+
+    if (!deployResult.success) {
+      throw new Error(`Deploy failed: ${deployResult.error?.message}`);
+    }
+
+    const installResult = await appInstall({ appPath: APP_PATH });
+
+    if (!installResult.success) {
+      throw new Error(`Install failed: ${installResult.error?.message}`);
+    }
+  });
+
+  afterAll(async () => {
+    await appUninstall({ appPath: APP_PATH });
+  });
+
+  it('should find the installed app in the workspace', async () => {
+    const metadataClient = new MetadataApiClient();
+
+    const result = await metadataClient.query({
+      findManyApplications: {
+        id: true,
+        name: true,
+        universalIdentifier: true,
+      },
+    });
+
+    const installedApp = result.findManyApplications.find(
+      (app: { universalIdentifier: string }) =>
+        app.universalIdentifier === APPLICATION_UNIVERSAL_IDENTIFIER,
+    );
+
+    expect(installedApp).toBeDefined();
+  });
+});
+```
+
+## テストの実行
+
+ローカルの Twenty サーバーが起動していることを確認し、次を実行します：
+
+```bash filename="Terminal"
+yarn test
+```
+
+また、開発中はウォッチモードでも実行できます：
+
+```bash filename="Terminal"
+yarn test:watch
+```
+
+## 型チェック
+
+テストを実行せずに、アプリの型チェックのみを実行することもできます：
+
+```bash filename="Terminal"
+yarn twenty dev:typecheck
+```
+
+これは、あなたのアプリの `tsconfig.json` に対して `tsc --noEmit` を実行し、型エラーを報告します。 スキャフォルドされたアプリには、テストファイル（`tsconfig.spec.json`）も対象とする `yarn typecheck` スクリプトも同梱されています。
+
+## GitHub Actions による CI
+
+スキャフォルダーは、すぐに使えるワークフローを `.github/workflows/ci.yml` に生成します。 `main` へのすべてのプッシュおよびすべてのプルリクエスト時に、ランナー内で一時的な Twenty サーバーを起動（`twentyhq/twenty/.github/actions/spawn-twenty-app-dev-test` アクション経由）し、そのサーバーを指すように `TWENTY_API_URL` / `TWENTY_API_KEY` を設定した上で、`yarn lint`、`yarn typecheck`、`yarn test:unit`、`yarn test` を実行します。 シークレットは一切不要で、ワークフローの先頭にある `TWENTY_VERSION` 環境変数を通じてサーバーバージョンを固定できます。
+
+スキャフォルドされた 3 つのワークフロー（`ci.yml`、`cd.yml` デプロイパイプライン、npm パブリッシング用の `publish.yml`）の詳細な手順については、[Publishing → Automated CI/CD](/l/ja/developers/extend/apps/operations/publishing#automated-cicd-scaffolded-workflows) を参照してください。

packages/twenty-docs/l/ja/developers/extend/apps/operations/translations.mdx

@@ -0,0 +1,126 @@
+---
+title: 翻訳
+description: 複数の言語でアプリを提供できます — 単一の locales カタログで、マニフェストのラベルと UI 文字列を翻訳します。
+icon: language
+---
+
+Twenty のアプリは **英語** で作成されています。ソースやマニフェスト内の文字列は英語のソーステキストであり、`en` は翻訳の元となるソースロケールです。未翻訳のロケールは `en` にフォールバックします。
+
+アプリには 2 種類の翻訳可能なテキストがあり、どちらも同じ `locales/` カタログを通じて処理されます。
+
+* **Manifest labels** — オブジェクト名とフィールド名、ビュータイトル、メニュー項目、その他アプリのメタデータで宣言される文字列。
+* **Front-component strings** — React のフロントコンポーネントがレンダリングするUIテキスト。
+
+翻訳可能な文字列にマークを付けてロケールごとのカタログに抽出し、それらのカタログを翻訳すれば、ビルドが現在のユーザーに適切な言語を提供します — 追加の設定は不要です。
+
+## フロントコンポーネント文字列のマーク
+
+`20-sdk/front-component` から翻訳ヘルパーをインポートします。
+
+```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>
+  );
+};
+```
+
+### 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
+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
+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
+// 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
+<Trans>Welcome back</Trans>
+<Trans>
+  Welcome
+  back
+</Trans>
+```