SPIKE: How to translate a page with entity references

[wesrowe]

Description

We need to understand how to translate entity references on translated pages, for the bright future of translations.

Acceptance Criteria

• Understand plan, document
  • SPIKE: How to translate a page with entity references #10004 (comment)

CMS Team

Please check the team(s) that will do this work.

• Program
• Platform CMS Team
• Sitewide Crew
• ⭐️ Sitewide CMS
• ⭐️ Public Websites
• ⭐️ Facilities
• ⭐️ User support

[jilladams]

SPrint planning:
Can investigate.
Best / easiest path may be: input translations for PACT as a different node type that doesn't use reusable Q&A.

Long-term: need a better way.

[jilladams]

Reframing from PACT-related to general use for future of translations.

[jilladams]

Can do mini refining / pull into sprint if we have capacity.

[EWashb]

@timcosgrove do you think we can close this one?

[timcosgrove]

@EWashb I'm keeping this one to track documenting this. It is (relatively) straightforward, provided the CMS and TMGMT are configured correctly.

[timcosgrove]

The short answer is, there is nothing special to do to enable translations of entity references in the CMS. The general procedure is:

• make the parent entity translatable (i.e. node)
• do not make the entity reference field translatable (unless there is a very good reason to do so)
• make the child entities translatable (i.e. the paragraphs, taxonomy terms, menus become translatable

Differences between translating an entity and a field

It's useful to talk about what we mean when we say an entity or field is 'translatable'. When an entity is translatable, it simply means that versions of that entity can be saved that are marked as suitable for a given language.

---
title: Entity translation
---
classDiagram
    note "Note: English is the source / original, and Spanish is the translation."
    English <|-- Spanish : translation of
    English : nid 523
    English : langcode
    English : title
    English : body
    English : categories/reference 345
    class Spanish {
        nid 523
        langcode
        title
        body
        categories/reference 345
    }

Loading

It's worth noting that as far as Drupal is concerned, these are the same entity. If you request node 523, whether you get the English or Spanish version is determined by what language context the CMS is in. The CMS uses context clues to know what language it should show. This can take a number of forms - URL component, domain, query string, etc - but generally, once the CMS knows it should display Spanish, it will display Spanish translations for anything it has a Spanish translation for.

What about categories, which is a taxonomy entity reference? The category entity is translated, but value itself is not. Both English and Spanish point to taxonomy entity 345. Taxonomy entity 345 is also translated, for all intents and purposes independently of the node. Then, the language context system is used to determine what language should show, and the CMS chooses to show the appropriate version of the respective entities.

---
title: Entity translation
---
classDiagram
    note "Note: English is the source / original, and Spanish is the translation."
    English <|-- Spanish : translation of
    English <|-- Categories : entity reference
    Spanish <|-- SpanishCategories : entity reference
    Categories <|-- SpanishCategories : translation of
    English : nid = 523
    English : langcode = en
    English : title = New class for seniors
    English : body = Some text etc.
    English : categories/reference = 345
    class Spanish {
        nid = 523
        langcode = es
        title = Nueva clase para adultos mayores.
        body = Algún texto, etc
        categories/reference = 345 - note this value does not change
    }
   class Categories {
     termid = 345
     langcode = en
     label = Announcement
   }
   class SpanishCategories {
     termid = 345
     langcode = es
     label = Anuncio
   }

Loading

Now, most reference fields are able to be made translatable (Paragraph fields are an exception, and cannot be translatable). Again, this means that the value can be different between source and translation. Using these same entities, if we make "categories/reference" a translatable field, it becomes possible for the Spanish translation of the parent entity to have an entirely different category:

---
title: Entity translation
---
classDiagram
    note "Note: English is the source / original, and Spanish is the translation."
    English <|-- Spanish : translation of
    English <|-- Categories : entity reference
    Spanish <|-- SpanishCategories : entity reference
    English : nid = 523
    English : langcode = en
    English : title = New class for seniors
    English : body = Some text etc.
    English : categories/reference = 345
    class Spanish {
        nid = 523
        langcode = es
        title = Nueva clase para adultos mayores.
        body = Algún texto, etc
        categories/reference = 678 - this is different now
    }
   class Categories {
     termid = 345
     langcode = en
     label = Announcement
   }
   class SpanishCategories {
     termid = 678
     langcode = es
     label = Pescado - this is a different category
   }

Loading

In other words, if we allow the categories field to be translatable, we allow the categories themselves to change.

The issue with this is that it allows the translation to semantically diverge. The Spanish translation is no longer actually a true translation of the English source, because its underlying data is allowed to change.

There are cases where this would be the right thing to do. If the categories need to change for the Spanish-speaking audience because that language and cultural context dictate that the article needs to be categorized differently, then it is appropriate.

However, most of the time, you want to represent the same content with the equivalent meaning in the target language. In this case, making the reference field translatable is unnecessary.

It's not recommended to make entity reference fields translatable unless it is explicitly needed for a few reasons:

• The opportunity for meaning to drift apart
• The potential to confuse people interacting with the CMS who do not fully understand the difference between translating an entity and translating an entity reference field
• Every field that is made translatable begins to contribute to database bloat, which is both a performance and operations problem

When requesting an entity reference field be made translatable, the burden of proof should very much be on the requester to justify why the field needs to be translatable.