Requesting localized content with the delivery endpoint

This page describes how you can request localized content with the Delivery endpoint API.

In Magnolia REST 2.1.x, version 2 of the Delivery endpoint allows you to send an API request for a specific language variant of content.

For i18n features to work correctly, check that the fallback site has locales configured or extends a site definition with desired locales.

Specifying the language

With the Delivery endpoint, you can request a single language variant, or send lang=all in the request to return all language variants available.

To request a specific single language variant, do one of the following:

  • Set the Accept-Language header. For example: Accept-Language: de-DE

  • Set the lang`query parameter. For example: `lang=de-DE

If both are set, the lang parameter takes priority. If neither is set, the decision is delegated to the I18nContentSupport interface.

To return all language variants:

  • Set the lang query parameter to all: lang=all

You can use both the Accept-Language header and the lang query parameter for both sub-resources Read node and Query nodes.

Examples

The example requests below make use of the title and title_de properties of the /travel/about page in the Travel Demo.

Requestion localized content

The responses are returned based on the following configuration:

/<my-module>/restEndpoints/ep.yaml
$type: jcrDeliveryEndpoint_v2
workspace: website
rootPath: /
nodeTypes:
  - mgnl:page

Neither parameter

If neither the header nor the lang query parameters is used in the request, the language used for the response reflects the locale determined by the the I18nContentSupport interface.

Header Request URL JSON response

not set

/.rest/ep/travel/about

JSON response:

{
 "@name": "about",
 "@path": "/travel/about",
 "@id": "808ebe4c-72b2-49f1-b9f7-e7db22bce02f",
 "@nodeType": "mgnl:page",
 "hideInNav": "false",
 "title": "About",
 "@nodes": []
}

The language is not defined by the header or the lang parameter. The value returned for title is determined by the I18nContentSupport interface.

Both parameters

If both the header and the lang query parameters are set. The query parameter takes priority.

  • The parameter is parsed for a single language tag.

  • If the tag is a full language tag such as de-CH or en-US, and the system does not have a perfectly matching counterpart, the system selects the closest variant (de, en). See the getNextLocale method of info.magnolia.cms.i18n.AbstractI18nContentSupport.

  • If lang=all is set, all language variants are returned.

Header Request URL JSON response

Accept-Language: en-GB

/.rest/ep/travel/about?lang=de-DE

Both the header and the lang parameters are set, the lang parameter takes priority for content delivery.

{
 "@name": "about",
 "@path": "/travel/about",
 "@id": "808ebe4c-72b2-49f1-b9f7-e7db22bce02f",
 "@nodeType": "mgnl:page",
 "hideInNav": "false",
 "title": "Über uns",
 "@nodes": []
}

Accept-Language: en-GB

/.rest/ep/travel/about?lang=all

All language variants are returned since lang=all was sent in the request.

{
 "@name": "about",
 "@path": "/travel/about",
 "@id": "808ebe4c-72b2-49f1-b9f7-e7db22bce02f",
 "@nodeType": "mgnl:page",
 "hideInNav": "false",
 "title": "About",
 "title_de": "Über uns",
 "@nodes": []
}

Only the header

If only the Accept-Language header is set.

  • Server-driven content negotiation algorithms select the best match for the language tag set in the header.

  • If the value is * (wildcard), it means that any language the server may return is acceptable.

  • The value can be in the form of weighted syntax, for example Accept-Language: fr-CH, fr;q=0.9, en;q=0.8.

Header Request URL JSON response

Accept-Language: de-DE

/.rest/ep/travel/about

Server-driven content negotiation is used to select the best match for the language tag specified in the header.

{
 "@name": "about",
 "@path": "/travel/about",
 "@id": "808ebe4c-72b2-49f1-b9f7-e7db22bce02f",
 "@nodeType": "mgnl:page",
 "hideInNav": "false",
 "title": "Über uns",
 "@nodes": []
}

Only the lang parameter

If only the lang query parameter is set.

  • The parameter is parsed for a single language tag.

  • If the tag is a full language tag such as de-CH or en-US, and the system doesn’t have any perfectly matching counterpart, the system selects the closest variant (de, en). See the getNextLocale method of info.magnolia.cms.i18n.AbstractI18nContentSupport.

  • If lang=all is set, all language variants are returned.

Header Request URL JSON response

not set

/.rest/ep/travel/about?lang=de-DE

Selects the closest supported locale to that specified by the lang parameter.

{
 "@name": "about",
 "@path": "/travel/about",
 "@id": "808ebe4c-72b2-49f1-b9f7-e7db22bce02f",
 "@nodeType": "mgnl:page",
 "hideInNav": "false",
 "title": "Über uns",
 "@nodes": []
}

not set

/.rest/ep/travel/about?lang=es-ES

Responds with a fallback value since the title_es property, which could hold a Spanish translation, is not defined for the page and/or the es locale is not configured for the site.

{
 "@name": "about",
 "@path": "/travel/about",
 "@id": "808ebe4c-72b2-49f1-b9f7-e7db22bce02f",
 "@nodeType": "mgnl:page",
 "hideInNav": "false",
 "title": "About",
 "@nodes": []
}
Related topics
Feedback

Headless

×

Location

This widget lets you know where you are on the docs site.

You are currently perusing through the Headless docs.

Main doc sections

DX Core Headless PaaS Legacy Cloud Incubator modules