メインコンテンツまでスキップ

Document Service API: locale パラメータ

既定では、Document Service API はドキュメントの既定ロケール版を返します（アプリで別の既定ロケールを設定していなければ 'en'、つまり英語版です。Internationalization (i18n) を参照）。このページでは、特定のロケールだけを対象にデータを取得・更新するために locale をどう使うかを説明します。

findOne() でロケール版を取得する​

locale を渡すと、Document Service API の findOne() メソッド は、そのロケールのドキュメント版を返します。

Example request
await strapi.documents('api::restaurant.restaurant').findOne({
  documentId: 'a1b2c3d4e5f6g7h8i9j0klm',
  locale: 'fr',
});
Example response
{
  documentId: "a1b2c3d4e5f6g7h8i9j0klm",
  name: "Biscotte Restaurant",
  publishedAt: null, // draft version (default)
  locale: "fr", // パラメータで指定したロケール
  // …
}

status を省略すると、既定で draft 版が返ります。

findFirst() でロケール版を取得する​

Document Service API で 最初に一致するドキュメントを取得 するとき、特定のロケール版を返す例です。

リクエスト例
const document = await strapi.documents('api::article.article').findFirst({
  locale: 'fr',
});
レスポンス例
{
  "documentId": "cjld2cjxh0000qzrmn831i7rn",
  "title": "Test Article"
  // …
}

status を省略すると、既定で draft 版が返ります。

findMany() でロケール版を取得する​

findMany() メソッド に locale を渡すと、そのロケールが存在するドキュメントがすべて返ります。

status を省略すると、既定で各ドキュメントの draft 版が返ります。

Example request
// status: draft が既定
await strapi.documents('api::restaurant.restaurant').findMany({ locale: 'fr' });
Example response
[
  {
    documentId: 'a1b2c3d4e5f6g7h8i9j0klm',
    name: 'Restaurant Biscotte',
    publishedAt: null,
    locale: 'fr',
    // …
  },
  // …
];
補足説明:

次の 4 ドキュメントがあり、ロケールの組み合わせがそれぞれ異なるとします。

  • ドキュメント A:
    • en
    • fr
    • it
  • ドキュメント B:
    • en
    • it
  • ドキュメント C:
    • fr
  • ドキュメント D:
    • fr
    • it

findMany({ locale: 'fr' }) は、fr 版を持つドキュメント A、C、D について、それぞれの下書き版だけを返します。

ロケール向けに create() する​

特定ロケール用のドキュメントを作成するには、Document Service API の create メソッド に locale を渡します。

スペイン語ロケールの下書きを作成
await strapi.documents('api::restaurant.restaurant').create({
  locale: 'es', // 省略すると既定ロケールの下書きが作成される
  data: { name: 'Restaurante B' },
})
Example response
{
  documentId: "pw2s0nh5ub1zmnk0d80vgqrh",
  name: "Restaurante B",
  publishedAt: null,
  locale: "es"
  // …
}

ロケール版を update() する​

ドキュメントの特定ロケール版だけを更新するには、Document Service API の update() メソッド に locale を渡します。

スペイン語ロケールを更新
await strapi.documents('api::restaurant.restaurant').update({
  documentId: 'a1b2c3d4e5f6g7h8i9j0klm',
  locale: 'es',
  data: { name: 'Nuevo nombre del restaurante' },
});
Example response
{
  documentId: "a1b2c3d4e5f6g7h8i9j0klm",
  name: "Nuevo nombre del restaurante",
  locale: "es",
  publishedAt: null,
  // …
}

ロケール版を delete() する​

Document Service API の delete() メソッド で locale を使うと、一部のロケールだけを削除できます。status を明示しない限り、下書きと公開版の両方が削除されます。

1 つのロケール版を削除​

await strapi.documents('api::restaurant.restaurant').delete({
  documentId: 'a1b2c3d4e5f6g7h8i9j0klm',
  locale: 'es',
});

すべてのロケール版を削除​

locale にはワイルドカード * が使え、ドキュメントのすべてのロケール版を削除できます。

Example request
await strapi.documents('api::restaurant.restaurant').delete({
  documentId: 'a1b2c3d4e5f6g7h8i9j0klm',
  locale: '*',
}); // 存在するすべてのロケール
レスポンス例
{
  "documentId": "a1b2c3d4e5f6g7h8i9j0klm",
  "versions": [
    {
      "title": "Test Article"
    }
  ]
}

ロケール版を publish() する​

Document Service API の publish() メソッド で、特定のロケール版だけを公開するには locale を渡します。

1 つのロケール版を公開​

