Issue #3065609 by Charlie ChX Negyesi: Document translations vs getEntity()

core/lib/Drupal/Core/Entity/Plugin/DataType/EntityAdapter.php

@@ -168,7 +168,10 @@ class EntityAdapter extends TypedData implements \IteratorAggregate, ComplexData
    * Returns the wrapped entity object.
    *
    * @return \Drupal\Core\Entity\EntityInterface
-   *   The wrapped entity object.
+   *   The wrapped entity object. If the entity is translatable and a specific
+   *   translation is required, always request it by calling ::getTranslation()
+   *   or ::getUntranslated() as the language of the returned object is not
+   *   defined.
    */
   public function getEntity() {
     return $this->entity;

core/lib/Drupal/Core/Field/FieldItemListInterface.php

@@ -31,7 +31,10 @@ interface FieldItemListInterface extends ListInterface, AccessibleInterface {
    * Gets the entity that field belongs to.
    *
    * @return \Drupal\Core\Entity\FieldableEntityInterface
-   *   The entity object.
+   *   The entity object. If the entity is translatable and a specific
+   *   translation is required, always request it by calling ::getTranslation()
+   *   or ::getUntranslated() as the language of the returned object is not
+   *   defined.
    */
   public function getEntity();