Intlayer コンテンツ管理システム（CMS）ドキュメント

Intlayer CMSは、Intlayerプロジェクトのコンテンツを外部化できるアプリケーションです。

そのために、Intlayerは「遠隔辞書（distant dictionaries）」の概念を導入しています。

目次

遠隔辞書の理解

Intlayerは「ローカル辞書」と「遠隔辞書」を区別しています。

• 「ローカル」辞書とは、Intlayerプロジェクト内で宣言されている辞書のことです。例えば、ボタンの宣言ファイルやナビゲーションバーなどです。この場合、コンテンツは頻繁に変更されることを想定していないため、コンテンツを外部化することは意味がありません。

• 「遠隔」辞書とは、Intlayer CMSを通じて管理される辞書のことです。これは、チームがウェブサイト上で直接コンテンツを管理できるようにするために役立ち、さらにA/Bテスト機能やSEOの自動最適化を利用することも目的としています。

ビジュアルエディターとCMSの違い

Intlayer Visual エディターは、ローカル辞書のコンテンツをビジュアルエディターで管理できるツールです。変更が行われると、コンテンツはコードベースに置き換えられます。つまり、アプリケーションが再ビルドされ、ページがリロードされて新しいコンテンツが表示されることを意味します。

これに対して、Intlayer CMSは、遠隔辞書のコンテンツをビジュアルエディターで管理できるツールです。変更が行われても、コンテンツはコードベースに影響を与えません。そして、ウェブサイトは自動的に変更されたコンテンツを表示します。

統合

パッケージのインストール方法の詳細については、以下の該当セクションを参照してください。

Next.jsとの統合

Next.jsとの統合については、セットアップガイドを参照してください。

Create React Appとの統合

Create React Appとの統合については、セットアップガイドを参照してください。

Vite + Reactとの統合

Vite + Reactとの統合については、セットアップガイドを参照してください。

設定

Intlayer CMSにログインするには、次のコマンドを実行してください：

npx intlayer login

これにより、デフォルトのブラウザが開き、認証プロセスを完了し、Intlayerサービスを使用するために必要な認証情報（Client IDとClient Secret）を受け取ることができます。

Intlayerの設定ファイル内で、CMSの設定をカスタマイズできます：

import type { IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  // ... その他の設定
  editor: {
    /**
     * 必須
     *
     * アプリケーションのURL。
     * これはビジュアルエディターがターゲットとするURLです。
     */
    applicationURL: process.env.INTLAYER_APPLICATION_URL,

    /**
     * 必須
     *
     * エディターを有効にするためにクライアントIDとクライアントシークレットが必要です。
     * これらはコンテンツを編集しているユーザーを識別するために使用されます。
     * Intlayerダッシュボードのプロジェクト（https://app.intlayer.org/projects）で新しいクライアントを作成することで取得できます。
     * clientId: process.env.INTLAYER_CLIENT_ID,
     * clientSecret: process.env.INTLAYER_CLIENT_SECRET,
     */
    clientId: process.env.INTLAYER_CLIENT_ID,
    clientSecret: process.env.INTLAYER_CLIENT_SECRET,

    /**
     * 任意
     *
     * Intlayer CMSをセルフホスティングしている場合、CMSのURLを設定できます。
     *
     * Intlayer CMSのURL。
     * デフォルトでは https://intlayer.org に設定されています。
     */
    cmsURL: process.env.INTLAYER_CMS_URL,

    /**
     * オプション
     *
     * Intlayer CMSをセルフホスティングしている場合、バックエンドのURLを設定できます。
     *
     * Intlayer CMSのURL。
     * デフォルトでは https://back.intlayer.org に設定されています。
     */
    backendURL: process.env.INTLAYER_BACKEND_URL,
  },
};

export default config;

クライアントIDとクライアントシークレットをお持ちでない場合は、Intlayerダッシュボード - プロジェクトで新しいクライアントを作成して取得できます。

利用可能なすべてのパラメータについては、設定ドキュメントを参照してください。

CMSの使用方法

設定のプッシュ

Intlayer CMSを設定するには、intlayer CLIコマンドを使用できます。

npx intlayer config push

