Repository navigation
Commit 6dd6a53
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
- .changeset
- packages/cli
- src/utils
- test
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| 6 | + | |
| 7 | + | |
| 8 | + | |
| 9 | + | |
| 10 | + | |
| 11 | + | |
| 12 | + | |
| 13 | + | |
| 14 | + | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
1483 | 1483 | | |
1484 | 1484 | | |
1485 | 1485 | | |
| 1486 | + | |
| 1487 | + | |
| 1488 | + | |
| 1489 | + | |
| 1490 | + | |
| 1491 | + | |
| 1492 | + | |
| 1493 | + | |
| 1494 | + | |
| 1495 | + | |
1486 | 1496 | | |
1487 | 1497 | | |
1488 | 1498 | | |
1489 | | - | |
| 1499 | + | |
1490 | 1500 | | |
1491 | 1501 | | |
1492 | 1502 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
62 | 62 | | |
63 | 63 | | |
64 | 64 | | |
| 65 | + | |
| 66 | + | |
| 67 | + | |
| 68 | + | |
| 69 | + | |
| 70 | + | |
| 71 | + | |
| 72 | + | |
| 73 | + | |
| 74 | + | |
| 75 | + | |
| 76 | + | |
| 77 | + | |
| 78 | + | |
| 79 | + | |
| 80 | + | |
| 81 | + | |
| 82 | + | |
| 83 | + | |
| 84 | + | |
| 85 | + | |
| 86 | + | |
| 87 | + | |
| 88 | + | |
| 89 | + | |
| 90 | + | |
| 91 | + | |
| 92 | + | |
| 93 | + | |
| 94 | + | |
| 95 | + | |
| 96 | + | |
| 97 | + | |
| 98 | + | |
| 99 | + | |
| 100 | + | |
| 101 | + | |
| 102 | + | |
| 103 | + | |
| 104 | + | |
| 105 | + | |
| 106 | + | |
| 107 | + | |
| 108 | + | |
| 109 | + | |
| 110 | + | |
| 111 | + | |
| 112 | + | |
| 113 | + | |
| 114 | + | |
| 115 | + | |
| 116 | + | |
| 117 | + | |
| 118 | + | |
| 119 | + | |
| 120 | + | |
| 121 | + | |
| 122 | + | |
| 123 | + | |
| 124 | + | |
| 125 | + | |
| 126 | + | |
| 127 | + | |
| 128 | + | |
| 129 | + | |
| 130 | + | |
| 131 | + | |
| 132 | + | |
| 133 | + | |
0 commit comments