i18n REST API

There are two i18n API endpoints to facilitate content management in a multilingual ApostropheCMS project.

These APIs are part of the implementation of the built-in admin UI and are generally not necessary if you just want to manipulate documents in a particular locale. For such operations, it's recommended to use the piece and page REST APIs. You can find more information about these APIs and how to use them for document manipulation in different locales here and here.

Endpoints

Authentication is required for all REST API requests.

REST endpoints

Method	Path	Description
GET	/api/v1/@apostrophecms/i18n/locales	Returns information about all configured locales.
POST	/api/v1/@apostrophecms/i18n/locale	Returns the path to a locale home-page or optional document id and makes the clipboard available in the given locale.
POST	/api/v1/@apostrophecms/i18n/exist-in-locale	Returns arrays of the original document id(s), new locale id(s), and aposDocId(s) for an array of document id(s) and a locale.

GET /api/v1/@apostrophecms/i18n/locales

Query parameters

None.

Request example

// Request inside an async function.
const response = await fetch('https://example.net/api/v1/@apostrophecms/i18n/locales', {});
const locales = await response.json();

Response

A successful response will contain an object as follows:

{
  "en": {
    "label": "English",
    "_edit": true
  },
  "fr": {
    "label": "French",
    "_edit": false
  }
}

Note that for each locale the response indicates both the label and whether the current user is permitted to edit content in this locale at all.

This API has been made public in order to facilitate the creation of locale switcher UI in headless applications.

POST /api/v1/@apostrophecms/i18n/locale

Query parameters

Parameter	Example	Description
contextDocId	?contextDocId=cloydg3ka0005qcls5vmg8sb9	An optional document id for the path, defaults to the locale home-page.
locale	?locale=fr	Required. The locale for the desired path.
clipboard	?clipboard=exampleClipboardContent	Optional string. Move clipboard contents from localStorage to the cross-domain session cache.

Request example

// Request inside an async function.
const response = await fetch('https://example.net/api/v1/@apostrophecms/i18n/locale', {
  method: 'POST'
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer your_api_key'
  },
  body: JSON.stringify({
    locale: 'fr',
    clipboard: 'exampleClipboardContent',
    contextDocId: 'cloydg3ka0005qcls5vmg8sb9'
  })
});
const document = await response.json();

Response

A successful POST response will return the path to the document in the supplied locale with the supplied contextDocId, or the home page path if no id is provided.

The clipboard content must be a string and only needs to be supplied in cross-domain situations where the target locale's hostname differs from the current locale's hostname. For example, https://fr.example.com/french-example-page versus https://example.com/english-example-page. In this case a aposCrossDomainSessionToken key will be supplied as a query parameter on the returned path If the locales share the same hostname but different paths (e.g., https://example.com/fr/french-example-page and https://example.com/en/english-example-page), the clipboard content will not be cached.

Same hostname response:

{
  "redirectTo": "/fr/page-slug"
}

Different hostname response

{
  "redirectTo": "https://fr.example.com/french-example-page?aposCrossDomainSessionToken=generated_token"
}

This token can then be used to retrieve the clipboard contents from the apostrophe cache:

const clipboard = await self.apos.cache.get('@apostrophecms/i18n:cross-domain-sessions', generated_token);

POST /api/v1/@apostrophecms/i18n/exist-in-locale

Query parameters

Parameter	Example	Description
ids	?ids=cloydg3ka0005qcls5vmg8sb9,cloydg3ka0005qcls5vmg8sb8	Required. An array of document IDs to check in the specified locale.
locale	?locale=fr	Required. The locale in which to check for the document IDs.
mode	?mode=published	Required. The mode (e.g., draft or published) in which to check for the document IDs.

Request example

// Request inside an async function.
const response = await fetch('https://example.net/api/v1/@apostrophecms/i18n/exist-in-locale', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer your_api_key'
  },
  body: JSON.stringify({
    ids: ['cloydg3ka0005qcls5vmg8sb9', 'cloydg3ka0005qcls5vmg8sb8'],
    locale: 'fr',
    mode: 'published'
  })
});
const result = await response.json();

Response

A successful POST response will return an object with arrays indicating the status of the provided document IDs in the specified locale and mode.

Response Structure:

{
  "originalLocaleIds": ["originalLocaleId1", "originalLocaleId2"],
  "newLocaleIds": ["newLocaleId1", "newLocaleId2"],
  "aposDocIds": ["aposDocId1", "aposDocId2"]
}

• originalLocaleIds: Array of document IDs in the original locale and mode.
• newLocaleIds: Array of document IDs in the new locale.
• aposDocIds: Array of aposDocId values for the documents.

Example Response

{
  "originalLocaleIds": ["cloydg3ka0005qcls5vmg8sb9:en:published", "cloydg3ka0005qcls5vmg8sb8:en:published"],
  "newLocaleIds": ["cloydg3ka0005qcls5vmg8sb9:fr:published", "cloydg3ka0005qcls5vmg8sb8:fr:published"],
  "aposDocIds": ["cloydg3ka0005qcls5vmg8sb9", "cloydg3ka0005qcls5vmg8sb8"]
}

This endpoint is useful for verifying the existence of documents in a given locale and mode.