Skip to content

Commit 7d13751

Browse files
committed
fix(spec): column translation guidance for name/kind, tighter tests, wording
Co-authored-by: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017ihL2fxVwyhFFqT657pqUh
1 parent 6a232f7 commit 7d13751

7 files changed

Lines changed: 53 additions & 27 deletions

File tree

‎packages/services/service-settings/src/translations/ja-JP.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -595,7 +595,7 @@ export const jaJP: PlatformTranslationData = {
595595
+ '組織ごとに設定するため、規制対象の組織は数年、開発用の組織は数日だけ保持できます。'
596596
+ 'プラットフォーム機能が必要とする最小期間(例:ジョブキューの重複検出ウィンドウ)より短い上書きは無視されてエラーとして記録され、既定のウィンドウが引き続き適用されます。',
597597
keyColumn: { label: 'オブジェクト' },
598-
columns: { maxAge: { label: '行の保持期間' }, expireAfter: { label: '行の有効期限' } },
598+
columns: { maxAge: { label: '行の保持期間' }, expireAfter: { label: '行の失効までの期間' } },
599599
},
600600
quotas: {
601601
label: '行数クォータ',

‎packages/services/service-settings/src/translations/ru.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -749,7 +749,7 @@ export const ru: PlatformTranslationData = {
749749
label: 'Переопределения хранения',
750750
help: 'Переопределения срока для объектов. Длительности задаются в h/d/w/y. Задаются для каждой организации, так что регулируемая организация может хранить годы, а организация для разработки — дни. Переопределение короче минимума, нужного функции платформы (например, окна обнаружения дубликатов очереди заданий), игнорируется и записывается как ошибка, а срок по умолчанию продолжает действовать.',
751751
keyColumn: { label: 'Объект' },
752-
columns: { maxAge: { label: 'Хранить строки' }, expireAfter: { label: 'Срок истечения строк' } },
752+
columns: { maxAge: { label: 'Хранить строки в течение' }, expireAfter: { label: 'Срок истечения строк' } },
753753
},
754754
quotas: {
755755
label: 'Квоты строк',

‎packages/services/service-settings/src/translations/zh-CN.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -613,7 +613,7 @@ export const zhCN: PlatformTranslationData = {
613613
+ '按组织设置,因此受监管的组织可以保留数年,开发用的组织只保留数天。'
614614
+ '短于某项平台功能所需最短窗口(例如作业队列的重复检测窗口)的覆盖会被忽略并记为错误,继续沿用默认窗口。',
615615
keyColumn: { label: '对象' },
616-
columns: { maxAge: { label: '行保留时长' }, expireAfter: { label: '行过期时间' } },
616+
columns: { maxAge: { label: '行保留时长' }, expireAfter: { label: '行过期时长' } },
617617
},
618618
quotas: {
619619
label: '行数配额',

‎packages/services/service-settings/src/translations/zh-Hant.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -491,7 +491,7 @@ export const zhHant: PlatformTranslationData = {
491491
label: '保留期覆寫',
492492
help: '依物件覆寫保留期。時長使用 h/d/w/y。依組織設定,因此受監管的組織可保留數年,開發用組織只保留數天。短於某項平台功能所需最短期限(例如工作佇列的重複偵測期限)的覆寫值會被忽略並記錄為錯誤,繼續套用預設期限。',
493493
keyColumn: { label: '物件' },
494-
columns: { maxAge: { label: '列保留期限' }, expireAfter: { label: '列到期時間' } },
494+
columns: { maxAge: { label: '列保留期限' }, expireAfter: { label: '列到期期限' } },
495495
},
496496
quotas: {
497497
label: '列數配額',

‎packages/spec/src/system/settings-manifest.zod.ts‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -604,10 +604,17 @@ export const SpecifierSchema = lazySchema(() => z.object({
604604
* key against it, and every manifest read serves them as this specifier's
605605
* `options`. Without a source, a declared `options` table is the fallback,
606606
* as for a `select`; without either, any key is admitted.
607+
*
608+
* Translated under `settings.<namespace>.keys.<key>.keyColumn` (`label`, and
609+
* `description` as `help`), beside the map's own `label`.
607610
*/
608611
keyColumn: SpecifierMapKeyColumnSchema.optional().describe('Key column (map)'),
609612

610-
/** `map`: the value columns, in display order. See {@link keyColumn} for the stored shape. */
613+
/**
614+
* `map`: the value columns, in display order. See {@link keyColumn} for the
615+
* stored shape. Translated under `settings.<namespace>.keys.<key>.columns.<name>`
616+
* (`label`, and `description` as `help`), keyed by each column's `name`.
617+
*/
611618
columns: z.array(SpecifierMapColumnSchema).optional().describe('Value columns (map): one stores a scalar per key, several an object'),
612619

613620
/**

‎packages/spec/src/system/translation.test.ts‎

Lines changed: 17 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1859,13 +1859,13 @@ describe('translation unknown-key strictness', () => {
18591859
const entry = {
18601860
label: '保留期覆盖',
18611861
keyColumn: { label: '对象', help: '要覆盖的对象' },
1862-
columns: { maxAge: { label: '保留时长' }, expireAfter: { label: '过期时间', help: '行过期前的时长' } },
1862+
columns: { maxAge: { label: '保留时长' }, expireAfter: { label: '过期时长', help: '行过期前的时长' } },
18631863
};
18641864
const result = PlatformTranslationDataSchema.safeParse({ settings: keys(entry) });
18651865
expect(result.success, JSON.stringify(result.error?.issues)).toBe(true);
18661866
const parsed = result.data?.settings?.lifecycle?.keys?.retention_overrides;
18671867
expect(parsed?.keyColumn).toEqual({ label: '对象', help: '要覆盖的对象' });
1868-
expect(parsed?.columns?.expireAfter).toEqual({ label: '过期时间', help: '行过期前的时长' });
1868+
expect(parsed?.columns?.expireAfter).toEqual({ label: '过期时长', help: '行过期前的时长' });
18691869
// The served document and the platform bundle read the same shape.
18701870
expect(ServedTranslationDataSchema.safeParse({ settings: keys(entry) }).success).toBe(true);
18711871
expect(PlatformTranslationBundleSchema.safeParse({ 'zh-CN': { settings: keys(entry) } }).success).toBe(true);
@@ -1875,7 +1875,6 @@ describe('translation unknown-key strictness', () => {
18751875
['headers', 'columns'],
18761876
['columnLabels', 'columns'],
18771877
['keyHeader', 'keyColumn'],
1878-
['key_column', 'keyColumn'],
18791878
])('refuses `%s` on the setting entry, naming `%s`', (wrong, right) => {
18801879
const issue = issuesOf({ [wrong]: {} }).find((i) => i.code === 'unrecognized_keys');
18811880
expect(issue?.message).toContain(`\`${wrong}\` → \`${right}\``);
@@ -1894,8 +1893,21 @@ describe('translation unknown-key strictness', () => {
18941893
it('refuses a bare string where a column entry is an object', () => {
18951894
// A column header is two strings, not one: a plain string would leave
18961895
// no place for its `help`, so the shape refuses it rather than coerce.
1897-
expect(issuesOf({ keyColumn: 'Object' })).not.toEqual([]);
1898-
expect(issuesOf({ columns: { maxAge: 'Keep rows for' } })).not.toEqual([]);
1896+
const at = ['settings', 'lifecycle', 'keys', 'retention_overrides'];
1897+
expect(issuesOf({ keyColumn: 'Object' }).map((i) => [i.code, i.path]))
1898+
.toEqual([['invalid_type', [...at, 'keyColumn']]]);
1899+
expect(issuesOf({ columns: { maxAge: 'Keep rows for' } }).map((i) => [i.code, i.path]))
1900+
.toEqual([['invalid_type', [...at, 'columns', 'maxAge']]]);
1901+
});
1902+
1903+
it("refuses a specifier column pasted in whole, saying where its `name` goes instead of renaming it", () => {
1904+
// `name` is the record key, never the header: a rename to `label`
1905+
// would tell the author to overwrite the header with the identifier.
1906+
const issue = issuesOf({ columns: { maxAge: { name: 'maxAge', label: '保留时长', kind: 'duration' } } })
1907+
.find((i) => i.code === 'unrecognized_keys');
1908+
expect(issue?.message).toContain('`columns.<name>`');
1909+
expect(issue?.message).toContain('the `map` specifier declares it');
1910+
expect(issue?.message).not.toContain('`name` → `label`');
18991911
});
19001912
});
19011913
});

‎packages/spec/src/system/translation.zod.ts‎

Lines changed: 24 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -2237,6 +2237,29 @@ const appTranslationDataShape = () => ({
22372237
}).optional().describe('Cross-namespace Settings UI strings'),
22382238
});
22392239

2240+
/**
2241+
* One column header of a settings `map` specifier: the key column
2242+
* (`keys.<key>.keyColumn`) or one value column (`keys.<key>.columns.<name>`).
2243+
* Its leaves are the two strings `SpecifierMapColumnSchema` and
2244+
* `SpecifierMapKeyColumnSchema` declare: `label`, and `description` translated
2245+
* as `help`, the spelling the setting's own entry uses for its `description`.
2246+
*/
2247+
const settingsMapColumnTranslation = (surface: string) => strictObject({
2248+
surface,
2249+
history: TRANSLATION_HISTORY,
2250+
aliases: { title: 'label', header: 'label', heading: 'label', helpText: 'help', hint: 'help', description: 'help' },
2251+
// A specifier column pasted in whole carries these two. Neither is copy:
2252+
// the column's `name` is the record key this entry sits under, and its
2253+
// `kind` is declared by the specifier, so neither is renamed to a leaf here.
2254+
guidance: {
2255+
name: "a column's `name` is not translated: it is the key this entry sits under (`columns.<name>`), so write the entry there and drop `name`",
2256+
kind: "a column's `kind` is not translated: the `map` specifier declares it, so drop it from the translation",
2257+
},
2258+
}, {
2259+
label: z.string().optional().describe('Translated column header'),
2260+
help: z.string().optional().describe('Translated column help text'),
2261+
});
2262+
22402263
/**
22412264
* The one group that is PLATFORM-ONLY, as a shape rather than a schema.
22422265
*
@@ -2266,22 +2289,6 @@ const appTranslationDataShape = () => ({
22662289
* A function, not a `const`, for the same reason
22672290
* {@link appTranslationDataShape} is one.
22682291
*/
2269-
/**
2270-
* One column header of a settings `map` specifier: the key column
2271-
* (`keys.<key>.keyColumn`) or one value column (`keys.<key>.columns.<name>`).
2272-
* Its leaves are the two strings `SpecifierMapColumnSchema` and
2273-
* `SpecifierMapKeyColumnSchema` declare: `label`, and `description` translated
2274-
* as `help`, the spelling the setting's own entry uses for its `description`.
2275-
*/
2276-
const settingsMapColumnTranslation = (surface: string) => strictObject({
2277-
surface,
2278-
history: TRANSLATION_HISTORY,
2279-
aliases: { title: 'label', name: 'label', header: 'label', heading: 'label', helpText: 'help', hint: 'help', description: 'help' },
2280-
}, {
2281-
label: z.string().optional().describe('Translated column header'),
2282-
help: z.string().optional().describe('Translated column help text'),
2283-
});
2284-
22852292
const platformSettingsShape = () => ({
22862293
/**
22872294
* Settings manifest translations keyed by settings namespace
@@ -2340,7 +2347,7 @@ const platformSettingsShape = () => ({
23402347
history: TRANSLATION_HISTORY,
23412348
aliases: {
23422349
title: 'label', name: 'label', helpText: 'help', hint: 'help', description: 'help', choices: 'options', values: 'options',
2343-
keyHeader: 'keyColumn', key_column: 'keyColumn', headers: 'columns', columnLabels: 'columns',
2350+
keyHeader: 'keyColumn', headers: 'columns', columnLabels: 'columns',
23442351
},
23452352
}, {
23462353
label: z.string().optional().describe('Translated setting label'),

0 commit comments

Comments
 (0)