From 507af0a14dd039feb139c41e0d889e9b7f124a89 Mon Sep 17 00:00:00 2001
From: John Preston <johnprestonmail@gmail.com>
Date: Fri, 27 Mar 2026 12:54:49 +0700
Subject: [PATCH] [ai] Improve the tr::marked() force rules.

---
 REVIEW.md | 15 ++++++++++++++-
 1 file changed, 14 insertions(+), 1 deletion(-)

diff --git a/REVIEW.md b/REVIEW.md
index 6e840ec6a8..6d96567a84 100644
--- a/REVIEW.md
+++ b/REVIEW.md
@@ -114,7 +114,7 @@ bool _expanded = false;
 SomeType *_pointer = nullptr;
 ```
 
-## Prefer tr:: projections over Ui::Text:: in localization calls
+## Use tr:: projections for TextWithEntities
 
 Inside `tr::lng_...()` calls, always use the `tr::` projection helpers instead of their `Ui::Text::` equivalents. The `tr::` helpers are shorter and work uniformly as both placeholder wrappers and final projectors.
 
@@ -145,6 +145,19 @@ tr::lng_some_key(
     tr::rich)
 ```
 
+Also use `tr::marked()` as the standard way to create `TextWithEntities` — not just as a projector:
+
+```cpp
+// BAD - verbose constructor:
+auto text = TextWithEntities();
+auto text = TextWithEntities{ u"hello"_q };
+auto text = TextWithEntities().append(u"hello"_q);
+
+// GOOD - concise:
+auto text = tr::marked();
+auto text = tr::marked(u"hello"_q);
+```
+
 ## Multi-line calls — one argument per line
 
 When a function call doesn't fit on one line, put each argument on its own line. Don't group "logical pairs" on the same line — it creates inconsistent line lengths and makes diffs noisier.