Problem/Motivation
The JSON:API client can only target a translation through a /{locale}/ URL path prefix. That works for a stock multilingual site using URL language negotiation. Sites using the JSON:API Multilingual module select the translation on the canonical URL via a langCode query parameter that is not dependent on the site's language negotiation settings.
Proposed resolution
- Reads send the language as a
langCodequery parameter and, for backwards compatibility with URL-prefix negotiation, as the/{locale}/path prefix. Stock backends ignore the parameter (a spec-valid implementation-specific query parameter) and negotiate by prefix; backends usingjsonapi_multilingualselect the translation with the parameter alone, so the same request works on either backend. With the module, a read of a translation that does not exist is a strict 404 (individual) or excludes the item (collection, reported undermeta.omitted). - A new
includeFallbackread option sendsincludeFallback=1, deferring a missing translation to the site's language fallback chain instead of failing strictly: an individual read of existing content always resolves, and a collection includes every item in its best available language. Ignored by stock backends. - A new instance option
languagePathPrefix: falseallows dropping the prefix entirely (including from collection POSTs and thedecoupled_routerhop ofgetResourceByPath). Recommended for backends usingjsonapi_multilingual, where the langCode query parameter carries the language; required for backends that do not serve/{locale}/URLs. - Writes target exactly one translation:
updateResource/deleteResourcesend the prefix plus a langCode query parameter. - A new
createTranslation()method adds a translation to an existing entity via an individual-path POST. - A new
getAvailableTranslations()helper extracts themeta.availableTranslationslangcodes that a strict backend's 404 advertises, for retrying with an existing language or rendering a language switcher. getResourceByPath()uses the resolved translation's language (theentity.langcodethatjsonapi_multilingualadds to translate-path responses) as the follow-up read's locale when the caller does not pass one, so translated aliases return the translation they name.
Remaining tasks
User interface changes
API changes
API changes explained in Proposed resolution, changes are fully backwards compatible.
Data model changes
Issue fork api_client-3612682
Show commands
Start within a Git clone of the project using the version control instructions.
Or, if you do not have SSH keys set up on git.drupalcode.org:
Comments
Comment #3
lauriiiComment #4
brianperryMerged and published on npm. Thanks again @lauriii and @mglaman!