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

設定方法、Live Sync サーバーの起動、ローカル開発ワークフロー、制約事項などの完全なガイドは、Live Sync ドキュメントを参照してください。

セルフホスティング

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'）として許可していることを確認してください。エディターのコンソールでエラーがないか確認してください。