Translation

Source: packages/spec/src/system/translation.zod.ts

TypeScript Usage

import { ActionResultDialogTranslationSchema, CoverageBreakdownEntrySchema, FieldTranslationSchema, LocaleSchema, ObjectTranslationDataSchema, TranslationBundleSchema, TranslationConfigSchema, TranslationCoverageResultSchema, TranslationDataSchema, TranslationDiffItemSchema, TranslationDiffStatusSchema, TranslationItemSchema } from '@objectstack/spec/system';
import type { ActionResultDialogTranslation, CoverageBreakdownEntry, FieldTranslation, Locale, ObjectTranslationData, TranslationBundle, TranslationConfig, TranslationCoverageResult, TranslationData, TranslationDiffItem, TranslationDiffStatus, TranslationItem } from '@objectstack/spec/system';

// Validate data
const result = ActionResultDialogTranslationSchema.parse(data);

ActionResultDialogTranslation

Translations for an action result dialog

Properties

Property	Type	Required	Description
title	`string`	optional	Translated result dialog title
description	`string`	optional	Translated result dialog description
acknowledge	`string`	optional	Translated acknowledge button label
fields	`Record<string, string>`	optional	Result field labels keyed by the literal field path declared in the action metadata (keys may contain dots)

CoverageBreakdownEntry

Coverage breakdown for a single translation group

Properties

Property	Type	Required	Description
group	`string`	✅	Translation group category
totalKeys	`integer`	✅	Total keys in this group
translatedKeys	`integer`	✅	Translated keys in this group
coveragePercent	`number`	✅	Coverage percentage for this group

FieldTranslation

Translation data for a single field

Properties

Property	Type	Required	Description
label	`string`	optional	Translated field label
help	`string`	optional	Translated help text
placeholder	`string`	optional	Translated placeholder text for form inputs
options	`Record<string, string>`	optional	Option value to translated label map

Locale

BCP-47 Language Tag (e.g. en-US, zh-CN)

Type: string

ObjectTranslationData

Translation data for a single object

Properties

Property	Type	Required	Description
label	`string`	optional	Translated singular label
pluralLabel	`string`	optional	Translated plural label
description	`string`	optional	Translated object description
fields	`Record<string, { label?: string; help?: string; placeholder?: string; options?: Record<string, string> }>`	optional	Field-level translations
_views	`Record<string, { label?: string; description?: string; emptyState?: object }>`	optional	View translations keyed by view name
_actions	`Record<string, { label?: string; description?: string; confirmText?: string; successMessage?: string; … }>`	optional	Action translations keyed by action name
_sections	`Record<string, { label?: string; description?: string }>`	optional	Section translations keyed by section name
_tabs	`Record<string, { label?: string }>`	optional	Filter-preset tab translations keyed by tab name

Nested Shape: `ObjectTranslationData.fields[string]`

Translation data for a single field

Property	Type	Required	Description
label	`string`	optional	Translated field label
help	`string`	optional	Translated help text
placeholder	`string`	optional	Translated placeholder text for form inputs
options	`Record<string, string>`	optional	Option value to translated label map

Nested Shape: `ObjectTranslationData._views[string]`

Property	Type	Required	Description
label	`string`	optional	Translated view label
description	`string`	optional	Translated view description
emptyState	`{ title?: string; message?: string }`	optional	Translated empty-state copy shown when the view has no rows

Nested Shape: `ObjectTranslationData._actions[string]`

Property	Type	Required	Description
label	`string`	optional	Translated action label
description	`string`	optional	Translated action description — the explanatory line under the title in the action's param dialog
confirmText	`string`	optional	Translated confirmation prompt
successMessage	`string`	optional	Translated success toast/message
params	`Record<string, { label?: string; helpText?: string; placeholder?: string; options?: Record<string, string> }>`	optional	Action parameter translations keyed by parameter name
resultDialog	`{ title?: string; description?: string; acknowledge?: string; fields?: Record<string, string> }`	optional	Translations for the action result dialog

