From f217994370479a1b2fc5838d7369456278ec90b1 Mon Sep 17 00:00:00 2001
From: moss-bryophyta <261561981+moss-bryophyta@users.noreply.github.com>
Date: Sun, 22 Mar 2026 13:04:22 -0700
Subject: [PATCH] docs: add T component granularity guidance

---
 docs-templates/guides/t.mdx | 33 +++++++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)

diff --git a/docs-templates/guides/t.mdx b/docs-templates/guides/t.mdx
index bce51c7..a66f941 100644
--- a/docs-templates/guides/t.mdx
+++ b/docs-templates/guides/t.mdx
@@ -164,6 +164,39 @@ Content in [`<T>`](__DOCS_PATH__/api/components/t) components is sent to the GT
 </T>
 ```
 
+## How much to wrap in a single `<T>`
+
+Wrap **logical content blocks** — content that a translator would naturally read and translate together.
+
+```jsx
+// ✅ Good — related content wrapped together gives translators full context
+<T>
+  <h1>Welcome to Our Platform</h1>
+  <p>Get started in minutes with our simple setup process.</p>
+</T>
+
+// ✅ Good — each card is an independent unit
+{features.map((feature) => (
+  <T key={feature.id}>
+    <h3><Var>{feature.title}</Var></h3>
+    <p><Var>{feature.description}</Var></p>
+  </T>
+))}
+
+// ❌ Too narrow — fragments the translation, loses context
+<T><h1>Welcome to Our Platform</h1></T>
+<T><p>Get started in minutes with our simple setup process.</p></T>
+
+// ❌ Too wide — wrapping your entire page makes it harder to maintain
+<T>
+  {/* ...hundreds of lines of JSX... */}
+</T>
+```
+
+**Rule of thumb:** if text is visually or semantically related, wrap it in one `<T>`. Only split when content is genuinely independent (e.g., a header vs. a footer).
+
+Wrapping more content in a single `<T>` gives translators better context, which produces more natural translations — some languages restructure sentences or need to reference nearby content.
+
 ## Common issues
 
 ### Component boundaries