From fbb06889392c8a5258d6eac72d9b84c6c611bf0b Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 13 Aug 2026 11:01:02 +0000
Subject: [PATCH] docs: document the widget subCaption translation key
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The "What you can translate" table's dashboard row only ever said
`dashboards.<name>` — it never enumerated the widget node's keys, so authors
had no way to learn `subCaption` (added by #7862 for the metric widget's
sub-caption, `options.description`) from the guide. Split the row into a
dashboard-level row and a widget row listing `title` / `description` /
`subCaption`, and add a callout explaining that a widget's `subtitle` alias
now resolves to `subCaption`, not `description` — two different authored
fields, two keys, per the #5428 item-4 ruling.

Part of #8052

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Jqe56GnYFddggeAyfkZFVz
---
 content/docs/ui/translations.mdx | 13 ++++++++++++-
 1 file changed, 12 insertions(+), 1 deletion(-)

diff --git a/content/docs/ui/translations.mdx b/content/docs/ui/translations.mdx
index 8a068937cb..0c48219455 100644
--- a/content/docs/ui/translations.mdx
+++ b/content/docs/ui/translations.mdx
@@ -72,7 +72,8 @@ export default defineStack({
 | Action result dialogs (title / description / acknowledge / field labels) | `objects.<name>._actions.<action>.resultDialog` |
 | Form sections | `objects.<name>._sections.<section>` |
 | App navigation | `apps.<app>.navigation.<id>.label` |
-| Dashboards and widgets | `dashboards.<name>` |
+| Dashboard label / description | `dashboards.<name>.label` / `description` |
+| Dashboard widget title / description / sub-caption | `dashboards.<name>.widgets.<widgetId>.title` / `description` / `subCaption` |
 | Page labels and `page:header` copy | `pages.<name>.label` / `description` / `title` / `subtitle` |
 | Screen-flow wizards (flow label, screen headings, screen field copy) | `flows.<flow>.label` / `flows.<flow>.screens.<node_id>.title` / `.fields.<field>.label` / `.placeholder` — see the boundary note below |
 | Global actions, settings, messages | `globalActions`, `settings`, `messages` |
@@ -85,6 +86,16 @@ labels untouched: `sys_approval_request`'s Approve / Reject rendered in English
 in a zh-CN workspace for every consumer except the Console, which happened to
 re-resolve them client-side against its own copy of the bundle.
 
+<Callout type="info">
+**A widget's `subtitle` alias resolves to `subCaption`, not `description`
+(#5428 item 4, #7862).** The metric widget's sub-caption — the string under
+the number — is the authored `widget.options.description`, a *different*
+authored field from `widget.description` (the copy under the card header).
+Two authored fields get two keys (「两个作者字段两个 key」): `description`
+translates `widget.description`, `subCaption` translates
+`widget.options.description`, and neither reaches the other's field.
+</Callout>
+
 <Callout type="info">
 **Page headers are keyed by page name (#3589).** A page's `page:header`
 component has no stable id, so its `properties.title` / `properties.subtitle`