intlayer.config.ts設定ファイルで環境変数を使用している場合は、--env引数を使って希望の環境を指定できます：

npx intlayer config push --env production

このコマンドは設定をIntlayer CMSにアップロードします。

辞書をプッシュする

ロケール辞書をリモート辞書に変換するには、intlayer CLIコマンドを使用できます。

npx intlayer dictionary push -d my-first-dictionary-key

intlayer.config.ts 設定ファイルで環境変数を使用している場合は、--env 引数を使って希望の環境を指定できます。

npx intlayer dictionary push -d my-first-dictionary-key --env production

このコマンドは初期コンテンツの辞書をアップロードし、Intlayer プラットフォームを通じて非同期に取得および編集できるようにします。

辞書の編集

その後、Intlayer CMS で辞書を確認および管理できるようになります。

@intlayer/api SDK を使用したプログラムによるアクセス

CLI およびビジュアルエディターを超えて、Intlayer は @intlayer/api パッケージで型付き SDK を提供しています。これにより、CMS をヘッドレスコンテンツデータベースとして扱うことができます。プロジェクトの取得、辞書の取得、および独自のアプリケーション、スクリプト、または CI パイプラインから直接、それらをプッシュまたは更新できます。

SDK は認証を処理します。clientId と clientSecret が利用可能であれば（Intlayer の設定または環境変数で）、OAuth2 アクセストークンを自動的に取得および更新し、すべてのリクエストに署名します。

インストール

npm install @intlayer/api

仕組み: オーセンティケーター + エンドポイント

SDK は、バンドルサイズを小さくするために、意図的に2つの別々のインポートに分割されています。

1. createIntlayerCMS — 軽量なオーセンティケーターを作成します。これは認証情報と管理されたアクセストークンのみを保持し、特定のドメインについては何も知りません。
2. dictionaryEndpoint、projectEndpoint、… — ドメインごとのエンドポイントバインダーで、それぞれ独自のサブパス（@intlayer/api/dictionary、@intlayer/api/project、…）からインポートされます。必要なエンドポイントにオーセンティケーターを渡します。

各エンドポイントは個別にインポートされるため、バンドルには実際に使用するドメインのみが含まれます。dictionaryEndpoint をインポートしても、プロジェクト、AI、その他のドメインクライアントがプルインされることはありません。

import { createIntlayerCMS } from "@intlayer/api";// 設定はオプションです: 省略した場合、認証情報は// `@intlayer/config/built` から読み込まれます。これは INTLAYER_CLIENT_ID および// INTLAYER_CLIENT_SECRET 環境変数を解決します。export const cmsAuthenticator = createIntlayerCMS();

WARNING

CMS の認証情報 (clientId / clientSecret) はコンテンツへの書き込みアクセスを許可します。オーセンティケーターはサーバー側（サーバーアクション、ルートハンドラー、スクリプト、CI）でのみ作成してください。クライアント側コードにインポートしたり、認証情報をブラウザに公開したりしないでください。

ビルド時の設定に依存しない場合は、認証情報を明示的に渡します。

