Translations

Every label in an ObjectStack app — object and field names, picklist options, view titles, action buttons, app navigation — is metadata, not a string baked into a component. Adding a language means adding a bundle, not touching the app.

Your first bundle

A bundle is a map of locale → translations, registered on your stack:

import { defineTranslationBundle } from '@objectstack/spec';

export const CrmTranslationBundle = defineTranslationBundle({
  en: {
    objects: {
      crm_account: {
        label: 'Account',
        pluralLabel: 'Accounts',
        fields: {
          name: { label: 'Account Name' },
          industry: { label: 'Industry' },
        },
      },
    },
  },
  'zh-CN': {
    objects: {
      crm_account: {
        label: '客户',
        pluralLabel: '客户',
        fields: {
          name: { label: '客户名称' },
          industry: { label: '行业' },
        },
      },
    },
  },
});

export default defineStack({
  // ...
  translations: [CrmTranslationBundle],
  i18n: { defaultLocale: 'en', supportedLocales: ['en', 'zh-CN'] },
});

What you can translate

The metadata types resolved per request are object, view, action, app, and dashboard — a field's labels are translated as part of its object document.

How a locale is chosen

Per request, in this order:

1. The Accept-Language header (the client SDK sends it; setLocale() sets it)
2. A ?locale= query parameter
3. The stack's defaultLocale

Within the bundle, matching walks: exact (zh-CN) → case-insensitive → base language (zh-CN → zh) → variant expansion (zh → zh-CN). If nothing matches, the chain falls back to en, and finally to the literal label on the metadata. Translation lookup never throws — a missing string degrades to the next best text.

Resolved labels are served straight from the REST metadata endpoints (the locale is part of the ETag), so the Console and any SDUI client get translated metadata without doing lookups themselves.

Organizing the files

i18n.fileOrganization picks the layout:

• per_locale (default) — one file per language, combined in the bundle. This is what the Todo example does (en, zh-CN, ja-JP).
• bundled — every locale in one file, like the CRM example above. Fine for two locales; unwieldy past that.
• per_namespace — split by module.

Draft with the CLI, gate in CI

# Scaffold entries for everything translatable that isn't yet
npx os i18n extract --locales zh-CN --fill todo --out src/translations

# Report coverage; fail the build when it slips
npx os i18n check --strict --threshold 95

os i18n check exits non-zero on violations, so it works as a CI gate. A missing string in the default locale is an error; missing strings in other locales are warnings until you set --strict / --threshold. The Todo example ships a completeness test alongside its bundles — worth copying.

Current boundaries

Honest limits worth knowing before you plan around them:

• validationMessages has no runtime consumer today. The schema accepts it and the coverage tooling counts it, but nothing reads it back — validation errors are not translated through bundles yet.
• messageFormat: 'icu' is declared but not implemented — plural/gender formatting isn't available; simple is what runs.
• Two bundle shapes exist. File-authored bundles use the objects.<name> shape documented here, which is what the resolver reads. The translation metadata type authored at runtime uses an object-first (o.<object>) shape, and the two are not bridged — author translations as files for now.
• AI-suggested translation fields (aiSuggested, aiConfidence) are schema only.

Related

• Views · Apps · Actions — the surfaces you're translating
• Objects — where the fallback labels are declared
• i18n standard — the normative protocol
• Translation schema reference — every field, generated from the spec