From 11747d90f6c31c3b3239d77f5485ef4da880c7e1 Mon Sep 17 00:00:00 2001
From: moss-bryophyta <261561981+moss-bryophyta@users.noreply.github.com>
Date: Tue, 11 Aug 2026 08:02:22 -0700
Subject: [PATCH] docs(react): document the _tagIds id-tagging option for
 Next.js

Adds the opt-in `_tagIds` option to the Next.js `withGTConfig` reference,
shipped in gt-next@11.1.6 (gt#2017) and previously undocumented.

Covers the exact span-injection behavior from the implementation:
host elements are annotated in place, bare text/fragments/component roots
get a layout-neutral display:contents span, and output that renders
nothing is left untouched.
---
 .../react/(frameworks)/nextjs/config.mdx      | 27 +++++++++++++++++++
 1 file changed, 27 insertions(+)

diff --git a/docs/en-US/react/(frameworks)/nextjs/config.mdx b/docs/en-US/react/(frameworks)/nextjs/config.mdx
index 46f5ca5a2..7dd581d2e 100644
--- a/docs/en-US/react/(frameworks)/nextjs/config.mdx
+++ b/docs/en-US/react/(frameworks)/nextjs/config.mdx
@@ -100,6 +100,7 @@ All options are optional. Locale options are most commonly set in `gt.config.jso
 | [`getLocalePath`](#request-function-paths) | Path to a custom [`getLocale`](/docs/node/reference/functions/get-locale) function. | `string` | Yes | — |
 | [`getRegionPath`](#request-function-paths) | Path to a custom [`getRegion`](/docs/react/nextjs/reference/functions/get-region) function. | `string` | Yes | — |
 | [`pathRegex`](#path-regex) | Restrict i18n middleware to matching pathnames. | `string` | Yes | — |
+| [`_tagIds`](#tag-ids) | Expose each [`<T>`](/docs/react/reference/components/t) translation hash as a `data-_gt-hash` attribute. | `boolean` | Yes | `false` |
 | [`eslint`](#eslint-options) | Generate the General Translation ESLint config. | `boolean` | Yes | `true` |
 | [`eslintSeverity`](#eslint-options) | Severity for the generated ESLint rules. | `'error' \| 'warn'` | Yes | `'warn'` |
 | [`overwriteESLintConfig`](#eslint-options) | Overwrite an existing `eslint.config.mjs`. | `boolean` | Yes | `false` |
@@ -288,6 +289,32 @@ A JavaScript regular expression source string. When set, the i18n middleware and
   If [`getLocale()`](/docs/react/nextjs/reference/functions/get-locale) or [`registerLocale()`](/docs/react/nextjs/reference/functions/register-locale) receives an unknown locale, `gt-next` warns and falls back to `defaultLocale`.
 </Callout>
 
+### `_tagIds` [#tag-ids]
+
+**Type** `boolean` · **Optional** · **Default** `false`
+
+Tags rendered [`<T>`](/docs/react/reference/components/t) and [`<Tx>`](/docs/react/nextjs/reference/components/tx) output with its published-translation hash, exposed as a `data-_gt-hash` DOM attribute. Tooling such as localized replay and in-context QA uses that attribute to map a rendered node back to the translation it came from.
+
+```ts title="next.config.ts"
+export default withGTConfig(nextConfig, {
+  _tagIds: true,
+});
+```
+
+The value must be the literal `true`. Any other value, including a truthy non-boolean, leaves tagging off, and the option is never enabled implicitly.
+
+Tagging applies to the DOM only. It has no effect on translated strings, such as those returned by [`useGT()`](/docs/react/reference/hooks/use-gt), and it is skipped on React Native.
+
+<Callout type="warn">
+  **Enabling this can add wrapper elements.** Span injection is kept to the minimum necessary:
+
+  - **A single host element** (for example `<T><td>…</td></T>`) is annotated in place. No wrapper is added, so the markup stays valid inside restricted parents such as `<tr>`, `<select>`, and `<ul>`.
+  - **Bare text, a fragment, or a component root** has no host element to carry the attribute, so the output is wrapped in a layout-neutral `display:contents` `<span>`. This is the only case that injects one.
+  - **Output that renders nothing** (`null`, `undefined`, booleans, `''`, arrays whose entries all render nothing, or an empty fragment) is left untouched, so no empty `<span>` appears. Note that `0` and `NaN` do render text and are tagged normally.
+
+  This markup injection is why tagging is off by default. Leave it off unless a tool you run requires the hashes.
+</Callout>
+
 ### ESLint options [#eslint-options]
 
 - `eslint` (`boolean`, default `true`) — generate the General Translation ESLint config during setup.