Skip to main content
Localization in Declarative Forms is built around a single concept: any text field that accepts a string also accepts a LocaleMap — an object with locale code keys and translated string values. The platform picks the right value at runtime based on the active locale.

​
LocaleMap syntax

A plain string applies to all locales: 
label: Full name
A locale map provides a translation per locale: 
label:
  en: Full name
  es: Nombre completo
When a locale map is used, the platform selects the value matching the active locale. If no matching locale exists in the map, en is used as the fallback.

​
Every string field supports LocaleMap

The following properties all accept string | LocaleMap:
  • title (root key)
  • description (root key)
  • sections[].title
  • fields[].label
  • fields[].placeholder
  • fields[].min_label, fields[].max_label (for rating fields)
  • options[].label (for selection fields)
  • validators[].message
  • completion.title
  • completion.message
  • completion.button.label
  • completion.button.url
  • connections[email].subject
  • connections[email].body

​
Locale resolution — priority order

The active locale is determined in this order:
  1. ?lang= URL query parameter — always wins
  2. Browser’s navigator.language
  3. locale key in the YAML
  4. en as the final fallback

​
The locale root key

Setting locale in your YAML locks the form to a specific language. The platform auto-appends ?lang= to the URL to maintain locale consistency as the user moves between sections. 
locale: es
The ?lang= query parameter can still override the locale key — it takes the highest priority in the resolution chain.

​
Supported locale codes

en (English) and es (Spanish).

​
Templating and localization

LocaleMap values in email connections support Handlebars interpolation. Each locale string can contain {{data.fieldId}} variables: 
connections:
  - type: email
    to: "{{data.email}}"
    subject:
      en: "New application from {{data.full_name}}"
      es: "Nueva solicitud de {{data.full_name}}"

​
Options localization

Selection fields (single_select, multiple_select, dropdown) use a structured option format when labels need to be translated: 
options:
  - value: eng
    label:
      en: Software Engineer
      es: Ingeniero de Software
  - value: pm
    label:
      en: Product Manager
      es: Gerente de Producto
  - value: design
    label:
      en: Designer
      es: Diseñador
The value is locale-independent — it is what gets stored in submission.data. The label is what the user sees and supports LocaleMap.

​
Full example

The job application form fully translated: 
version: 1
title:
  en: Join the team
  es: Únete al equipo
description:
  en: Takes about 2 minutes.
  es: Tarda unos 2 minutos.
sections:
  - id: main
    title:
      en: Apply to work with us
      es: Solicita trabajar con nosotros
    fields:
      - id: full_name
        type: short_text
        label:
          en: Full name
          es: Nombre completo
        placeholder:
          en: Jane Smith
          es: Ana García
      - id: role
        type: single_select
        label:
          en: Role you're applying for
          es: Puesto al que aplicas
        options:
          - value: eng
            label:
              en: Software Engineer
              es: Ingeniero de Software
          - value: pm
            label:
              en: Product Manager
              es: Gerente de Producto
          - value: design
            label:
              en: Designer
              es: Diseñador
      - id: email
        type: email
        label:
          en: Email address
          es: Correo electrónico
    next: done