import { createIntlayerCMS } from "@intlayer/api";export const cmsAuthenticator = createIntlayerCMS({  editor: {    clientId: process.env.INTLAYER_CLIENT_ID,    clientSecret: process.env.INTLAYER_CLIENT_SECRET,    // オプション、セルフホスティングされたバックエンドの場合:    // backendURL: process.env.INTLAYER_BACKEND_URL,  },});

認証情報は、Intlayer Dashboard - Projects で新しいアクセスキーを作成して取得できます。

プロジェクトの取得

import { createIntlayerCMS } from "@intlayer/api";import { projectEndpoint } from "@intlayer/api/project";const cmsAuthenticator = createIntlayerCMS();// 認証情報でアクセス可能なプロジェクトをリストアップconst { data: projects } =  await projectEndpoint(cmsAuthenticator).getProjects();// 選択したプロジェクトの集約されたローカライゼーションインサイトを読み取るconst { data: insights } =  await projectEndpoint(cmsAuthenticator).getProjectInsights();

辞書の取得

import { createIntlayerCMS } from "@intlayer/api";import { dictionaryEndpoint } from "@intlayer/api/dictionary";const cmsAuthenticator = createIntlayerCMS();// プロジェクトのすべてのリモート辞書をリストアップconst { data: dictionaries } =  await dictionaryEndpoint(cmsAuthenticator).getDictionaries();// またはキーで単一の辞書を取得const { data: dictionary } = await dictionaryEndpoint(  cmsAuthenticator).getDictionary("my-first-dictionary-key");

辞書のプッシュと更新

CMS をデータベースとして使用してコンテンツを書き戻します。

import { createIntlayerCMS } from "@intlayer/api";import { dictionaryEndpoint } from "@intlayer/api/dictionary";const cmsAuthenticator = createIntlayerCMS();// 新しい辞書を作成await dictionaryEndpoint(cmsAuthenticator).addDictionary({  key: "my-first-dictionary-key",  content: { title: "Hello world" },});// 辞書の一括Upsert (1回の呼び出しで作成または更新)await dictionaryEndpoint(cmsAuthenticator).pushDictionaries([  { key: "home", content: { title: "Home" } },  { key: "about", content: { title: "About" } },]);// 既存の辞書を更新await dictionaryEndpoint(cmsAuthenticator).updateDictionary({  id: "<dictionary-id>",  key: "home",  content: { title: "Updated title" },});

ヒント: 繰り返しを避けるためにバインドされたエンドポイントを再利用します。

typescript

コンテンツをコピー

コードをコピー

コードをクリップボードにコピー

const dictionary = dictionaryEndpoint(cmsAuthenticator);await dictionary.pushDictionaries([myDictionary]);const { data } = await dictionary.getDictionaries();

単一メソッドの抽出

すべてのエンドポイントメソッドはすでに認証されており、スタンドアロンであるため（独自のトークン処理を保持しているため）、1つを抽出して渡すことができます。例えば、依存関係として注入する場合などです。

import { createIntlayerCMS } from "@intlayer/api";import { dictionaryEndpoint } from "@intlayer/api/dictionary";const dictionary = dictionaryEndpoint(createIntlayerCMS());// すでに認証済み — 呼び出しごとに自動的にトークンを更新しますexport const pushDictionaries = dictionary.pushDictionaries;// 使用方法await pushDictionaries([{ key: "home", content: { title: "Home" } }]);

ライブ同期

ライブ同期は、アプリが実行時に CMS のコンテンツ変更を反映できるようにします。再ビルドや再デプロイは不要です。有効にすると、更新がライブ同期サーバーにストリームされ、アプリケーションが読み込む辞書が更新されます。

Intlayerの設定を更新してLive Syncを有効にします：

import type { IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  // ... その他の設定
  editor: {
    /**
     * 変更が検出されたときにロケール設定のホットリロードを有効にします。
     * 例えば、辞書が追加または更新された場合、アプリケーションは
     * ページに表示されるコンテンツを更新します。
     *
     * ホットリロードは継続的なサーバー接続を必要とするため、
     * `enterprise`プランのクライアントのみ利用可能です。
     *
     * デフォルト: false
     */
    liveSync: true,
  },
  dictionary: {
    /**
     * 辞書のインポート方法を制御します：
     *
     * - "fetch"：辞書はLive Sync APIを使用して動的に取得されます。
     *   useIntlayerの代わりにuseDictionaryDynamicを使用します。
     *
     * 注意：ライブモードはLive Sync APIを使用して辞書を取得します。API呼び出しが
     * 失敗した場合、辞書は動的にインポートされます。
     * 注意：リモートコンテンツかつ"live"フラグが付いた辞書のみがライブモードを使用します。
     * その他はパフォーマンスのために動的モードを使用します。
     */
    importMode: "fetch",
  },
};

export default config;

アプリケーションをラップするために Live Sync サーバーを起動します：

スタンドアロンサーバーを使用した例：

{  "scripts": {    // ... その他のスクリプト    "live:start": "npx intlayer live",  },}

--process 引数を使用して、アプリケーションサーバーと並行して使用することもできます。

Next.js を使用した例：

{  "scripts": {    // ... その他のスクリプト    "build": "next build",    "dev": "next dev",    "start": "npx intlayer live --with 'next start'",  },}

Vite を使用した例：

{  "scripts": {    // ... その他のスクリプト    "build": "vite build",    "dev": "vite dev",    "start": "npx intlayer live --with 'vite start'",  },}

Live Sync サーバーはあなたのアプリケーションをラップし、更新されたコンテンツが到着すると自動的に適用します。

CMSからの変更通知を受け取るために、Live SyncサーバーはバックエンドとのSSE接続を維持します。CMSのコンテンツが変更されると、バックエンドは更新情報をLive Syncサーバーに転送し、新しい辞書を書き込みます。アプリケーションは次のナビゲーションまたはブラウザのリロード時に更新を反映し、再ビルドは不要です。

フローチャート（CMS/バックエンド -> Live Syncサーバー -> アプリケーションサーバー -> フロントエンド）:

動作の仕組み:

開発ワークフロー（ローカル）

• 開発中は、アプリケーション起動時にすべてのリモート辞書が取得されるため、更新をすばやくテストできます。
• Next.jsでローカルにLive Syncをテストするには、開発サーバーをラップします：

{  "scripts": {    // ... 他のスクリプト    "dev": "npx intlayer live --with 'next dev'",    // "dev": "npx intlayer live --with 'vite dev'", // Vite用  },}

開発中にIntlayerがLiveインポート変換を適用するように最適化を有効にします：

import type { IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  editor: {
    applicationURL: "http://localhost:5173",
    liveSyncURL: "http://localhost:4000",
    liveSync: true,
  },
  dictionary: {
    importMode: "fetch",
  },
  build: {
    optimize: true, // default: process.env.NODE_ENV === 'production'
  },
};

export default config;

この設定により、開発サーバーがLive Syncサーバーでラップされ、起動時にリモート辞書を取得し、CMSからの更新をSSE経由でストリーミングします。変更を確認するにはページをリロードしてください。

注意事項と制約：

• Live Sync のオリジンをサイトのセキュリティポリシー（CSP）に追加してください。Live Sync の URL が connect-src（および該当する場合は frame-ancestors）で許可されていることを確認してください。
• Live Sync は静的出力では動作しません。Next.js の場合、ページはランタイムで更新を受け取るために動的である必要があります（例：完全な静的のみの制約を避けるために、generateStaticParams、generateMetadata、getServerSideProps、または getStaticProps を適切に使用してください）。
• CMSでは、各辞書にliveフラグがあります。live=trueの辞書のみがライブ同期APIを通じて取得され、それ以外は動的にインポートされ、実行時には変更されません。
• liveフラグはビルド時に各辞書ごとに評価されます。ビルド時にリモートコンテンツがlive=trueに設定されていなかった場合、その辞書のライブ同期を有効にするには再ビルドが必要です。
• ライブ同期サーバーは.intlayerに書き込み可能でなければなりません。コンテナ環境では/.intlayerへの書き込み権限を確保してください。

セルフホスティング

Intlayer は、独自のインフラストラクチャ上で完全に実行できます。Docker Compose を使用して、フルスタック（ダッシュボード、API、データベース、オブジェクトストレージ、メール）を1行でブートストラップできます。

curl -fsSL https://intlayer.org/install.sh | sh

完全なセットアップガイド、環境変数リファレンス、アップグレード手順、バックアップ/復元手順については、セルフホスティングガイドを参照してください。

デバッグ

CMSで問題が発生した場合は、以下を確認してください：

• アプリケーションが稼働していること。

• editorの設定がIntlayerの設定ファイルで正しく行われていること。

  • 必須フィールド：
    • アプリケーションのURLは、エディター設定の applicationURL と一致している必要があります。
    • CMSのURL

• プロジェクトの設定がIntlayer CMSにプッシュされていることを確認してください。

• ビジュアルエディターはiframeを使用してウェブサイトを表示します。ウェブサイトのコンテンツセキュリティポリシー（CSP）がCMSのURLを frame-ancestors（デフォルトは 'https://app.intlayer.org'）として許可していることを確認してください。エディターのコンソールでエラーがないか確認してください。