Nested Shape: `ObjectTranslationData._sections[string]`

Property	Type	Required	Description
label	`string`	optional	Translated section label
description	`string`	optional	Translated section description

Nested Shape: `ObjectTranslationData._tabs[string]`

Property	Type	Required	Description
label	`string`	optional	Translated tab label

TranslationBundle

Map of locale codes to translation data

Type: Record<string, { objects?: Record<string, object>; apps?: Record<string, object>; messages?: Record<string, string>; globalActions?: Record<string, object>; … }>

TranslationConfig

Internationalization configuration

Properties

Property	Type	Required	Description
defaultLocale	`string`	✅	Default locale (e.g., "en")
supportedLocales	`string[]`	✅	Supported BCP-47 locale codes
fallbackLocale	`string`	optional	Fallback locale code

TranslationCoverageResult

Aggregated translation coverage result

Properties

Property	Type	Required	Description
locale	`string`	✅	BCP-47 locale code
objectName	`string`	optional	Object name scope (omit for full bundle)
totalKeys	`integer`	✅	Total translatable keys from metadata
translatedKeys	`integer`	✅	Number of translated keys
missingKeys	`integer`	✅	Number of missing translations
redundantKeys	`integer`	✅	Number of redundant translations
staleKeys	`integer`	✅	Number of stale translations
coveragePercent	`number`	✅	Translation coverage percentage
items	`{ key: string; status: Enum<'missing' \| 'redundant' \| 'stale'>; objectName?: string; locale: string; … }[]`	✅	Detailed diff items
breakdown	`{ group: string; totalKeys: integer; translatedKeys: integer; coveragePercent: number }[]`	optional	Per-group coverage breakdown

Nested Shape: `TranslationCoverageResult.items[number]`

A single translation diff item

Property	Type	Required	Description
key	`string`	✅	Dot-path translation key
status	`Enum<'missing' \| 'redundant' \| 'stale'>`	✅	Diff status of this translation key
objectName	`string`	optional	Associated object name (snake_case)
locale	`string`	✅	BCP-47 locale code
sourceHash	`string`	optional	Hash of source metadata for precise stale detection
aiSuggested	`string`	optional	AI-suggested translation for this key
aiConfidence	`number`	optional	AI suggestion confidence score (0–1)

Nested Shape: `TranslationCoverageResult.breakdown[number]`

Coverage breakdown for a single translation group

Property	Type	Required	Description
group	`string`	✅	Translation group category
totalKeys	`integer`	✅	Total keys in this group
translatedKeys	`integer`	✅	Translated keys in this group
coveragePercent	`number`	✅	Coverage percentage for this group

TranslationData

Translation data for objects, apps, and UI messages

Properties

Property	Type	Required	Description
objects	`Record<string, { label?: string; pluralLabel?: string; description?: string; fields?: Record<string, object>; … }>`	optional	Object translations keyed by object name
apps	`Record<string, { label: string; description?: string; navigation?: Record<string, object> }>`	optional	App translations keyed by app name
messages	`Record<string, string>`	optional	UI message translations keyed by message ID
globalActions	`Record<string, { label?: string; description?: string; confirmText?: string; successMessage?: string; … }>`	optional	Global action translations keyed by action name
dashboards	`Record<string, { label?: string; description?: string; actions?: Record<string, object>; widgets?: Record<string, object> }>`	optional	Dashboard translations keyed by dashboard name
pages	`Record<string, { label?: string; description?: string; title?: string; subtitle?: string; … }>`	optional	Page translations keyed by page name
flows	`Record<string, { label?: string; screens?: Record<string, object> }>`	optional	Screen-flow translations keyed by flow name
settings	`Record<string, { title?: string; description?: string; groups?: Record<string, object>; keys?: Record<string, object>; … }>`	optional	Settings manifest translations keyed by namespace
metadataForms	`Record<string, { label?: string; description?: string; sections?: Record<string, object>; fields?: Record<string, object> }>`	optional	Translations for metadata-type configuration forms keyed by metadata type
settingsCommon	`{ sourceLabels?: object }`	optional	Cross-namespace Settings UI strings

