Translation of documentation (ydb-platform#4918)

ydb/docs/en/core/concepts/_includes/transactions.md

@@ -47,6 +47,8 @@ For more information about YQL support in {{ ydb-short-name }}, see the [YQL doc
 
 ## Distributed transactions {#distributed-tx}
 
-A database table in {{ ydb-short-name }} can be sharded by the range of the primary key values. Different table shards can be served by different distributed database servers (including ones in different locations). They can also move independently between servers to enable rebalancing or ensure shard operability if servers or network equipment goes offline.
+A database [table](../datamodel/table.md) in {{ ydb-short-name }} can be sharded by the range of the primary key values. Different table shards can be served by different distributed database servers (including ones in different locations). They can also move independently between servers to enable rebalancing or ensure shard operability if servers or network equipment goes offline.
 
-{{ ydb-short-name }} supports distributed transactions. Distributed transactions are transactions that affect more than one shard of one or more tables. They require more resources and take more time. While point reads and writes may take up to 10 ms in 99 percentile, distributed transactions typically take from 20 to 500 ms.
+A [topic](../topic.md) in {{ ydb-short-name }} can be sharded into several partitions. Different topic partitions, similar to table shards, can be served by different distributed database servers.
+
+{{ ydb-short-name }} supports distributed transactions. Distributed transactions are transactions that affect more than one shard of one or more tables and topics. They require more resources and take more time. While point reads and writes may take up to 10 ms in the 99th percentile, distributed transactions typically take from 20 to 500 ms.

ydb/docs/en/core/reference/ydb-sdk/topic.md

@@ -1167,6 +1167,8 @@ You can read messages without a [commit](#no-commit) as well. In this case, all
 
 Information about which messages have already been processed can be [saved on the client side](#client-commit) by sending the starting consumer offset to the server when creating a new connection. This does not change the consumer offset on the server.
 
+Data from topics can be read in the context of [transactions](#read-tx). In this case, the reading offset will only advance when the transaction is committed. On reconnect, all uncommitted messages will be read again.
+
 {% list tabs %}
 
 - C++
@@ -1572,6 +1574,60 @@ Reading progress is usually saved on a server for each Consumer. However, such p
 
 {% list tabs %}
 
+- C++
+
+  Before reading messages, the client code must pass a transaction object reference to the reading session settings.
+
+  ```cpp
+      ReadSession->WaitEvent().Wait(TDuration::Seconds(1));
+
+      auto tableSettings = NYdb::NTable::TTxSettings::SerializableRW();
+      auto transactionResult = TableSession->BeginTransaction(tableSettings).GetValueSync();
+      auto Transaction = transactionResult.GetTransaction();
+
+      NYdb::NTopic::TReadSessionGetEventSettings topicSettings;
+      topicSettings.Block(false);
+      topicSettings.Tx(Transaction);
+
+      auto events = ReadSession->GetEvents(topicSettings);
+
+      for (auto& event : events) {
+          // process the event and write results to a table
+      }
+
+      NYdb::NTable::TCommitTxSettings commitSettings;
+      auto commitResult = Transaction.Commit(commitSettings).GetValueSync();
+  ```
+
+{% note warning %}
+
+  When processing `events`, you do not need to confirm processing for `TDataReceivedEvent` events explicitly.
+
+{% endnote %}
+
+  Confirmation of the `TStopPartitionSessionEvent` event processing must be done after calling `Commit`.
+
+  ```cpp
+      std::optional<TStopPartitionSessionEvent> stopPartitionSession;
+
+      auto events = ReadSession->GetEvents(topicSettings);
+
+      for (auto& event : events) {
+          if (auto* e = std::get_if<TStopPartitionSessionEvent>(&event) {
+              stopPartitionSessionEvent = std::move(*e);
+          } else {
+             // process the event and write results to a table
+          }
+      }
+
+      NYdb::NTable::TCommitTxSettings commitSettings;
+      auto commitResult = Transaction.Commit(commitSettings).GetValueSync();
+
+      if (stopPartitionSessionEvent) {
+          stopPartitionSessionEvent->Commit();
+      }
+  ```
+
 - Java (sync)
 
   [Example on GitHub](https://github.com/ydb-platform/ydb-java-examples/blob/develop/ydb-cookbook/src/main/java/tech/ydb/examples/topic/transactions/TransactionReadSync.java)