# Contentfulから移行する手順：モデル・Rich Text・画像・言語

公開日: 2026-10-20 | 更新日: 2026-10-20 | URL: https://blog.genko.me/contentful-migration

> Contentfulからgenko.meへ移行する手順を解説します。公式CLIのエクスポート、モデルとRich Textの変換、画像と参照ID、多言語の取り込み、Webhookの再設定、移行前に確認すべき制約を整理しました。

Contentfulからgenko.meへ移行するには、公式CLIでデータを保存し、モデル・言語別フィールド・Rich Text・アセット参照をgenko.meの形式へ変換します。Contentfulのエクスポートをそのまま完全復元できる移行ツールはありません。記事を少数試し、参照と翻訳のIDをそろえてから、下書きとして段階的に取り込む方法が適しています。

本記事はgenko.meの運営側が執筆しています。2026年10月20日時点の公式資料と実装を確認しています。

## Contentfulから移行する前に確認すること

移行理由が編集画面や小規模サイトの運用見直しなら、実際の記事で比較してください。一方、Contentfulの環境管理や独自のエディタ拡張、複雑なモデルを活用している場合は、その運用を移植する費用が判断材料になります。[公式CLI資料](https://www.contentful.com/developers/docs/tutorials/cli/import-and-export/)に出てくる環境などは本文とは別の移行対象です。

| 棚卸しするもの | 決めること |
| --- | --- |
| Space・Environment | 移行元を固定し、検証用データと本番原稿を区別 |
| Content Type | genko.meのどのAPIに対応させるか |
| Entry・AssetのID | 維持するIDと変換が必要なID |
| Locale | メイン言語、サブ言語、未翻訳の扱い |
| Rich Text内の埋め込み | HTML化、別フィールド化、サイト側描画のどれを使うか |
| Webhookと周辺処理 | 再ビルド、検索更新などの再接続先 |

変換・開発・確認・保守も見積もり、既存機能が必要なら継続も検討します。

## 1. Contentful CLIでエクスポートする

公式にインストール・認証した`contentful-cli`を使い、対象SpaceとEnvironmentを指定します。次は公式資料にあるオプションを使った例です。`SPACE_ID`と`ENVIRONMENT_ID`を実際の値へ置き換え、認証情報を原稿や共有リポジトリへ書かないでください。

```bash
contentful space export \
  --space-id SPACE_ID \
  --environment-id ENVIRONMENT_ID \
  --include-drafts \
  --include-archived \
  --download-assets \
  --export-dir ./contentful-backup \
  --content-file export.json
```

JSONとダウンロードしたファイルを保管します。このコマンドはContentful側の書き出しで、genko.meへ取り込むコマンドではありません。切り替え前に編集を止めて再取得し、検証後の差分を確認します。

## 2. Content Typeをgenko.meのAPIへ対応付ける

genko.meでは[APIとスキーマ](https://docs.genko.me/studio/apis)で入力項目を作ります。ContentfulのContent Typeをそのまま自動作成する機能はありません。単純な項目から対応表を作り、独自の検証ルールは別途確認します。

| 元のデータ | 移行先の設計例 | 注意点 |
| --- | --- | --- |
| 短文 | `text` | フィールドIDと必須条件を確認 |
| 長文 | `textarea` | 装飾が必要なら本文用の設計を分ける |
| 数字・真偽値・日時 | `number`・`boolean`・`datetime` | 値とタイムゾーンを検証 |
| Rich Text | `richtext` | JSONツリーをHTML文字列へ変換 |
| Entry参照 | `reference`・`references` | 参照先を登録し、IDを置き換える |
| Asset参照 | `image`・`images`・`file` | 移行先のメディアを登録する |
| JSONオブジェクト・複合構造 | 分割、別API、テキストとして保存 | 一対一の対応を前提にしない |

具体的な型は[フィールド一覧](https://docs.genko.me/studio/fields)を確認してください。必須は下書き保存にも適用されるため、作成途中の記事を保存できる設計にします。公開にだけ必要な条件は、編集運用とサイト側の検査も含めて決めます。

## 3. Contentful Rich TextをHTMLへ変換する

Contentfulの[Rich TextはJSON構造](https://www.contentful.com/developers/docs/concepts/rich-text/)です。genko.meのリッチテキストはHTML文字列なので、同じデータとして渡すことはできません。

基本的な変換には公式の[`@contentful/rich-text-html-renderer`](https://www.contentful.com/developers/docs/javascript/tutorials/rendering-contentful-rich-text-with-javascript/)の`documentToHtmlString`を利用できます。ただし、埋め込みEntryやAssetを表示するには、参照先を解決したうえで描画規則を作る必要があります。

変換時は、段落・見出しだけで成功と判断せず、次を確認します。

1. 内部リンクの参照先が新しいURLになるか。
2. 画像のリンク先と代替テキストを保持できるか。
3. 埋め込みEntryを、カード・通常リンク・別項目のどれへ変えるか。
4. 表やコードなどが、取り込み後のエディタと表示側で保たれるか。
5. 不要なHTMLや危険な属性を取り除いても意味が変わらないか。

HTMLは表示だけでなく、取り込み後の再編集・保存・配信まで確認します。

## 4. アセットと参照を先に準備する

ContentfulのAsset IDやCDN URLを画像フィールドへコピーしても、genko.meのメディアにはなりません。WordPress用・Contentful用の画像自動コピーはなく、Newt向けの画像移行とは別です。

画像は[コンテンツの画像・ファイル欄](https://docs.genko.me/studio/media)から登録し、原稿を保存して参照を確定させます。少量なら本文の取り込み後に手動で配置します。多量の場合は、旧Asset ID・保存ファイル・移行先メディアID・使用記事を対応表に残してください。取り込み形式の見本には、移行先で作ったテスト原稿のJSONエクスポートを使えます。

著者やカテゴリなどの参照先も先に作ります。依存関係が循環する場合は、最初に参照を任意にして原稿を登録し、対応IDがそろってから編集で結び付けます。リスト形式のインポートは既存記事を更新しないため、同じファイルの再投入で参照を後付けできるとは考えないでください。

## 5. 言語別のJSONへ変換して取り込む

Contentfulは[フィールドやEntryを使ったローカライズ](https://www.contentful.com/help/localization/field-and-entry-localization/)を説明しています。現在の方式を調べ、元データのどの値をどの言語へ移すか決めます。

genko.meでは1つの原稿IDに言語版を持たせ、値と公開状態を言語ごとに管理します。最初にメイン言語を登録し、そのIDと一致するサブ言語を取り込みます。設定と配信は[多言語コンテンツ](https://docs.genko.me/guides/multilingual-content)にあります。

次は、`title`と`body`を作ったAPIへ渡す変換済みJSONで、元のエクスポートとは異なります。

```json
{
  "contents": [
    {
      "id": "article-001",
      "title": "はじめての記事",
      "body": "<p>Rich Textから変換した本文です。</p>"
    }
  ]
}
```

1. まずメイン言語へ「下書き」で取り込みます。
2. 同じIDで翻訳済みの値を用意します。
3. インポート画面で対象のサブ言語を選びます。
4. ID一致件数とスキップ対象を確認して取り込みます。
5. 言語別にプレビューし、意図したものだけ公開します。

サブ言語の取り込みは、メイン言語にないIDを新規作成しません。未翻訳の値を機械的に複製して翻訳済みに見せず、言語版を作らないか、サイトで明示的なフォールバックを選びます。genko.meの配信は既定でフォールバックせず、公開版がない言語の単一取得は404です。

## genko.meのインポートで引き継げないもの

[取り込み仕様](https://docs.genko.me/studio/import-export)では、2026年10月時点で1ファイル10MB、1回1,000件までです。ContentfulのJSONに`entries`配列があっても、言語別の`fields`や`sys`を変換せず直接取り込める意味ではありません。

コンテンツIDは英数字・ハイフン・アンダースコアで64文字以内です。無効なIDは変換表で管理します。元の公開状態・予約・作成日時・編集履歴の復元はできません。元の公開日などは専用の日時フィールドへ移します。

同じIDが既存のリストにあると取り込みは停止し、それまでの保存分は残ります。全件を一括でロールバックする処理ではないため、成功したIDを照合して残りだけを再実行します。

## Webhookと公開サイトを切り替える

genko.meの[Webhook](https://docs.genko.me/guides/webhooks)は本文全体ではなく変更通知を送ります。既存のContentful向け受信処理をそのまま流用せず、イベント名、署名検証、対象API、言語を合わせて作り直します。自動リトライはなく、失敗時はログから手動再送できます。

手動公開は作成・更新イベントです。`entry.published`だけを監視すると手動公開を取りこぼすため、保存・削除・下書き化・言語別更新も含めて確認します。新しいフロントエンドの一覧・詳細・プレビュー・キャッシュ更新が通ってから切り替えます。

URLも変える場合は、旧URLごとの転送が必要です。作業表の例は[WordPress移行ガイド](https://blog.genko.me/wordpress-to-headless-cms)、再検証は[Next.jsとWebhook](https://blog.genko.me/nextjs-webhook-revalidate)を参照してください。[genko.me](https://genko.me/)の[プランと上限](https://docs.genko.me/studio/plans)に、言語数と画像容量も当てはめて確認します。

## よくある質問

### ContentfulのJSONをそのままgenko.meへ移せますか？

完全な直接移行には対応していません。Content Type、言語別フィールド、Rich Text、参照とメディアを移行先のスキーマに合わせて変換します。

### ContentfulのRich TextはHTMLへ変換できますか？

公式のHTMLレンダラーを使えます。埋め込みEntryやAssetは参照解決と描画規則が必要で、移行後の編集・保存も確認してください。

### Contentfulの多言語コンテンツは引き継げますか？

言語ごとに変換し、メイン言語の後で同じIDのサブ言語を取り込めます。元サービスのローカライズやフォールバック設定が自動で再現されるわけではありません。

### ContentfulのWebhook設定は移行できますか？

genko.me向けに登録と受信処理の再設定が必要です。署名、イベント、言語、失敗時の復旧を、新しい通知形式に合わせて検証してください。

## 出典

2026年10月20日に確認しました。

- [Contentful：CLIのインポート・エクスポート](https://www.contentful.com/developers/docs/tutorials/cli/import-and-export/)
- [Contentful：Rich Text](https://www.contentful.com/developers/docs/concepts/rich-text/)
- [Contentful：Rich TextのHTML変換](https://www.contentful.com/developers/docs/javascript/tutorials/rendering-contentful-rich-text-with-javascript/)
- [Contentful：ローカライズ方式](https://www.contentful.com/help/localization/field-and-entry-localization/)
- [genko.me：インポートとエクスポート](https://docs.genko.me/studio/import-export)
- [genko.me：多言語コンテンツ](https://docs.genko.me/guides/multilingual-content)