Nested Shape: `TranslationData.objects[string]`

Translation data for a single object

Property	Type	Required	Description
label	`string`	optional	Translated singular label
pluralLabel	`string`	optional	Translated plural label
description	`string`	optional	Translated object description
fields	`Record<string, { label?: string; help?: string; placeholder?: string; options?: Record<string, string> }>`	optional	Field-level translations
_views	`Record<string, { label?: string; description?: string; emptyState?: object }>`	optional	View translations keyed by view name
_actions	`Record<string, { label?: string; description?: string; confirmText?: string; successMessage?: string; … }>`	optional	Action translations keyed by action name
_sections	`Record<string, { label?: string; description?: string }>`	optional	Section translations keyed by section name
_tabs	`Record<string, { label?: string }>`	optional	Filter-preset tab translations keyed by tab name

Nested Shape: `TranslationData.apps[string]`

Property	Type	Required	Description
label	`string`	✅	Translated app label
description	`string`	optional	Translated app description
navigation	`Record<string, { label: string }>`	optional	Navigation group translations keyed by group ID

Nested Shape: `TranslationData.globalActions[string]`

Property	Type	Required	Description
label	`string`	optional	Translated action label
description	`string`	optional	Translated action description — the explanatory line under the title in the action's param dialog
confirmText	`string`	optional	Translated confirmation prompt
successMessage	`string`	optional	Translated success toast/message
params	`Record<string, { label?: string; helpText?: string; placeholder?: string; options?: Record<string, string> }>`	optional	Action parameter translations keyed by parameter name
resultDialog	`{ title?: string; description?: string; acknowledge?: string; fields?: Record<string, string> }`	optional	Translations for the action result dialog

Nested Shape: `TranslationData.dashboards[string]`

Property	Type	Required	Description
label	`string`	optional	Translated dashboard title
description	`string`	optional	Translated dashboard description
actions	`Record<string, { label?: string }>`	optional	Header action label translations keyed by action url/key
widgets	`Record<string, { title?: string; description?: string; subCaption?: string }>`	optional	Widget translations keyed by widget id

Nested Shape: `TranslationData.pages[string]`

Property	Type	Required	Description
label	`string`	optional	Translated page label (nav / breadcrumb)
description	`string`	optional	Translated page description
title	`string`	optional	Translated `page:header` title (defaults to `label`)
subtitle	`string`	optional	Translated `page:header` subtitle
components	`Record<string, { title?: string; description?: string; label?: string; placeholder?: string; … }>`	optional	Per-component copy keyed by component id (`PageComponentSchema.id`)

Nested Shape: `TranslationData.flows[string]`

