@@ -0,0 +1,17 @@
+---
+'@objectstack/spec': minor
+'@objectstack/cli': minor
+'@objectstack/metadata-protocol': minor
+---
+
+feat(spec): a lookup or master-detail field's related-list title is translatable
+
+Clause-②: yes
+Metadata-protocol: added
+
+A related list the record page derives from a lookup or master-detail field is titled by the field's `relatedListTitle`, or by the child object's label when it has none. That title had no translation slot, so a zh-CN reader saw it in the authoring language, and `os i18n check` could not see the gap. A lookup from an object back to itself was the plainest case: with no title of its own, a contract's record page listed its renewals under 「合同」, the same word as the contract beside it.
+
+- `FieldTranslationSchema` declares `relatedListTitle`: `objects.<child>.fields.<field>.relatedListTitle`, on the child object whose field declares the title. `translateObject` overlays it on the served child object (`GET /meta/object`, and the app bundle's object members), which is what the console derives the related list's title from, on the side card and on the body table alike.
+- It follows the packaged-base rule (ADR-0029 D9.2a): a title an org re-authored on top of the packaged declaration keeps its text. An authored `relatedListTitle` with no entry keeps its authored text; the child object's label is never substituted for it.
+- `os i18n extract` scaffolds the key and `os i18n check` counts it under the field bucket. A field without a `relatedListTitle` is recorded without being demanded.
+- The object save door puts a served (translated) `relatedListTitle` back to its source text, as it does for the field's other translated slots.
@@ -67,6 +67,7 @@ Translation data for a single field
 | **placeholder** | `string` | optional | Translated placeholder text for form inputs |
 | **options** | `Record<string, string>` | optional | Option value to translated label map |
 | **inlineTitle** | `string` | optional | Translated inline master-detail grid title — overlays the field's own `inlineTitle` |
+| **relatedListTitle** | `string` | optional | Translated detail-page related list title — overlays the field's own `relatedListTitle` |
 
 
 ---
@@ -109,6 +110,7 @@ Translation data for a single field
 | **placeholder** | `string` | optional | Translated placeholder text for form inputs |
 | **options** | `Record<string, string>` | optional | Option value to translated label map |
 | **inlineTitle** | `string` | optional | Translated inline master-detail grid title — overlays the field's own `inlineTitle` |
+| **relatedListTitle** | `string` | optional | Translated detail-page related list title — overlays the field's own `relatedListTitle` |
 
 ### Nested Shape: `ObjectTranslationData._views[string]`
 
 
@@ -21,7 +21,11 @@ export const BusinessUnit = ObjectSchema.create({
 
   fields: {
     name: Field.text({ label: 'Name', required: true, searchable: true, maxLength: 120 }),
-    parent: Field.lookup('showcase_business_unit', { label: 'Parent Unit', allowCreate: true }),
+    // A lookup back to this object, so a unit's record page lists its child
+    // units. Without a title of its own that list would be headed by this
+    // object's own label ("Business Units") beside the unit itself; the title
+    // is translated at `objects.showcase_business_unit.fields.parent.relatedListTitle`.
+    parent: Field.lookup('showcase_business_unit', { label: 'Parent Unit', allowCreate: true, relatedListTitle: 'Sub-units' }),
     kind: Field.select({
       label: 'Type',
       options: [
 
@@ -382,7 +382,8 @@ export const ShowcaseTranslationBundle = {
         // hence 任务数; `total_estimate` reuses showcase_task's 预计工时.
         fields: {
           name: { label: '项目名称' },
-          account: { label: '客户' },
+          // The account page's Projects list, titled by this lookup.
+          account: { label: '客户', relatedListTitle: '项目' },
           owner: { label: '负责人邮箱' },
           status: {
             label: '状态',
@@ -449,7 +450,8 @@ export const ShowcaseTranslationBundle = {
         pluralLabel: '任务',
         fields: {
           title: { label: '标题' },
-          project: { label: '项目' },
+          // The project page's Tasks list, titled by this master-detail.
+          project: { label: '项目', relatedListTitle: '任务' },
           assignee: { label: '负责人' },
           status: {
             label: '状态',
@@ -730,7 +732,8 @@ export const ShowcaseTranslationBundle = {
         pluralLabel: '发票',
         fields: {
           name: { label: '发票号' },
-          account: { label: '客户' },
+          // The account page's Invoices table, titled by this lookup.
+          account: { label: '客户', relatedListTitle: '发票' },
           contact: { label: '联系人' },
           owner: { label: '负责人邮箱' },
           status: { label: '状态' },
@@ -876,7 +879,9 @@ export const ShowcaseTranslationBundle = {
         description: '组织架构层级——在自引用对象上演示树形 / 树形表格视图。',
         fields: {
           name: { label: '名称' },
-          parent: { label: '上级单元' },
+          // The self-lookup's related-list title on a unit's record page,
+          // translated at birth like the label beside it.
+          parent: { label: '上级单元', relatedListTitle: '下级单元' },
           kind: {
             label: '类型',
             options: { company: '公司', division: '事业部', department: '部门', team: '团队' },
 
@@ -0,0 +1,40 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * Under zh-CN, the title of a self-lookup's related list is served translated.
+ *
+ * `showcase_business_unit.parent` points back at the same object, so a unit's
+ * record page lists its child units. The console derives that list (the side
+ * card, or the body table of a `relatedList: 'primary'` list) from the served
+ * CHILD field's `relatedListTitle`, read off `GET /meta/object`; with no
+ * translatable title it was headed by the object's own label, the same word
+ * as the record it sits beside. So the pin is the translator applied to the
+ * app's own object with the app's own bundle, exactly what the REST boundary
+ * does per request locale.
+ */
+import { describe, expect, it } from 'vitest';
+import { translateMetadataDocument, type TranslationBundle } from '@objectstack/spec/system';
+import { BusinessUnit } from '../src/data/objects/business-unit.object.js';
+import { ShowcaseTranslationBundle } from '../src/system/translations/index.js';
+
+const bundle = ShowcaseTranslationBundle as unknown as TranslationBundle;
+
+describe('showcase under zh-CN — a self-lookup\'s related-list title', () => {
+  it('is a lookup from the object back to itself that authors a title', () => {
+    const parent = BusinessUnit.fields.parent as Record<string, unknown>;
+    expect(parent.type).toBe('lookup');
+    expect(parent.reference).toBe(BusinessUnit.name);
+    expect(parent.relatedListTitle).toBe('Sub-units');
+  });
+
+  it('serves the title translated, distinct from the object\'s own translated label', () => {
+    const out = translateMetadataDocument('object', BusinessUnit, bundle, { locale: 'zh-CN' });
+    expect(out.fields.parent.relatedListTitle).toBe('下级单元');
+    expect(out.label).toBe('业务单元');
+  });
+
+  it('leaves the authored English in place for a locale the bundle does not carry', () => {
+    const out = translateMetadataDocument('object', BusinessUnit, bundle, { locale: 'en' });
+    expect(out.fields.parent.relatedListTitle).toBe('Sub-units');
+  });
+});
@@ -1504,6 +1504,9 @@ export function collectExpectedEntries(
         // The inline child grid's heading, drawn on the PARENT's form but
         // addressed by the child field that declares it (`translateObject`).
         pushOptional(out, ['objects', objectName, 'fields', fieldName, 'inlineTitle'], field.inlineTitle, 'field', { objectName });
+        // The related list's title on the parent's record page, addressed the
+        // same way: by the child field that declares it.
+        pushOptional(out, ['objects', objectName, 'fields', fieldName, 'relatedListTitle'], field.relatedListTitle, 'field', { objectName });
 
         // Options — accept either `{value, label}[]` arrays or a record map.
         //
 
@@ -0,0 +1,67 @@
+// Copyright (c) 2026 ObjectStack contributors. Apache-2.0 license.
+//
+// A lookup / master-detail field's related-list title
+// (`objects.<child>.fields.<field>.relatedListTitle`) is an authored,
+// user-visible label: the parent record page heads the derived related list
+// with it. It is served through `translateObject`, so without this walk
+// `os i18n extract` scaffolded no key for it and `os i18n check` measured a
+// debt of zero while a zh-CN user read it in English.
+
+import { describe, it, expect } from 'vitest';
+import { collectExpectedEntries, extractTranslations } from '../src/utils/i18n-extract.js';
+import { computeI18nCoverage } from '../src/utils/i18n-coverage.js';
+import { TranslationDataSchema } from '@objectstack/spec/system';
+
+const config = () => ({
+  objects: [
+    {
+      name: 'contract',
+      label: 'Contract',
+      fields: {
+        // A lookup from the object back to itself: its related list sits on a
+        // contract's own record page.
+        renewed_from: { type: 'lookup', label: 'Renewed From', reference: 'contract', relatedListTitle: 'Renewals' },
+        // No relatedListTitle: the list is headed by the child's label, nothing to demand.
+        amended_from: { type: 'lookup', label: 'Amended From', reference: 'contract' },
+      },
+    },
+  ],
+});
+
+const byKey = () => new Map(collectExpectedEntries(config()).map((e) => [e.path.join('.'), e]));
+
+describe('i18n extract — a field\'s relatedListTitle', () => {
+  it('walks the title on the child field that declares it, and only there', () => {
+    const entries = byKey();
+    expect(entries.get('objects.contract.fields.renewed_from.relatedListTitle'))
+      .toMatchObject({ sourceValue: 'Renewals', inline: 'Renewals', source: 'field' });
+    expect(entries.get('objects.contract.fields.amended_from.relatedListTitle')?.inline).toBeUndefined();
+  });
+
+  it('`TranslationDataSchema` accepts a bundle written at the extracted path', () => {
+    const out = extractTranslations(config(), { locales: ['zh-CN'] });
+    const zh = out.bundles['zh-CN'] as any;
+    expect(zh?.objects?.contract?.fields?.renewed_from?.relatedListTitle).toBeDefined();
+    expect(TranslationDataSchema.safeParse({ objects: zh.objects }).success).toBe(true);
+  });
+});
+
+describe('i18n check — a field\'s relatedListTitle', () => {
+  it('reports an untranslated title, and clears it once translated', () => {
+    const coverage = (translations: unknown[]) => computeI18nCoverage({
+      ...config(),
+      i18n: { supportedLocales: ['en', 'zh-CN'] },
+      translations,
+    } as any).issues.filter((i) => i.locale === 'zh-CN').map((i) => i.key);
+
+    const before = coverage([{ 'zh-CN': { objects: { contract: { label: '合同' } } } }]);
+    expect(before).toContain('objects.contract.fields.renewed_from.relatedListTitle');
+    // Nothing authored ⇒ nothing to translate.
+    expect(before).not.toContain('objects.contract.fields.amended_from.relatedListTitle');
+
+    const after = coverage([{
+      'zh-CN': { objects: { contract: { label: '合同', fields: { renewed_from: { relatedListTitle: '续签合同' } } } } },
+    }]);
+    expect(after).not.toContain('objects.contract.fields.renewed_from.relatedListTitle');
+  });
+});
@@ -131,4 +131,23 @@ describe('[#29673] restoreTranslatedEchoes', () => {
         const echoed = restoreTranslatedEchoes(typed, { source: packagedBase, bundle, packagedBase });
         expect(echoed.item.fields.amount.label).toBe('Amount');
     });
+
+    it('a self-lookup\'s translated relatedListTitle is put back to its source like every other field slot the read writes', () => {
+        const selfBundle = {
+            'zh-CN': { objects: { clm_contract: { fields: { renewed_from: { relatedListTitle: '续签合同' } } } } },
+        } as unknown as TranslationBundle;
+        const source = () => ({
+            name: 'clm_contract',
+            label: 'Contract',
+            fields: {
+                renewed_from: { type: 'lookup', label: 'Renewed From', reference: 'clm_contract', relatedListTitle: 'Renewals' },
+            },
+        });
+        const echo: any = translateObject(source(), selfBundle, { locale: 'zh-CN' });
+        // The precondition: the read really translated the slot.
+        expect(echo.fields.renewed_from.relatedListTitle).toBe('续签合同');
+        const { item, restored } = restoreTranslatedEchoes(echo, { source: source(), bundle: selfBundle });
+        expect((item as any).fields.renewed_from.relatedListTitle).toBe('Renewals');
+        expect(restored.map((r) => r.path)).toEqual(['fields.renewed_from.relatedListTitle']);
+    });
 });
@@ -120,7 +120,7 @@ export function translatedEchoNotices(name: string, restored: readonly RestoredT
 }
 
 /** The field slots the object translator writes. */
-const FIELD_TEXT_SLOTS = ['label', 'description', 'inlineHelpText', 'inlineTitle'] as const;
+const FIELD_TEXT_SLOTS = ['label', 'description', 'inlineHelpText', 'inlineTitle', 'relatedListTitle'] as const;
 /** The object scalars the object translator writes. */
 const OBJECT_TEXT_SLOTS = ['label', 'pluralLabel', 'description'] as const;
 
 
@@ -457,6 +457,7 @@
     "system/FieldTranslation:label",
     "system/FieldTranslation:options",
     "system/FieldTranslation:placeholder",
+    "system/FieldTranslation:relatedListTitle",
     "system/FileDestinationConfig:append",
     "system/FileDestinationConfig:encoding",
     "system/FileDestinationConfig:path",
Original file line number	Diff line number	Diff line change
`@@ -120,7 +120,7 @@ export function translatedEchoNotices(name: string, restored: readonly RestoredT`
`120`	`120`	`}`
`121`	`121`
`122`	`122`	`/** The field slots the object translator writes. */`
`123`		`-const FIELD_TEXT_SLOTS = ['label', 'description', 'inlineHelpText', 'inlineTitle'] as const;`
	`123`	`+const FIELD_TEXT_SLOTS = ['label', 'description', 'inlineHelpText', 'inlineTitle', 'relatedListTitle'] as const;`
`124`	`124`	`/** The object scalars the object translator writes. */`
`125`	`125`	`const OBJECT_TEXT_SLOTS = ['label', 'pluralLabel', 'description'] as const;`
`126`	`126`