Skip to main content

🌍 国際化（i18n）

国際化（i18n）機能は、AI Marketerユーザーが「ロケール」と呼ばれる異なる言語でローカライズされたコンテンツを作成、管理、配布することを可能にします。国際化の概念についての詳細は、W3Cの定義を参照してください。

i18n機能は次のような特長を持っています：

  • 管理パネルのユーザーが自分のコンテンツの複数のローカライズ版を作成することを可能にします（ユーザーガイドを参照）
  • 開発者が視聴者の国/言語に応じて適切なコンテンツを取得し、使用するローカライズプロジェクトを構築することを可能にします。
👀 Info

i18n機能はユーザーのコンテンツを自動的に翻訳したり、管理インターフェースを言語の特性に合わせて調整したりすることはありません（例えば、管理パネルを右から左へのフォーマットで表示するなど）。

✏️ メモ

デフォルトロケールの設定​

AI Marketer_PLUGIN_I18N_INIT_LOCALE_CODE [環境変数](/dev-docs/configurations/environment#AI Marketer-s-environment-variables)を設定して、環境のデフォルトロケールを設定することができます。この変数に使用する値はISO国コードであるべきです（[利用可能なロケールの完全なリスト](https://github.com/AI Marketer/AI Marketer/blob/v4.0.0/packages/plugins/i18n/server/constants/iso-locales.json)を参照）。

これは、AI Marketerアプリケーションが本番環境にデプロイされ、初めてコンテンツタイプにi18n機能がインストールされ、有効化されたときに有用です。新規のi18nインストールでは、enがデフォルトのロケールとして設定されます。データベースにロケールが含まれておらず、環境にAI Marketer_PLUGIN_I18N_INIT_LOCALE_CODEが設定されていない場合、ローカライゼーションが有効になっているコンテンツタイプのすべてのドキュメントは自動的にenロケールに移行されます。

REST APIでlocaleを使用する​

国際化（i18n）機能は、REST APIに新たな機能を追加します。

:::事前条件 ロケールのAPIコンテンツを操作するには、そのロケールがすでにAI Marketerの管理パネルに追加されていることを確認してください。 :::

locale APIパラメータは、指定したロケールのみのドキュメントを操作するために使用できます。localeはロケールコードを値として取ります（[利用可能なロケールの全リスト](https://github.com/AI Marketer/AI Marketer/blob/v4.0.0/packages/plugins/i18n/server/constants/iso-locales.json)を参照）。

💡 Tip

localeパラメータが定義されていない場合、デフォルトのロケールに設定されます。新しいAI Marketerプロジェクトが作成されたときのデフォルトのロケールはenですが、管理パネルでデフォルトのロケールを設定することもできます。

例えば、デフォルトでは、/api/restaurantsへのGETリクエストは/api/restaurants?locale=enへのリクエストと同じレスポンスを返します。

次の表は、REST APIにi18nによって追加された新しい使用ケースをリストし、構文例を示しています（リクエストをクリックすると、詳細を含む対応するセクションにジャンプします）：

使用ケース構文例
および詳細リンク
特定のロケールのすべてのドキュメントを取得するGET /api/restaurants?locale=fr
ドキュメントの特定のロケールバージョンを取得するGET /api/restaurants/abcdefghijklmno456?locale=fr
デフォルトのロケールで新しいドキュメントを作成するPOST /api/restaurants
+ リクエスト本文で属性を渡す
特定のロケールで新しいドキュメントを作成するPOST /api/restaurants
+ リクエスト本文で属性およびロケールを渡す
既存のドキュメントの新しいロケールバージョンを作成する、または既存のロケールバージョンを更新するPUT /api/restaurants/abcdefghijklmno456?locale=fr
+ リクエスト本文で属性を渡す
ドキュメントの特定のロケールバージョンを削除するDELETE /api/restaurants/abcdefghijklmno456?locale=fr

特定のロケールのすべてのドキュメントを取得する​

Example request

GET http://localhost:1337/api/restaurants?locale=fr

Example response
{
  "data": [
    {
      "id": 5,
      "documentId": "h90lgohlzfpjf3bvan72mzll",
      "Title": "Meilleures pizzas",
      "Body": [
        {
          "type": "paragraph",
          "children": [
            {
              "type": "text",
              "text": "On déguste les meilleures pizzas de la ville à la Pizzeria Arrivederci."
            }
          ]
        }
      ],
      "createdAt": "2024-03-06T22:08:59.643Z",
      "updatedAt": "2024-03-06T22:10:21.127Z",
      "publishedAt": "2024-03-06T22:10:21.130Z",
      "locale": "fr"
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "pageSize": 25,
      "pageCount": 1,
      "total": 1
    }
  }
}

特定のロケールのドキュメントを取得する​

特定のロケールの特定のドキュメントを取得するには、クエリにlocaleパラメータを追加します：

ユースケース構文形式と詳細情報のリンク
コレクションタイプでGET /api/content-type-plural-name/document-id?locale=locale-code
シングルタイプでGET /api/content-type-singular-name?locale=locale-code

コレクションタイプ​

特定のロケールのコレクションタイプの特定のドキュメントを取得するには、documentIdの後にlocaleパラメータをクエリに追加します：

Example request

GET /api/restaurants/lr5wju2og49bf820kj9kz8c3?locale=fr

Example response
{
  "data": [
    {
      "id": 22,
      "documentId": "lr5wju2og49bf820kj9kz8c3",
      "Name": "Biscotte Restaurant",
      "Description": [
        {
          "type": "paragraph",
          "children": [
            {
              "type": "text",
              "text": "Bienvenue au restaurant Biscotte! Le Restaurant Biscotte propose une cuisine à base de produits frais et de qualité, souvent locaux, biologiques lorsque cela est possible, et toujours produits par des producteurs passionnés."
            }
          ]
        }
      ],
      // …
      "locale": "fr"
    },
    // …
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "pageSize": 25,
      "pageCount": 1,
      "total": 3
    }
  }
}

シングルタイプ​

特定のロケールのシングルタイプのドキュメントを取得するには、シングルタイプ名の後にlocaleパラメータをクエリに追加します：

Example request

GET /api/homepage?locale=fr

Example response
{
  "data": {
    "id": 10,
    "documentId": "ukbpbnu8kbutpn98rsanyi50",
    "Title": "ホームページ",
    "Body": null,
    "createdAt": "2024-03-07T13:28:26.349Z",
    "updatedAt": "2024-03-07T13:28:26.349Z",
    "publishedAt": "2024-03-07T13:28:26.353Z",
    "locale": "fr"
  },
  "meta": {}
}

コレクションタイプの新しいローカライズドドキュメントを作成する​

ローカライズされたドキュメントをゼロから作成するには、Content APIにPOSTリクエストを送信します。デフォルトのロケール用に作成するか、別のロケール用に作成するかによって、リクエストのボディにlocaleパラメータを渡す必要があるかもしれません。

ユースケースシンタックス形式と詳細情報へのリンク
デフォルトのロケール用に作成するPOST /api/content-type-plural-name
特定のロケール用に作成するPOST /api/content-type-plural-name
+ リクエストボディにロケールを渡す

デフォルトのロケール用​

リクエストボディにロケールが渡されていない場合、ドキュメントはアプリケーションのデフォルトのロケールを使用して作成されます：

Example request

POST http://localhost:1337/api/restaurants

{
  "data": {
    "Name": "Oplato",
  }
}
Example response
{
  "data": {
    "id": 13,
    "documentId": "jae8klabhuucbkgfe2xxc5dj",
    "Name": "Oplato",
    "Description": null,
    "createdAt": "2024-03-06T22:19:54.646Z",
    "updatedAt": "2024-03-06T22:19:54.646Z",
    "publishedAt": "2024-03-06T22:19:54.649Z",
    "locale": "en"
  },
  "meta": {}
}

特定のロケール用​

デフォルトとは異なるロケールのローカライズエントリを作成するには、POSTリクエストのボディにlocale属性を追加します：

Example request

POST http://localhost:1337/api/restaurants

{
  "data": {
    "Name": "She's Cake",
    "locale": "fr"
  }
}
Example response
{
  "data": {
    "id": 15,
    "documentId": "ldcmn698iams5nuaehj69j5o",
    "Name": "She's Cake",
    "Description": null,
    "createdAt": "2024-03-06T22:21:18.373Z",
    "updatedAt": "2024-03-06T22:21:18.373Z",
    "publishedAt": "2024-03-06T22:21:18.378Z",
    "locale": "en"
  },
  "meta": {}
}

既存のドキュメントの新しいロケールバージョンを作成する、または既存のロケールバージョンを更新する​

既存のドキュメントに対して送信されるPUTリクエストを使用すると、以下のことができます：

  • ドキュメントの別のロケールバージョンを作成する
  • 既存のロケールバージョンのドキュメントを更新する

適切なURLにPUTリクエストを送信し、クエリURLにlocale=your-locale-codeパラメータを追加し、リクエストのボディ内のdataオブジェクトに属性を渡します：

ユースケース構文フォーマットと詳細情報へのリンク
コレクションタイプでPUT /api/content-type-plural-name/document-id?locale=locale-code
シングルタイプでPUT /api/content-type-singular-name?locale=locale-code
✋ Caution

既存のローカライズされたエントリーのローカライズを作成する場合、リクエストのボディはローカライズされたフィールドのみを受け入れることができます。

💡 Tip

Content-TypeはcreateLocalization権限が有効になっている必要があります。そうでない場合、リクエストは403: Forbiddenステータスを返します。

✏️ Note

既存のローカライズされたエントリーのロケールを変更することはできません。ローカライズされたエントリーを更新する際に、リクエストのボディにlocale属性を設定しても無視されます。

コレクションタイプで​

コレクションタイプの既存のドキュメントに新しいロケールを作成するには、documentIdの後にlocaleパラメータをクエリに追加し、リクエストのボディにデータを渡します。

例: 既存のレストランにフランス語のロケールを作成

PUT http://localhost:1337/api/restaurants/lr5wju2og49bf820kj9kz8c3?locale=fr

{
  data: {
    "Name": "She's Cake in French",
  }
}
Example response
{
  "data": {
    "id": 19,
    "documentId": "lr5wju2og49bf820kj9kz8c3",
    "Name": "She's Cake in French",
    "Description": null,
    "createdAt": "2024-03-07T12:13:09.551Z",
    "updatedAt": "2024-03-07T12:13:09.551Z",
    "publishedAt": "2024-03-07T12:13:09.554Z",
    "locale": "fr"
  },
  "meta": {}
}

シングルタイプで​

既存のシングルタイプドキュメントに新しいロケールを作成するには、シングルタイプ名の後にlocaleパラメータをクエリに追加し、リクエストのボディにデータを渡します。

例: 既存のHomepageシングルタイプにFRロケールを作成

PUT http://localhost:1337/api/homepage?locale=fr

{
  "data": {
    "Title": "Page d'accueil"
  }
}
Example response
{
  "data": {
    "id": 10,
    "documentId": "ukbpbnu8kbutpn98rsanyi50",
    "Title": "Page d'accueil",
    "Body": null,
    "createdAt": "2024-03-07T13:28:26.349Z",
    "updatedAt": "2024-03-07T13:28:26.349Z",
    "publishedAt": "2024-03-07T13:28:26.353Z",
    "locale": "fr"
  },
  "meta": {}
}

ドキュメントのロケール版を削除する​

ドキュメントのロケール版を削除するには、適切なlocaleパラメータを付けてDELETEリクエストを送信します。

DELETEリクエストは成功時にのみ204のHTTPステータスコードを送信し、レスポンスボディにはデータは返されません。

コレクションタイプでの削除​

コレクションタイプのドキュメントの特定のロケールバージョンのみを削除するには、documentIdの後にlocaleパラメータをクエリに追加します：

Example request

DELETE /api/restaurants/abcdefghijklmno456?locale=fr

シングルタイプでの削除​

シングルタイプのドキュメントの特定のロケールバージョンのみを削除するには、シングルタイプ名の後にlocaleパラメータをクエリに追加します：

Example request

DELETE /api/homepage?locale=fr

GraphQL APIでのlocaleの使用​

i18n機能は、GraphQL APIに新しい機能を追加します：

  • localeフィールドがGraphQLスキーマに追加されます。
  • GraphQLは以下の用途で使用できます：
    • locale引数を使用して特定のロケールのドキュメントをクエリする
    • 特定のロケールのドキュメントを作成、更新、削除するためのミューテーション

特定のロケールのすべてのドキュメントを取得する​

特定のロケールのすべてのドキュメントを取得するには、クエリにlocale引数を渡します：

Example request
query {
  restaurants(locale: "fr") {
    documentId
    name
    locale
  }
}
Example response
{
  "data": {
    "restaurants": [
      {
        "documentId": "a1b2c3d4e5d6f7g8h9i0jkl",
        "name": "Restaurant Biscotte",
        "locale": "fr"
      },
      {
        "documentId": "m9n8o7p6q5r4s3t2u1v0wxyz",
        "name": "Pizzeria Arrivederci",
        "locale": "fr"
      },
    ]
  }
}

特定のロケールのドキュメントを取得する​

特定のロケールのドキュメントを取得するには、クエリにdocumentIdとlocale引数を渡します：

Example query
query Restaurant($documentId: ID!, $locale: I18NLocaleCode) {
  restaurant(documentId: "a1b2c3d4e5d6f7g8h9i0jkl", locale: "fr") {
    documentId
    name
    description
    locale
  }
}
Example response
{
  "data": {
    "restaurant": {
      "documentId": "lviw819d5htwvga8s3kovdij",
      "name": "Restaurant Biscotte",
      "description": "Bienvenue au restaurant Biscotte!",
      "locale": "fr"
    }
  }
}

新しいローカライズされたドキュメントの作成​

localeフィールドを渡して、特定のロケールのローカライズされたドキュメントを作成することができます（GraphQLでのミューテーションについての詳細は、GraphQL APIドキュメンテーションを参照してください）。

例：フランス語ロケールで新しいレストランを作成
mutation CreateRestaurant($data: RestaurantInput!, $locale: I18NLocaleCode) {
  createRestaurant(
    data: {
      name: "Brasserie Bonjour",
      description: "ここにフランス語の説明を入力"
    },
    locale: "fr"
  ) {
  documentId
  name
  description
  locale
}

特定のロケールのドキュメントを更新する​

locale 引数をミューテーションに渡すことで、特定のロケールのドキュメントを更新できます（GraphQLのミューテーションについての詳細は、GraphQL APIドキュメンテーションを参照してください）。

例：フランス語ロケールのレストランの説明フィールドを更新
mutation UpdateRestaurant($documentId: ID!, $data: RestaurantInput!, $locale: I18NLocaleCode) {
  updateRestaurant(
    documentId: "a1b2c3d4e5d6f7g8h9i0jkl"
    data: {
      description: "フランス語の新しい説明"
    },
    locale: "fr"
  ) {
  documentId
  name
  description
  locale
}

ドキュメントのロケールを削除する​

locale 引数をミューテーションに渡すことで、ドキュメントの特定のローカライゼーションを削除できます：

mutation DeleteRestaurant($documentId: ID!, $locale: I18NLocaleCode) {
  deleteRestaurant(documentId: "xzmzdo4k0z73t9i68a7yx2kk", locale: "fr") {
    documentId
  }
}