[META] Formalize translations support

Created on 2 September 2016, almost 8 years ago
Updated 23 October 2023, 8 months ago

Problem/Motivation

JSON:API does not fully support translatable content entities, for instance https://github.com/jsdrupal/drupal-admin-ui will need this.

Regarding GET support, JSON:API already has implicit translation support, that is /fr/jsonapi/node/article/UUID will return a JSON:API response containing the French translation of the given article. The problem with this is that it depends on and varies by each site's language negotiation configuration. This means translations may behave differently on Drupal-powered JSON:API instances A versus B. This is suboptimal because:

  • it violates the assumption that one JSON:API instance works the same as another
  • it makes it hard (potentially impossible) to write client libraries that can be reused across projects by the community
  • it makes it impossible to standardize in a JSON:API profile (coming in the upcoming 1.1 version of the JSON:API specification).
  • it results in automagic fallback behavior in edge cases that may be fine for HTML use cases but not for JSON:API use cases (see @corbacho in #69 for a concrete example)

CUD operations on translations have little to no support, at the moment (see #80-#89 and #3038308: Avoid translations DELETE data loss and unintended changes with PATCH and test all methods against entity route parameter translation upcasting → ).

Proposed resolution

Define a single, non-configurable, well-defined language negotiation mechanism. That defines JSON:API's responses in the edge cases of requesting a non-existing translation and a non-existing langcode. Implement full CUD translation support on top of that.

The following specification covers individual operations (see #100-#109 for the related discussion):

https://github.com/gabesullice/drupal-jsonapi-translations/blob/master/i...

This issue cannot remove the current automatic behavior (that'd be too disruptive), but users would have to update to the formal/official mechanism if they want the edge cases to be handled in a consistent, sensible manner. Instead this will introduce a new experimental module (JSON:API Translation), implementing all the new/missing logic. This would allow people to opt-in without requiring any additional configuration. The goal would be to deprecate the legacy (GET) logic and merge the module into JSON:API in D10.

Remaining tasks

How collections should behave is still being discussed (see #69 and #110).

Done

🌱 Plan
Status

Needs work

Version

11.0 🔥

Component
JSON API  →

Last updated 2 days ago

Created by

🇫🇷France gabesullice 🇫🇷 ①③ UTC+2

Live updates comments and jobs are added and updated live.
  • Needs documentation

    A documentation change is requested elsewhere. For Drupal core (and possibly other projects), once the change has been committed, this status should be recorded in a change record node.

Sign in to follow issues

Comments & Activities

Not all content is available!

It's likely this issue predates Contrib.social: some issue and comment data are missing.

  • 🇵🇱Poland Pozi

    I am new to the topic and was able to add new translation by commenting out those lines from #126 patch:

        if ($resource_langcode !== $parsed_langcode) {
          $message = 'Translation resource language mismatch: "%s" (request metadata) vs "%s" (request payload).';
          throw new UnprocessableEntityHttpException(sprintf($message, $resource_langcode, $parsed_langcode));
        }
    

    @b.khouy you can add transaltion either by using queryParam "lang_code" or by setting POST request "Content-Language", of course both set to translation destination language. Sending PATCH request to whatever entity endpoint language modifies default language.

    BTW, "successful" translation adding returned error 500 with details: "Cannot get a version identifier for a non-versionable resource.".

    Moreover with enabled jsonapi_translation module JSON:API GET translation stopped working, it always returns default language.

  • 🇬🇧United Kingdom sam.foster

    Hey guys,

    What is the current state of play for this issue? We have Drupal 8.9.2 and are using JSON:API to create English nodes, but we need to create translations of those nodes into Welsh. The Content Type is correctly set up to allow translation, and we can of course create a translation with the GUI, but is this now possible using the JSON:API module or via some other means?

    Can any of these patches here be successfully applied to deliver such functionality? I've tried patching in the drupal/core section of my composer.json but the patch won't apply. Is that because it is now in the core or is it because the patches no longer work with the current version I have as part of Drupal 8.9.2?

    Any pointers will be greatly appreciated

    Cheers

    Sam

  • 🇬🇧United Kingdom sam.foster

    Guys

    Any update at all - can REST API actually create translated nodes and establish the relationship between the original node and the translated one?

    If not are there any work arounds?

    Surely someone out there knows something?

    Thanks

    Sam

  • 🇺🇸United States bradjones1 Digital Nomad Life

    Hi Sam - This is not an area I'm actively working on, yet I can speak to your repeated requests for an update. Drupal is maintained by open-source contributors and there's no dedicated paid developers working on JSON:API specifically. You mention "REST API" which would be something different from JSON:API module, but i'm guessing you're talking about the items in this issue. There is some work on this already, as you can see on this issue... but it's waiting on people (maybe people like you?) to help finish it up.

    I can say that if there are ever updates, you'll see them here. If this is important to your use case, you can help us get this done, or I'm sure there are developers experienced in this area who would be open to doing sponsored work.

  • 🇳🇱Netherlands bbrala Netherlands

    A little note about this we need to take into consideration. If we add a query parameter, the JSON:API specification has some rules around them. They need to be a valid member name, but also contain a special character. See:

    https://jsonapi.org/format/#query-parameters-custom

  • 🇺🇸United States bradjones1 Digital Nomad Life

    Per #143 My read is that it must contain at least one non a-z character, but a capital letter suffices.

    It is RECOMMENDED that a capital letter (e.g. camelCasing) be used to satisfy the above requirement.

    So not much of a strong requirement but something we should enforce.

  • 🇳🇱Netherlands bbrala Netherlands

    Wow you're right. Yay! :)

  • 🇮🇹Italy plach Venezia

    @bbrala @bradjones1

    I resumed work on this today at the DrupalCon Lille sprint. Regarding #143 - #144, the latest code uses a langCode parameter. That looks compliant, doesn't it?

  • 🇳🇱Netherlands bbrala Netherlands

    yeah langCode is fine.

    Would've loved to be able to sit with you, but the fact this week is the kids vacation made that too hard :(

  • 🇮🇹Italy plach Venezia

    @gabesullice

    Addressed your reviews at https://www.drupal.org/project/drupal/issues/3199697#mr1591-note220760 📌 Add JSON:API Translation experimental module Needs work

Production build 0.69.0 2024