Internationalisation FR/EN

QForm Builder distingue deux sujets complémentaires :

1. la langue de la documentation VitePress ;
2. la langue de l’interface de FormBuilder et FormViewer.

Interface du builder

Le français est la langue par défaut. L’anglais est inclus nativement.

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

Pour afficher l’interface anglaise :

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

FormViewer accepte les mêmes props :

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

La locale est injectée dans les composants internes : toolbar, catalogue, arborescence, panneaux de propriétés, conditions, steps et adaptateurs Quasar.

Surcharger les traductions

Une application hôte peut surcharger seulement les clés nécessaires grâce à locales.

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

const customLocales: QFormBuilderLocaleRegistry = {
  fr: {
    toolbar: {
      title: 'Éditeur de formulaire métier',
      save: 'Publier',
    },
    canvas: {
      empty: 'Ajoutez votre premier champ',
    },
  },
}
</script>

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

Les surcharges sont fusionnées récursivement avec la locale intégrée. Il n’est donc pas nécessaire de recopier tout le dictionnaire.

Ajouter une locale personnalisée

Une locale non intégrée utilise le français comme base, puis applique les surcharges fournies.

<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>

Pour une traduction complète, fournir progressivement toutes les familles du type QFormBuilderLocale.

Types publics

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

Les locales intégrées peuvent également être importées depuis le layer dans le code interne du projet. Pour une application consommatrice, l’API recommandée reste les props locale et locales.

Messages de validation FormKit

Pour fr et en, le formulaire racine transmet également la locale à la configuration hiérarchique FormKit. Les messages de validation suivent donc le choix du composant sans modifier globalement les autres builders de la page.

Une locale personnalisée supplémentaire doit aussi être enregistrée dans le formkit.config.ts de l’application hôte si ses messages de validation FormKit doivent être traduits. Sinon, QForm Builder conserve le français comme locale FormKit de secours.

Contrôler les textes UI

Le dépôt fournit :

bun run ui:i18n:check

Ce contrôle échoue si des libellés espagnols ou portugais historiques connus réapparaissent dans app/**/*.vue ou app/**/*.ts.

Il doit rester bloquant dans release:doctor.

Documentation VitePress bilingue

La documentation est organisée ainsi :

/       documentation française
/en/    documentation anglaise

Chaque page française doit posséder une page anglaise correspondante avec le même chemin relatif.

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

Vérification :

bun run docs:i18n:check

Le script échoue si une page manque dans une langue ou si la version anglaise est vide.

Règle de contribution

Lorsqu’un texte visible est ajouté :

1. ajouter une clé typée à QFormBuilderLocale ;
2. ajouter les valeurs françaises et anglaises ;
3. utiliser useFormBuilderLocale() dans le composant ;
4. mettre à jour les docs FR et EN dans le même patch ;
5. exécuter ui:i18n:check et docs:i18n:check.