Localizing built-in copy
Texaryn’s built-in widgets provide eight required message functions: the visible labels
and accessible names for array add, remove, move-up and move-down controls; the
required marker; the error summary heading and per-item detail; and validation
messages. Field labels, descriptions and hints usually come from the schema or
the UI configuration. The optional fieldLabel function localizes a label
inferred from a data pointer, or the generic label used when no name is available.
The optional expandBoundary function supplies labels for recursive expansion
and projection-budget controls. Supply both optional functions when those
controls and fallback labels must be translated.
Those functions form one contract, FormMessages in @texaryn/core, and every
binding renders from it. English is the default. Supplying another set replaces
the configured copy in every widget, including a layered widget set such as
@texaryn/react-mui, which reads the same configuration through
@texaryn/react.
The contract
Section titled “The contract”import type { FormMessages } from '@texaryn/core'
const french: FormMessages = { addItem: ({ itemTemplateTitle, containerTitle }) => ({ label: 'Ajouter', accessibleName: containerTitle ? `Ajouter un élément à ${containerTitle}` : `Ajouter ${itemTemplateTitle ?? 'un élément'}`, }), removeItem: ({ position, itemTitle, containerTitle }) => ({ label: 'Retirer', accessibleName: `Retirer ${itemTitle ?? 'élément'} ${position}${containerTitle ? ` de ${containerTitle}` : ''}`, }), moveItemUp: ({ position, itemTitle, containerTitle }) => ({ label: 'Monter', accessibleName: `Monter ${itemTitle ?? 'élément'} ${position}${containerTitle ? ` dans ${containerTitle}` : ''}`, }), moveItemDown: ({ position, itemTitle, containerTitle }) => ({ label: 'Descendre', accessibleName: `Descendre ${itemTitle ?? 'élément'} ${position}${containerTitle ? ` dans ${containerTitle}` : ''}`, }), expandBoundary: ({ boundary, containerTitle, position, count }) => { const label = boundary === 'recursion' ? 'Développer' : 'Afficher plus de champs' return { label, accessibleName: `${label}${count > 1 ? ` ${position}` : ''}${containerTitle ? ` dans ${containerTitle}` : ''}`, } }, requiredIndicator: () => ({ text: '(obligatoire)', placement: 'before' }), errorSummaryHeading: ({ count }) => (count === 1 ? 'Il y a un problème' : `Il y a ${count} problèmes`), errorSummaryDetail: ({ messages }) => ` : ${messages.join(', ')}`, fieldLabel: ({ fieldName, itemPosition }) => fieldName ?? (itemPosition === undefined ? 'Champ' : `Élément ${itemPosition}`), validationMessage: (error) => { if (error.keyword === 'required') return 'Ce champ est obligatoire.' if (error.keyword === 'minLength') { const limit = error.params.limit return typeof limit === 'number' && Number.isFinite(limit) && limit >= 0 ? `Saisissez au moins ${limit} caractères.` : 'Cette valeur est trop courte.' } return 'Cette valeur est invalide.' },}Each message is a function rather than a template, so a language decides its
own word order, whether a clause appears at all, and how a position is written.
position is 1-based and meant for display.
An action returns both surfaces of its control. The accessible name has to contain the visible label: a speech-input user says the word on the button, and the control has to answer to it. The conformance suite asserts that relation on the rendered DOM.
The required indicator returns its text and which side of the label it sits
on. The binding keeps it out of the accessible name; aria-required already
carries the state.
The optional fieldLabel function receives a readable name such as First name, or a 1-based array item position. Without it, Texaryn uses the English
fallbacks Field and Item N. Schema titles stay unchanged. Field widgets and
error summary links use the same resolved label.
The error summary’s heading takes the number of items, and its detail returns the whole text that follows an item’s link, punctuation included, so a locale decides its own colon and its own list separator. The link text is resolved by the same helper used for the widget label.
validationMessage receives a ValidationError. Format from its keyword and
normalized params, not from message: that field preserves evaluator
diagnostic text for debugging and is not safe presentation copy. The JSON
Schema and Zod adapters normalize known constraints into params.limit or
params.format; unknown evaluator keywords receive the safe fallback This value is invalid. in English. Locale changes reformat visible errors without
revalidating the form.
A locale implements the required interface. When Texaryn adds a required
message, a translated application fails to compile rather than rendering one
English control. The optional fieldLabel and expandBoundary functions fall back to English
when omitted. To reword a single message while keeping the rest, use
mergeMessages(englishMessages, { requiredIndicator: () => ({ text: '*', placement: 'after' }) }).
Supplying it
Section titled “Supplying it”React, on the provider:
<FormProvider value={form.runtime} messages={french}> <FormRoot registry={registry} /></FormProvider>Vue, beside the runtime. A ref or getter lets a language switch reach a mounted form:
const messages = ref(french)provideFormRuntime(form.runtime, { messages })Web Components, as a property, before or after the element is connected:
import type { TexarynFormElement } from '@texaryn/web-components'
const form = document.createElement('texaryn-form') as TexarynFormElementform.messages = frenchor through mountForm(container, runtime, { registry, idPrefix, messages: french }),
whose returned Mount has setMessages for a later switch.
Angular, on the form root:
<texaryn-form-root [form]="form" [registry]="registry" [messages]="french" />Svelte, on the form root:
<FormRoot {form} {registry} messages={french} />SolidJS, on the form root:
<FormRoot form={form} registry={registry} messages={french} />In every binding a new set takes effect on the mounted form without remounting it, so focus and any partly typed value survive a language change.
Bridging an existing i18n stack
Section titled “Bridging an existing i18n stack”Texaryn defines no message identifiers. Each function calls your own translation function with keys you choose, so the catalogue stays yours:
import { useMemo } from 'react'import { useTranslation } from 'react-i18next'import type { FormMessages } from '@texaryn/core'
const validationKeywords = new Set([ 'required', 'minLength', 'maxLength', 'minimum', 'exclusiveMinimum', 'maximum', 'exclusiveMaximum', 'minItems', 'maxItems', 'minProperties', 'maxProperties', 'format', 'pattern', 'type', 'enum', 'const', 'uniqueItems', 'dependentRequired', 'additionalProperties', 'oneOf', 'anyOf', 'not',])
function useTexarynMessages(): FormMessages { const { t } = useTranslation() return useMemo( () => ({ addItem: (c) => ({ label: t('form.add'), accessibleName: t('form.addName', c) }), removeItem: (c) => ({ label: t('form.remove'), accessibleName: t('form.removeName', c) }), moveItemUp: (c) => ({ label: t('form.up'), accessibleName: t('form.upName', c) }), moveItemDown: (c) => ({ label: t('form.down'), accessibleName: t('form.downName', c) }), expandBoundary: (c) => ({ label: t(c.boundary === 'recursion' ? 'form.expand' : 'form.moreFields'), accessibleName: t(c.boundary === 'recursion' ? 'form.expandName' : 'form.moreFieldsName', c), }), requiredIndicator: () => ({ text: t('form.required'), placement: 'after' }), errorSummaryHeading: (c) => t('form.summaryHeading', c), errorSummaryDetail: (c) => t('form.summaryDetail', c), fieldLabel: (c) => c.fieldName ?? ( c.itemPosition === undefined ? t('form.field') : t('form.item', c) ), validationMessage: (e) => t( validationKeywords.has(e.keyword) ? `form.validation.${e.keyword}` : 'form.validation.invalid', e.params, ), }), [t], )}The useMemo matters: the set is passed by identity, so a new object on every
render would re-render every widget.
Custom widgets
Section titled “Custom widgets”A custom widget reads the configured set the same way the built-in ones do:
useFormMessages() in React, useFormMessages() returning a computed in Vue,
and ctx.messages on the render context in Web Components. Pass that set to
visibleFieldLabel(title, pointer, messages) from @texaryn/core when deriving
a label, so a later language change reaches both the widget and its summary link.
What is not covered
Section titled “What is not covered”The error summary’s focus behaviour is ADR-005’s, not this contract’s. Texaryn sets no text direction; that is the host document’s.