French and English internationalization

QForm Builder separates two complementary concerns:

1. the VitePress documentation language;
2. the FormBuilder and FormViewer user-interface language.

Builder user interface

French is the default language. English is built in.

<FormBuilder
  builder-id="contact-builder"
  locale="fr"
/>

To display the English interface:

<FormBuilder
  builder-id="contact-builder"
  locale="en"
/>

FormViewer accepts the same props:

<FormViewer
  v-model="values"
  :form-fields="schema"
  locale="en"
/>

The locale is injected into internal components: toolbar, catalog, tree, settings panels, conditions, steps and Quasar adapters.

Override translations

A host application can override only the required keys through locales.

<script setup lang="ts">
import type {
  QFormBuilderLocaleRegistry,
} from '@vevedh/qform-builder-layer/types'

const customLocales: QFormBuilderLocaleRegistry = {
  en: {
    toolbar: {
      title: 'Business form editor',
      save: 'Publish',
    },
    canvas: {
      empty: 'Add your first field',
    },
  },
}
</script>

<template>
  <FormBuilder
    builder-id="business-form"
    locale="en"
    :locales="customLocales"
  />
</template>

Overrides are deeply merged with the built-in locale, so the whole dictionary does not need to be copied.

Add a custom locale

A locale that is not built in uses French as its base, then applies the supplied overrides.

<script setup lang="ts">
import type {
  QFormBuilderLocaleRegistry,
} from '@vevedh/qform-builder-layer/types'

const customLocales: QFormBuilderLocaleRegistry = {
  de: {
    code: 'de',
    name: 'Deutsch',
    common: {
      save: 'Speichern',
      cancel: 'Abbrechen',
    },
    toolbar: {
      title: 'Formular-Builder',
    },
  },
}
</script>

<template>
  <FormBuilder locale="de" :locales="customLocales" />
</template>

For a complete translation, progressively provide every family defined by QFormBuilderLocale.

Public types

import type {
  QFormBuilderLocale,
  QFormBuilderLocaleCode,
  QFormBuilderLocaleOverrides,
  QFormBuilderLocaleRegistry,
} from '@vevedh/qform-builder-layer/types'

Built-in locales can also be imported inside the layer project. For consuming applications, the recommended public API remains the locale and locales props.

FormKit validation messages

For fr and en, the root form also forwards the locale through FormKit hierarchical configuration. Validation messages therefore follow the component choice without globally changing other builders on the page.

An additional custom locale must also be registered in the host application's formkit.config.ts when its FormKit validation messages need translation. Otherwise, QForm Builder keeps French as the FormKit fallback locale.

Check UI strings

The repository provides:

bun run ui:i18n:check

This check fails if known legacy Spanish or Portuguese labels reappear in app/**/*.vue or app/**/*.ts.

It must remain a blocking step in release:doctor.

Bilingual VitePress documentation

The documentation is organized as follows:

/       French documentation
/en/    English documentation

Every French page must have an English counterpart with the same relative path.

docs/guide/form-builder.md
docs/en/guide/form-builder.md

Run:

bun run docs:i18n:check

The script fails when a page is missing in either language or when the English version is empty.

Contribution rule

When adding visible text:

1. add a typed key to QFormBuilderLocale;
2. add French and English values;
3. consume useFormBuilderLocale() in the component;
4. update French and English docs in the same patch;
5. run ui:i18n:check and docs:i18n:check.