Property	Type	Required	Description
label	`string`	optional	Translated flow label
screens	`Record<string, { title?: string; fields?: Record<string, object> }>`	optional	Screen translations keyed by screen node id (`FlowNode.id`, the client's `ScreenSpec.nodeId`)

Nested Shape: `TranslationData.settings[string]`

Property	Type	Required	Description
title	`string`	optional	Translated settings manifest title
description	`string`	optional	Translated settings manifest description
groups	`Record<string, { title?: string; description?: string }>`	optional	Group translations keyed by group key
keys	`Record<string, { label?: string; help?: string; placeholder?: string; options?: Record<string, string> }>`	optional	Per-setting field translations keyed by setting key
actions	`Record<string, { label?: string; confirmText?: string; successMessage?: string }>`	optional	Action button translations keyed by action id

Nested Shape: `TranslationData.metadataForms[string]`

Property	Type	Required	Description
label	`string`	optional	Translated metadata-type display label (overrides registry label)
description	`string`	optional	Translated metadata-type description
sections	`Record<string, { label?: string; description?: string }>`	optional	Section translations keyed by section.name
fields	`Record<string, { label?: string; helpText?: string; placeholder?: string }>`	optional	Field translations keyed by field path (dot-notation for nested fields)

Nested Shape: `TranslationData.settingsCommon`

Property	Type	Required	Description
sourceLabels	`{ env?: string; global?: string; tenant?: string; user?: string; … }`	optional	Source badge labels by resolution layer

TranslationDiffItem

A single translation diff item

Properties

Property	Type	Required	Description
key	`string`	✅	Dot-path translation key
status	`Enum<'missing' \| 'redundant' \| 'stale'>`	✅	Diff status of this translation key
objectName	`string`	optional	Associated object name (snake_case)
locale	`string`	✅	BCP-47 locale code
sourceHash	`string`	optional	Hash of source metadata for precise stale detection
aiSuggested	`string`	optional	AI-suggested translation for this key
aiConfidence	`number`	optional	AI suggestion confidence score (0–1)

TranslationDiffStatus

Translation diff status: missing from bundle, redundant (no matching metadata), or stale (metadata changed)

Allowed Values

missing
redundant
stale

TranslationItem

One locale of translations — the translation metadata type

Properties

Property	Type	Required	Description
objects	`Record<string, { label?: string; pluralLabel?: string; description?: string; fields?: Record<string, object>; … }>`	optional	Object translations keyed by object name
apps	`Record<string, { label: string; description?: string; navigation?: Record<string, object> }>`	optional	App translations keyed by app name
messages	`Record<string, string>`	optional	UI message translations keyed by message ID
globalActions	`Record<string, { label?: string; description?: string; confirmText?: string; successMessage?: string; … }>`	optional	Global action translations keyed by action name
dashboards	`Record<string, { label?: string; description?: string; actions?: Record<string, object>; widgets?: Record<string, object> }>`	optional	Dashboard translations keyed by dashboard name
pages	`Record<string, { label?: string; description?: string; title?: string; subtitle?: string; … }>`	optional	Page translations keyed by page name
flows	`Record<string, { label?: string; screens?: Record<string, object> }>`	optional	Screen-flow translations keyed by flow name
settings	`Record<string, { title?: string; description?: string; groups?: Record<string, object>; keys?: Record<string, object>; … }>`	optional	Settings manifest translations keyed by namespace
metadataForms	`Record<string, { label?: string; description?: string; sections?: Record<string, object>; fields?: Record<string, object> }>`	optional	Translations for metadata-type configuration forms keyed by metadata type
settingsCommon	`{ sourceLabels?: object }`	optional	Cross-namespace Settings UI strings
locale	`string`	✅	BCP-47 locale this item translates (e.g. "zh-CN")
name	`string`	optional	Item name — conventionally the locale code (`zh-CN`); the runtime sync falls back to it when `locale` is absent
label	`string`	optional	Human-readable label shown in metadata lists
_lock	`Enum<'none' \| 'no-overlay' \| 'no-delete' \| 'full'>`	optional	Item-level lock — controls overlay & delete (ADR-0010).
_lockReason	`string`	optional	Human-readable reason shown when a write is refused by _lock.
_lockSource	`Enum<'artifact' \| 'package' \| 'env-forced'>`	optional	Layer that set _lock (artifact \| package \| env-forced).
_provenance	`Enum<'package' \| 'org' \| 'env-forced'>`	optional	Origin of the item (package \| org \| env-forced).
_packageId	`string`	optional	Owning package machine id.
_packageVersion	`string`	optional	Owning package version.
_lockDocsUrl	`string`	optional	Optional documentation link surfaced next to _lockReason.

Nested Shape: `TranslationItem.objects[string]`

Translation data for a single object

Property	Type	Required	Description
label	`string`	optional	Translated singular label
pluralLabel	`string`	optional	Translated plural label
description	`string`	optional	Translated object description
fields	`Record<string, { label?: string; help?: string; placeholder?: string; options?: Record<string, string> }>`	optional	Field-level translations
_views	`Record<string, { label?: string; description?: string; emptyState?: object }>`	optional	View translations keyed by view name
_actions	`Record<string, { label?: string; description?: string; confirmText?: string; successMessage?: string; … }>`	optional	Action translations keyed by action name
_sections	`Record<string, { label?: string; description?: string }>`	optional	Section translations keyed by section name
_tabs	`Record<string, { label?: string }>`	optional	Filter-preset tab translations keyed by tab name

Nested Shape: `TranslationItem.apps[string]`

Property	Type	Required	Description
label	`string`	✅	Translated app label
description	`string`	optional	Translated app description
navigation	`Record<string, { label: string }>`	optional	Navigation group translations keyed by group ID

Nested Shape: `TranslationItem.globalActions[string]`

Property	Type	Required	Description
label	`string`	optional	Translated action label
description	`string`	optional	Translated action description — the explanatory line under the title in the action's param dialog
confirmText	`string`	optional	Translated confirmation prompt
successMessage	`string`	optional	Translated success toast/message
params	`Record<string, { label?: string; helpText?: string; placeholder?: string; options?: Record<string, string> }>`	optional	Action parameter translations keyed by parameter name
resultDialog	`{ title?: string; description?: string; acknowledge?: string; fields?: Record<string, string> }`	optional	Translations for the action result dialog

Nested Shape: `TranslationItem.dashboards[string]`

Property	Type	Required	Description
label	`string`	optional	Translated dashboard title
description	`string`	optional	Translated dashboard description
actions	`Record<string, { label?: string }>`	optional	Header action label translations keyed by action url/key
widgets	`Record<string, { title?: string; description?: string; subCaption?: string }>`	optional	Widget translations keyed by widget id

Nested Shape: `TranslationItem.pages[string]`

Property	Type	Required	Description
label	`string`	optional	Translated page label (nav / breadcrumb)
description	`string`	optional	Translated page description
title	`string`	optional	Translated `page:header` title (defaults to `label`)
subtitle	`string`	optional	Translated `page:header` subtitle
components	`Record<string, { title?: string; description?: string; label?: string; placeholder?: string; … }>`	optional	Per-component copy keyed by component id (`PageComponentSchema.id`)

Nested Shape: `TranslationItem.flows[string]`

Property	Type	Required	Description
label	`string`	optional	Translated flow label
screens	`Record<string, { title?: string; fields?: Record<string, object> }>`	optional	Screen translations keyed by screen node id (`FlowNode.id`, the client's `ScreenSpec.nodeId`)

Nested Shape: `TranslationItem.settings[string]`

Property	Type	Required	Description
title	`string`	optional	Translated settings manifest title
description	`string`	optional	Translated settings manifest description
groups	`Record<string, { title?: string; description?: string }>`	optional	Group translations keyed by group key
keys	`Record<string, { label?: string; help?: string; placeholder?: string; options?: Record<string, string> }>`	optional	Per-setting field translations keyed by setting key
actions	`Record<string, { label?: string; confirmText?: string; successMessage?: string }>`	optional	Action button translations keyed by action id

Nested Shape: `TranslationItem.metadataForms[string]`

Property	Type	Required	Description
label	`string`	optional	Translated metadata-type display label (overrides registry label)
description	`string`	optional	Translated metadata-type description
sections	`Record<string, { label?: string; description?: string }>`	optional	Section translations keyed by section.name
fields	`Record<string, { label?: string; helpText?: string; placeholder?: string }>`	optional	Field translations keyed by field path (dot-notation for nested fields)

Nested Shape: `TranslationItem.settingsCommon`

Property	Type	Required	Description
sourceLabels	`{ env?: string; global?: string; tenant?: string; user?: string; … }`	optional	Source badge labels by resolution layer

Translation

On this page