Skip to content

Commit 6dd6a53

Browse files
fix(cli): os i18n extract seeds a field help entry from its description when inlineHelpText is empty (#29280)
<!-- claude-projects-attribution: {"github_login":"os-steve"} --> _Requested by **Steve** · [project thread](https://claude.ai/code/project/chan_01FdL1XeUyvVNxLreh3F4Qi9?thread=cmsg_01FdL1XeUyvVNxLreh3F4Qi99xJJWSaMiqsy9A1NjZ6HbD)_ Fixes #29221 Clause-②: no Metadata-protocol: none ## 维护者速读 - 改了什么:`os i18n extract` 为字段 `help` 条目取默认语言原文时,改为取 `help`、`inlineHelpText`、`description` 中第一个真正写了内容的值;空字符串视为没写,与 console 帮助行 `inlineHelpText || description` 的读法一致。 - 为什么改:原来的 `??` 链停在 `inlineHelpText: ''` 上,这类字段的 `help` 条目没有原文,console 实际显示的 description 从未进入翻译包。 - 风险与回滚:只影响 cli 抽取器给 `help` 条目选原文;非空 `inlineHelpText` 仍优先于 description,`help` 仍最优先,全空字段照旧。仓库内没有任何非测试源码写 `inlineHelpText: ''` 或 `help: ''`,已提交的翻译包不变。回滚即撤掉本 PR。 - 先看:`packages/cli/src/utils/i18n-extract.ts` 中 `collectExpectedEntries` 的字段 `help` 那一段;`packages/cli/test/i18n-extract-inline-help-text.test.ts` 新增的 describe。 - 两分钟验证:`pnpm --filter @objectstack/cli exec vitest run --project unit test/i18n-extract-inline-help-text.test.ts`,应看到 15 条全过。 - 需要你做的:无,席位落地。(卡片的 Edge 2 按派单只做读数、不改代码,见 Acceptance notes。) ## What changes `collectExpectedEntries` (`packages/cli/src/utils/i18n-extract.ts`) seeds a field's `objects.OBJECT.fields.FIELD.help` entry from the **first authored link** of `help`, `inlineHelpText`, `description`, read through `asAuthoredLabel`, the one "authored" test the file already uses (a non-empty string, or a non-empty inline locale map). Before, it read `field.help ?? field.inlineHelpText ?? field.description`, which stops at an empty string. - `inlineHelpText: ''` or `help: ''` beside a `description` now scaffolds the description, which is the line the console draws (`fieldHelpText` in `@object-ui/fields`: `inlineHelpText || description`). - Unchanged: `help` wins over both; a non-empty `inlineHelpText` wins over `description`; a field whose links are all empty gets the same seed-less entry as before. - Whitespace-only text stays authored. That matches the console's `||` (a single space is truthy, so it is the line drawn) and the resolver's non-empty check in PR #29217. Skipping it here would make the extractor disagree with both. - Changeset: `.changeset/29221-i18n-extract-field-help-empty-link.md`, a `patch` for `@objectstack/cli`. The `os i18n check` coverage gate reads the same entries, so a field with `inlineHelpText: ''` and a `description` no longer reports its default locale as missing `help`. ## Tests New `describe` in `packages/cli/test/i18n-extract-inline-help-text.test.ts` (9 tests, beside the existing order pins): - `inlineHelpText: ''` with `description: 'B'` seeds `help` = `'B'`; `help: ''` likewise; `help: ''` with an `inlineHelpText` seeds the `inlineHelpText`; - a non-empty `inlineHelpText` still wins over `description`; `help` still wins over both (with and without an empty `inlineHelpText`); - whitespace-only `inlineHelpText` stays the source, and the restated console reader draws it too; - every link empty still emits the seed-less entry; - for five field shapes that author no `help`, the seed equals the line the console draws (`inlineHelpText || description`, restated); - `computeI18nCoverage` counts the default locale as covered when the seed is the description behind an empty `inlineHelpText`. No forced edits to existing tests. ## Acceptance notes - **One rule, every site (Edge 1, measured).** The field `help` entry is the only place in the extractor that derives help text through a fallback chain. The other help keys each read one key with no fallback: flow screen fields' `inlineHelpText` (the screen field schema has no `description`), form section entries' `helpText`, action params' `helpText`, bulk params' `help`, metadata-form fields' `helpText`. Each already goes through `asAuthoredLabel` or `pushOptional`, so an empty string authors no entry there. `i18n-coverage.ts` has no derivation of its own. - **Committed bundles (measured).** No non-test source in the repo authors `inlineHelpText: ''` or `help: ''` (`git grep` hits only CHANGELOG prose and the `@object-ui/fields` README/docblock). `check:i18n` (the nine generated bundle packages) and `check:i18n-coverage` are in the gate run below; nothing was regenerated. - **Edge 2 (reading, no code).** A field authoring both a non-empty `inlineHelpText` and a different `description` gets one `help` entry, seeded from the `inlineHelpText`, and the resolver serves its translation on `description` too. Readers of a field's `description` besides the console's help line, read on this head: - Studio designer surfaces: the field inspector's description box (`ObjectFieldInspector`), the form canvas preview (`ObjectFormCanvas`), the data-model designer's row tooltip (`DataModelDesigner.fieldTooltip`), the property editor (`plugin-designer` `PropertyEditor`), and `MetadataService.toFieldPayload`, which writes `description` back on save. - `RecordDetailPanel` copies `description` onto each detail field; no renderer in `plugin-detail` draws a field's `description` (grep on this head). - The runtime's action summary for the MCP tool list (`summarizeActionParams`) uses a backing field's `description` as a param's help when the param has no `helpText`. It reads the registry's object, not a localized serve (traced to the MCP domain's declarations loop; not traced end to end). - A separate `description` entry from the extractor would need a bundle key that `FieldTranslationSchema` does not declare, which is a `packages/spec` change. The fix that needs no new key is in the resolver (`translateObject`): serve the `help` entry on `description` only when the field authors no non-empty `inlineHelpText`. That is spec seat 1's surface and reverses what the #29153 ruling kept, so it is reported to the seat, not done here. ## Verification Head `3298a9c9`, the merge of `origin/main` at `01252a45`. Heavy runs went through `os-verify-lock.sh`. <details><summary>cli package: unit tests, typecheck, lint</summary> - `pnpm --workspace-concurrency=2 --filter '@objectstack/cli^...' build`: VERDICT command-exit 0. - `pnpm --filter @objectstack/cli build && pnpm --filter @objectstack/cli exec vitest run --project unit --maxWorkers=2 && pnpm --filter @objectstack/cli typecheck` on `a6ea00b0` (the commit before the merge): Test Files 372 passed (372), Tests 5259 passed (5259); typecheck and `check:test-typecheck` OK. VERDICT command-exit 0. The `integration` tier is CI's (no integration-tier file or spawn entry touched). - After merging `origin/main` (it touched no cli file; it touched `packages/spec` and `service-analytics`, both rebuilt): the two extractor files, Test Files 2 passed (2), Tests 39 passed (39). VERDICT command-exit 0. - `eslint --no-inline-config` on the two touched cli files (the root `pnpm lint` command, scoped): exit 0, no output. </details> <details><summary>Ablation: the old chain turns the new pins red</summary> `scripts/ablation-replace.mjs` put `field.help ?? field.inlineHelpText ?? field.description` back over the new chain (anchor 1 to 0, blob `21178839abf6` to `1ccf82f67d58`), ran the test file through the lock and restored (`git diff HEAD` empty after). The test imports the extractor from `src`, so no build was involved. - Tests 5 failed, 10 passed (15). The five: `inlineHelpText: ''` beside a description, `help: ''` beside a description, `help: ''` beside an `inlineHelpText` (each `expected undefined to be 'B'` or `'I'`), the console-agreement matrix (`expected undefined to be 'B'`), and the coverage case (`expected [ { severity: 'error', … } ] to deeply equal []`). - The pins that stay green under the ablation are the preservation pins (`help` wins, non-empty `inlineHelpText` wins, whitespace stays, all-empty is seed-less): they hold before and after, as intended. </details> <details><summary>dispatch-gates</summary> - `node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack` on `3298a9c9`: 61 commands (the same list as on `a6ea00b0`, before the merge). Each ran with stdin closed; 58 exited 0 on the first pass. - Three exited 3 (prerequisite, not a finding) and pass on a rerun: `check-plugin-teardown-shape.mjs --self-test` after fetching its pinned fixture commit; `check:dual-build-cjs-loads` and `check:i18n-coverage` after `turbo run build --filter='./packages/**' --filter='./examples/**'` (VERDICT command-exit 0). `check:i18n-coverage`: "OK (14 config(s), 426 baselined untranslated string(s), none new)"; `check:i18n` exit 0. The working tree stayed clean: nothing was regenerated. - `node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --ran FILE` (each line carrying its exit code): "61 derived famil(ies) accounted for — 61 run, 0 NOT-MEASURED (a DERIVED zero — all 61 recorded an exit code and none of them is 3)". Exit 0. - Not measured locally: the CI-only families and scheduled jobs `--commands` does not list. Those are CI's readings. </details> --- _Generated by [Claude Code](https://claude.ai/code/session_01ADHkmT5Q35nWM5fCTsoR5H)_ --------- Co-authored-by: Claude <noreply@anthropic.com>
1 parent d9885f5 commit 6dd6a53

3 files changed

Lines changed: 94 additions & 1 deletion

File tree

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
---
2+
'@objectstack/cli': patch
3+
---
4+
5+
fix(cli): `os i18n extract` scaffolds a field's description when its `inlineHelpText` is empty
6+
7+
Clause-②: no
8+
Metadata-protocol: none
9+
10+
Nothing changes in what a metadata author can write. What changes is the seed `os i18n extract` (and the `os i18n check` coverage gate) takes for a field's `objects.OBJECT.fields.FIELD.help` entry.
11+
12+
- **Before.** The seed was `help ?? inlineHelpText ?? description`, which stops at an empty string. A field with `inlineHelpText: ''` (or `help: ''`) and a `description` got a help entry with no seed, so the description, which is the line the console draws for that field, was never offered for translation.
13+
- **Now.** The first link that carries authored text wins: an empty string reads as absent, as it does in the console's help line (`inlineHelpText || description`). Whitespace-only text still counts as authored, as it does in the console.
14+
- **Unchanged.** `help` still wins over `inlineHelpText`, and a non-empty `inlineHelpText` still wins over `description`. A field whose links are all empty still gets the seed-less entry it got before.

‎packages/cli/src/utils/i18n-extract.ts‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1483,10 +1483,20 @@ export function collectExpectedEntries(
14831483
// `inlineHelpText` is the key `FieldSchema` spells help text with, so it
14841484
// is the authored default-locale text of `help` — after `help`, before
14851485
// `description` — exactly as the authored label is for `label` (#15711).
1486+
//
1487+
// The FIRST AUTHORED link wins, not the first defined one: the console
1488+
// draws `inlineHelpText || description` (`fieldHelpText` in
1489+
// `@object-ui/fields`), so an empty `inlineHelpText` reads as absent
1490+
// there and the description is the line people see. A `??` chain
1491+
// stopped at that `''` and scaffolded no seed, leaving the drawn
1492+
// description out of the bundle (#29221). `asAuthoredLabel` is the one
1493+
// "authored" test this file uses (a non-empty string or a non-empty
1494+
// inline locale map); whitespace-only text stays authored, as it does
1495+
// for the console's `||` and the resolver's non-empty check.
14861496
pushOptional(
14871497
out,
14881498
['objects', objectName, 'fields', fieldName, 'help'],
1489-
field.help ?? field.inlineHelpText ?? field.description,
1499+
asAuthoredLabel(field.help) ?? asAuthoredLabel(field.inlineHelpText) ?? asAuthoredLabel(field.description),
14901500
'field',
14911501
{ objectName },
14921502
);

‎packages/cli/test/i18n-extract-inline-help-text.test.ts‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -62,3 +62,72 @@ describe('the field help key takes `inlineHelpText` as its default-locale source
6262
expect(helpIssues(report, 'zh-CN').length).toBe(1);
6363
});
6464
});
65+
66+
// The extractor seeds the key from the FIRST AUTHORED link of
67+
// `help`, `inlineHelpText`, `description`. The console draws a field's help
68+
// line from `inlineHelpText || description` (`fieldHelpText` in
69+
// `@object-ui/fields`), so an empty string reads as absent there; a `??` chain
70+
// stopped at `inlineHelpText: ''` and scaffolded no seed, leaving the drawn
71+
// description out of the bundle (#29221).
72+
describe('the field help key skips an empty link, as the console does', () => {
73+
const entryOf = (field: Record<string, unknown>) =>
74+
collectExpectedEntries(stack(field, [])).find((e) => e.path.join('.') === HELP_KEY);
75+
76+
/** The console's reader (`fieldHelpText` in `@object-ui/fields`), restated. */
77+
const consoleHelpLine = (field: Record<string, unknown>) =>
78+
(field.inlineHelpText as string | undefined) || (field.description as string | undefined) || undefined;
79+
80+
it('`inlineHelpText: \'\'` beside a description scaffolds the description', () => {
81+
const entry = entryOf({ inlineHelpText: '', description: 'B' });
82+
expect(entry?.sourceValue).toBe('B');
83+
expect(entry?.inline).toBe('B');
84+
});
85+
86+
it('`help: \'\'` beside a description scaffolds the description', () => {
87+
const entry = entryOf({ help: '', description: 'B' });
88+
expect(entry?.sourceValue).toBe('B');
89+
expect(entry?.inline).toBe('B');
90+
});
91+
92+
it('`help: \'\'` beside an `inlineHelpText` scaffolds the `inlineHelpText`', () => {
93+
expect(entryOf({ help: '', inlineHelpText: 'I', description: 'B' })?.sourceValue).toBe('I');
94+
});
95+
96+
it('a non-empty `inlineHelpText` still wins over the description', () => {
97+
expect(entryOf({ inlineHelpText: 'I', description: 'B' })?.sourceValue).toBe('I');
98+
});
99+
100+
it('`help` still wins over both', () => {
101+
expect(entryOf({ help: 'H', inlineHelpText: 'I', description: 'B' })?.sourceValue).toBe('H');
102+
expect(entryOf({ help: 'H', inlineHelpText: '', description: 'B' })?.sourceValue).toBe('H');
103+
});
104+
105+
it('whitespace-only `inlineHelpText` stays the source: the console\'s `||` draws it too', () => {
106+
const field = { inlineHelpText: ' ', description: 'B' };
107+
expect(entryOf(field)?.sourceValue).toBe(' ');
108+
expect(consoleHelpLine(field)).toBe(' ');
109+
});
110+
111+
it('every link empty still emits the seed-less entry, as before', () => {
112+
const entry = entryOf({ help: '', inlineHelpText: '', description: '' });
113+
expect(entry).toBeDefined();
114+
expect(entry?.sourceValue).toBeUndefined();
115+
expect(entry?.inline).toBeUndefined();
116+
});
117+
118+
it('agrees with the line the console draws, for every field that authors no `help`', () => {
119+
const shapes: Record<string, unknown>[] = [
120+
{ description: 'B' },
121+
{ inlineHelpText: 'I' },
122+
{ inlineHelpText: 'I', description: 'B' },
123+
{ inlineHelpText: '', description: 'B' },
124+
{ inlineHelpText: 'I', description: '' },
125+
];
126+
for (const field of shapes) expect(entryOf(field)?.sourceValue).toBe(consoleHelpLine(field));
127+
});
128+
129+
it('the coverage gate counts the default locale as covered by the scaffolded description', () => {
130+
const report = computeI18nCoverage(stack({ inlineHelpText: '', description: '说明' }, [enHelp]), { strict: true });
131+
expect(helpIssues(report, 'zh-CN')).toEqual([]);
132+
});
133+
});

0 commit comments

Comments
 (0)