core/lib/Drupal/Core/Entity/entity.api.php | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/core/lib/Drupal/Core/Entity/entity.api.php b/core/lib/Drupal/Core/Entity/entity.api.php
index 5387c7e..0a71c7f 100644
--- a/core/lib/Drupal/Core/Entity/entity.api.php
+++ b/core/lib/Drupal/Core/Entity/entity.api.php
@@ -113,6 +113,17 @@
  * @endcode
  * This involves the same hooks and operations as regular entity loading.
  *
+ * @section entities_revisions_translations Entities, revisions and translations
+ *
+ * A translation is not a revision and a revision is not necessarily a
+ * translation. Revisions and translations are the two axes on the "spreadsheet"
+ * of an entity. If you use the UI and have revisions enabled, then a new
+ * translation change would create a new revision (with a copy of all data for
+ * other languages in that revision). If you don't use revisions or you use the
+ * API, then you can change multiple translations within one revision.
+ * Conceptually, the revisions are columns on the spreadsheet and translations
+ * are rows.
+ *
  * @section save Save operations
  * To update an existing entity, you will need to load it, change properties,
  * and then save; as described above, when creating a new entity, you will also