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

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

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

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.

On this page