The 5.7 branch of Magnolia reached End-of-Life on December 31, 2023, as specified in our End-of-life policy. This means the 5.7 branch is no longer maintained or supported. Please upgrade to the latest Magnolia release. By upgrading, you will get the latest release of Magnolia featuring significant improvements to the author and developer experience. For a successful upgrade, please consult our Magnolia 6.2 documentation. If you need help, please contact info@magnolia-cms.com.
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. This is different from the previous implementation (REST 2.0.x), in which the endpoint version 1 always delivered all language variants available in the JCR repository.
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 endpoint v2, you can request a single language variant, or send To request a specific single language variant, do one of the following: 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: You can use both the lang=all
in the request to return all language variants available. Accept-Language: de-DE
lang
query parameter. For example: lang=de-DE
lang
query parameter to all: lang=all
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.
The reponses are returned based on the following configuration:
class: info.magnolia.rest.delivery.jcr.v2.JcrDeliveryEndpointDefinition workspace: website rootPath: / nodeTypes: - mgnl:page includeSystemProperties: false
Neither parameter
If neither the header or the lang query parameters is used in the request, the language used for the response refelcts the locale determined by the the I18nContentSupport interface.
Accept-Language header | Request URL | JSON response |
---|---|---|
not set |
| { "@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 |
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
oren-US
, and the system does not have a perfectly matching counterpart, the system selects the closest variant (de
,en
). See thegetNextLocale
method of AbstractI18nContentSupport. - If
lang=all
is set all language variants are returned.
Accept-Language header | Request URL | JSON response |
---|---|---|
Accept-Language: en-GB |
| { "@name": "about", "@path": "/travel/about", "@id": "808ebe4c-72b2-49f1-b9f7-e7db22bce02f", "@nodeType": "mgnl:page", "hideInNav": "false", "title": "Über uns", "@nodes": [] } Both the header and the |
Accept-Language: en-GB |
| { "@name": "about", "@path": "/travel/about", "@id": "808ebe4c-72b2-49f1-b9f7-e7db22bce02f", "@nodeType": "mgnl:page", "hideInNav": "false", "title": "About", "title_de": "Über uns", "@nodes": [] } All language variants are returned since |
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
.
Accept-Language header | Request URL | JSON response |
---|---|---|
|
| { "@name": "about", "@path": "/travel/about", "@id": "808ebe4c-72b2-49f1-b9f7-e7db22bce02f", "@nodeType": "mgnl:page", "hideInNav": "false", "title": "Über uns", "@nodes": [] } Server-driven content negotiation is used to select the best match for the language tag specified in the header. |
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
oren-US
, and the system doesn't have any perfectly matching counterpart, the system selects the closest variant (de
,en
). See thegetNextLocale
method of AbstractI18nContentSupport. - If
lang=all
is set all language variants are returned.
Accept-Language header | Request URL | JSON response |
---|---|---|
Not set |
| { "@name": "about", "@path": "/travel/about", "@id": "808ebe4c-72b2-49f1-b9f7-e7db22bce02f", "@nodeType": "mgnl:page", "hideInNav": "false", "title": "Über uns", "@nodes": [] } Selects the closest supported locale to that specified by the |
Not set |
| { "@name": "about", "@path": "/travel/about", "@id": "808ebe4c-72b2-49f1-b9f7-e7db22bce02f", "@nodeType": "mgnl:page", "hideInNav": "false", "title": "About", "@nodes": [] } Responds with a fallback value since the |