フランス語ロケールを公開
await strapi.documents('api::restaurant.restaurant').publish({
  documentId: 'a1b2c3d4e5f6g7h8i9j0klm',
  locale: 'fr',
});
Example response
{
  versions: [
    {
      documentId: 'a1b2c3d4e5f6g7h8i9j0klm',
      name: 'Restaurant Biscotte',
      publishedAt: '2024-03-14T18:38:05.674Z',
      locale: 'fr',
      // …
    },
  ];
}

すべてのロケール版を公開​

locale に * を渡すと、ドキュメントのすべてのロケール版を公開できます。

すべてのロケールを公開
await strapi
  .documents('api::restaurant.restaurant')
  .publish({ documentId: 'a1b2c3d4e5f6g7h8i9j0klm', locale: '*' });
Example response
{
  "versions": [
    {
      "documentId": "a1b2c3d4e5f6g7h8i9j0klm",
      "publishedAt": "2024-03-14T18:45:21.857Z",
      "locale": "en"
      // …
    },
    {
      "documentId": "a1b2c3d4e5f6g7h8i9j0klm",
      "publishedAt": "2024-03-14T18:45:21.857Z",
      "locale": "es"
      // …
    },
    {
      "documentId": "a1b2c3d4e5f6g7h8i9j0klm",
      "publishedAt": "2024-03-14T18:45:21.857Z",
      "locale": "fr"
      // …
    }
  ]
}

ロケール版を unpublish() する​

Document Service API の unpublish() メソッド で、特定のロケール版だけの公開を取り下げるには locale を渡します。

1 つのロケール版の公開を取り下げ​

フランス語ロケールの公開を取り下げ
await strapi
  .documents('api::restaurant.restaurant')
  .unpublish({ documentId: 'a1b2c3d4e5f6g7h8i9j0klm', locale: 'fr' });
Example response
{
  versions: 1;
}

すべてのロケール版の公開を取り下げ​

locale に * を渡すと、ドキュメントのすべてのロケール版の公開を取り下げられます。

すべてのロケールの公開を取り下げ
await strapi
  .documents('api::restaurant.restaurant')
  .unpublish({ documentId: 'a1b2c3d4e5f6g7h8i9j0klm', locale: '*' });
Example response
{
  versions: 3;
}
リクエスト例
const document = await strapi.documents('api::article.article').unpublish({
  documentId: 'cjld2cjxh0000qzrmn831i7rn',
  fields: ['title'],
});
レスポンス例
{
  "documentId": "cjld2cjxh0000qzrmn831i7rn",
  "versions": [
    {
      "title": "Test Article"
    }
  ]
}

ロケール版で discardDraft() する​

Document Service API の discardDraft() メソッド で、一部のロケールについてだけ下書きを破棄するには locale を渡します。

1 つのロケール版の下書きを破棄​

そのロケールの公開版の内容で下書きを上書きするには、discardDraft() に locale を渡します。

フランス語ロケールの下書きを破棄
await strapi
  .documents('api::restaurant.restaurant')
  .discardDraft({ documentId: 'a1b2c3d4e5f6g7h8i9j0klm', locale: 'fr' });
Example response
{
  versions: [
    {
      documentId: 'a1b2c3d4e5f6g7h8i9j0klm',
      name: 'Restaurant Biscotte',
      publishedAt: null,
      locale: 'fr',
      // …
    },
  ];
}

すべてのロケール版の下書きを破棄​

locale に * を渡すと、各ロケールについて下書きを破棄し、公開版のデータで置き換えられます。

すべてのロケールの下書きを破棄
await strapi
  .documents('api::restaurant.restaurant')
  .discardDraft({ documentId: 'a1b2c3d4e5f6g7h8i9j0klm', locale: '*' });
Example response
{
  versions: [
    {
      documentId: 'a1b2c3d4e5f6g7h8i9j0klm',
      name: 'Biscotte Restaurant',
      publishedAt: null,
      locale: 'en',
      // …
    },
    {
      documentId: 'a1b2c3d4e5f6g7h8i9j0klm',
      name: 'Restaurant Biscotte',
      publishedAt: null,
      locale: 'fr',
      // …
    },
    {
      documentId: 'a1b2c3d4e5f6g7h8i9j0klm',
      name: 'Biscotte Restaurante',
      publishedAt: null,
      locale: 'es',
      // …
    },
  ];
}

ロケールごとに count() する​

特定ロケールのドキュメント数を数えるには、Document Service API の count() メソッド に locale と他のパラメータを渡します。

status を省略すると、下書きが数えられます（公開済みも下書き版があるものとして数えるため、ロケール内の利用可能ドキュメント総数に相当します）。

// フランス語ロケールのドキュメント数（status 省略時は下書きベースの総数）
await strapi.documents('api::restaurant.restaurant').count({ locale: 'fr' });
このページを編集