Translations (i18n)
Translations (i18n)
Crouton supports server-side translations for column labels, resource titles, sidebar entries, enum option labels, UI chrome, and validation messages. The frontend never owns a translation catalogue — it sends Accept-Language, and the API responds in that language.
Setup
Add an i18n block to crouton.json:
{
"title": "My app",
"resourcesDir": "resources",
"enumsFile": "crouton.enums.json",
"i18n": {
"defaultLanguage": "en",
"languages": ["en", "nl", "fr"],
"translationsDir": "translations"
}
}| Field | Description |
|---|---|
defaultLanguage | Fallback language when a key is missing. |
languages | All supported languages. Controls cache size. |
translationsDir | Directory containing <lang>.json files, relative to project root. |
Generating translation files
# Create initial files for every configured language
npx crouton init translations
# Regenerate & merge (safe — hand edits are preserved)
npx crouton update translations
# Same as above, limited to specific languages
npx crouton update translations --lang nl,fr
# Remove keys that no longer match any column/enum
npx crouton update translations --prune
# Preview without writing
npx crouton update translations --dry-runcrouton update resources also refreshes translation files in the same pass, so the normal database-sync flow keeps translations in step with newly-introspected columns.
File format
Each language has one JSON file in translationsDir:
// translations/nl.json
{
"app": {
"title": "Mijn applicatie"
},
"sidebarGroups": {
"metadata": "Metadata"
},
"resources": {
"book": {
"title": "Boeken",
"sidebar": "Boeken",
"columns": {
"name": "Naam",
"description": "Beschrijving"
},
"actions": {
"publish": "Publiceren"
},
"subResources": {
"chapters": {
"title": "Hoofdstukken",
"columns": { "title": "Titel" }
}
}
}
},
"enums": {
"Status": {
"ACTIVE": "Actief",
"ARCHIVED": "Gearchiveerd"
}
},
"ui": {
"actions": { "save": "Opslaan", "cancel": "Annuleren", "delete": "Verwijderen" },
"table": { "empty": "Geen resultaten", "of": "van" }
},
"validation": {
"required": "{field} is verplicht",
"invalid_type": "{field} heeft een ongeldig type"
}
}Key conventions
resources.<name>is keyed on the resource'sname(fromresource.json), not on the route.- Column keys are column ids, including virtual ids generated by
extend. - Every section is optional. An empty
{}file is valid and means "fall back everywhere". - The
en.jsonfile is a real file generated withlabelFromId/resource.jsonlabels. It is the last resort before the raw column id. - Empty strings (
"") are treated as untranslated — they fall through the fallback chain.
Fallback chain
For any lookup (e.g. resources.book.columns.name):
- Requested language bundle (
nl.json) - Default language bundle (
en.json) - The
labelfromresource.json labelFromId(columnId)— the raw id turned into a readable string
How it works
Accept-Language header
The frontend sets Accept-Language on every API call via an axios interceptor installed by useCrouton().init(). The backend's LanguageInterceptor parses the header (standard q-value negotiation), stores the resolved language in an AsyncLocalStorage context, and sets Vary: Accept-Language + Content-Language on the response.
Caching
Any reverse proxy in front of crouton must honour Vary: Accept-Language, or it will serve stale translations.
What gets translated
| Endpoint | Translated |
|---|---|
GET /<route>/schemas | Column labels, resource title, view/form/table/filter JSON Schema titles |
GET /<route>/definition | Same |
GET /_app/layout | Sidebar labels, group labels, app title. Adds i18n metadata and ui dictionary |
GET /_app/translations | ui + validation dictionaries for the current language |
Read endpoints (findAll / findOne) | { value, label } envelope uses localized enum labels |
| Validation errors (400) | validation.<code> keys with {field} interpolation |
Dev-only editor endpoints (resource-columns, resource-json-raw, PATCH /resource.json) serve untranslated data — they edit resource.json, so they show what is on disk.
Enum labels
Enum option labels in read responses (the { value, label } envelope) are translated using enums.<EnumName>.<value> keys. Sorting and filtering on an enum column still operate on the stored scalar value, not the translated label.
Frontend
Language select
When the backend reports more than one language, a LanguageSelect dropdown appears in the admin sidebar. Consumers can also build their own UI — useLanguage() exposes the full reactive state:
import { useLanguage } from '@ghentcdh/crouton-vue';
const { language, languages, setLanguage, t } = useLanguage();
// Change language programmatically
await setLanguage('nl');
// Look up a ui dictionary key
const label = t('actions.save'); // "Opslaan"setLanguage updates the reactive ref, persists to localStorage, and triggers a layout + FormDef refresh automatically. Switching back to a previously used language is instant (FormDefs are cached per language).
UI dictionary
Crouton ships built-in translations for all application chrome (buttons, modals, filters, …) for English, Dutch, French, German, and West Flemish (wv). No configuration needed — the right strings load automatically based on the active language.
For any other language, the English strings are used as fallback. The table below lists the EN / NL / FR / DE strings; the wv bundle covers the same keys.
Bundled ui keys
| Key | EN | NL | FR | DE |
|---|---|---|---|---|
table.search | Search... | Zoeken... | Rechercher... | Suchen... |
table.filters | Filters | Filters | Filtres | Filter |
table.addFilter | Add filter | Filter toevoegen | Ajouter un filtre | Filter hinzufĂĽgen |
table.addRecord | Add record | Record toevoegen | Ajouter un enregistrement | Datensatz hinzufĂĽgen |
table.editFields | Edit fields | Velden bewerken | Modifier les champs | Felder bearbeiten |
table.recordsPerPage | Records per page | Records per pagina | Enregistrements par page | Einträge pro Seite |
table.showing | Showing | Toont | Affichage de | Zeige |
table.of | of | van | sur | von |
table.records | records | records | enregistrements | Einträge |
actions.save | Save | Opslaan | Enregistrer | Speichern |
actions.cancel | Cancel | Annuleren | Annuler | Abbrechen |
actions.close | Close | Sluiten | Fermer | SchlieĂźen |
actions.edit | Edit | Bewerken | Modifier | Bearbeiten |
actions.delete | Delete | Verwijderen | Supprimer | Löschen |
actions.view | View | Bekijken | Voir | Ansehen |
actions.create | Create | Aanmaken | Créer | Erstellen |
actions.retry | Retry | Opnieuw | Réessayer | Wiederholen |
actions.reset | Reset | Resetten | Réinitialiser | Zurücksetzen |
actions.apply | Apply | Toepassen | Appliquer | Anwenden |
modal.update | Update | Bijwerken | Mettre Ă jour | Aktualisieren |
modal.create | Create | Aanmaken | Créer | Erstellen |
modal.deleteTitle | Delete record | Record verwijderen | Supprimer l'enregistrement | Datensatz löschen |
modal.deleteMessage | Are you sure… | Weet u zeker… | Êtes-vous sûr… | Sind Sie sicher… |
autoSave.saving | Saving… | Opslaan… | Enregistrement… | Speichern… |
autoSave.saved | Saved ✓ | Opgeslagen ✓ | Enregistré ✓ | Gespeichert ✓ |
autoSave.pending | Fill required fields… | Vul verplichte velden in… | Remplissez les champs… | Pflichtfelder ausfüllen… |
autoSave.error | Save failed | Opslaan mislukt | Échec de l'enregistrement | Speichern fehlgeschlagen |
filter.contains | contains | bevat | contient | enthält |
filter.not_contains | not contains | bevat niet | ne contient pas | enthält nicht |
filter.equals | equals | is gelijk aan | est égal à | ist gleich |
filter.not_equals | not equals | is niet gelijk aan | n'est pas égal à | ist nicht gleich |
filter.gt | > | > | > | > |
filter.lt | < | < | < | < |
filter.isnull | is empty | is leeg | est vide | ist leer |
filter.isnotnull | is not empty | is niet leeg | n'est pas vide | ist nicht leer |
filter.enterValue | Enter a value | Voer een waarde in | Saisir une valeur | Wert eingeben |
filter.removeFilter | Remove filter | Filter verwijderen | Supprimer le filtre | Filter entfernen |
notifications.created | created | created | created | created |
notifications.updated | updated | updated | updated | updated |
notifications.deleted | Record deleted | Record deleted | Record deleted | Record deleted |
notifications.actionPending | Processing… | Processing… | Processing… | Processing… |
notifications.actionSuccess | Done | Done | Done | Done |
notifications.actionFailed | Action failed | Action failed | Action failed | Action failed |
notifications.actionError | Something went wrong… | Something went wrong… | Something went wrong… | Something went wrong… |
validation.required | This field is required | Dit veld is verplicht | Ce champ est obligatoire | Dieses Feld ist erforderlich |
admin.title | {title} Admin | {title} Beheer | {title} Administration | {title} Verwaltung |
auth.signInWith | Sign in with | Aanmelden met | Se connecter avec | Anmelden mit |
auth.accessDenied | Sign-in failed or this account has no access. | Aanmelden mislukt of dit account heeft geen toegang. | Échec de la connexion ou ce compte n'a pas accès. | Anmeldung fehlgeschlagen oder dieses Konto hat keinen Zugriff. |
Overriding a bundled string
Add a ui section to your translation file. Only the keys you specify are overridden; the rest come from the built-in defaults.
// translations/nl.json
{
"ui": {
"actions": {
"save": "Bewaren"
}
}
}Adding a language not bundled
Add a full ui section for that language in its translation file:
// translations/es.json
{
"ui": {
"table": {
"search": "Buscar...",
"filters": "Filtros",
"addFilter": "Añadir filtro",
"addRecord": "Añadir registro",
"editFields": "Editar campos"
},
"actions": {
"save": "Guardar",
"cancel": "Cancelar",
"close": "Cerrar",
"edit": "Editar",
"delete": "Eliminar",
"view": "Ver",
"create": "Crear",
"retry": "Reintentar",
"reset": "Restablecer",
"apply": "Aplicar"
},
"modal": {
"update": "Actualizar",
"create": "Crear",
"deleteTitle": "Eliminar registro",
"deleteMessage": "¿Está seguro de que desea eliminar? Los datos se perderán."
},
"autoSave": {
"saving": "Guardando…",
"saved": "Guardado âś“",
"pending": "Complete los campos obligatorios para guardar",
"error": "Error al guardar"
}
}
}Accessing ui keys in custom components
const { t } = useLanguage();
t('actions.save'); // "Opslaan" (when lang = nl)
t('table.filters'); // "Filters"
t('unknown.key'); // "unknown.key" (key itself as fallback)
t('unknown.key', 'My fallback'); // "My fallback"No i18n library is needed. The dictionary is a plain nested object; t() does a dotted-path lookup.
Column-level translation properties
Each column in a resource exposes two translation-related fields in the /schemas payload:
labelKey
The dotted translation key used to look up this column's label. Auto-generated as:
resources.<resourceName>.columns.<columnId>For example, a status column on the book resource uses key resources.book.columns.status.
You can override labelKey per column in resource.json:
{
"columns": {
"status": {
"label": "Status",
"labelKey": "shared.columns.status"
}
}
}Useful when multiple resources share the same column and you want one translation key for all of them.
enumName
Links a column to an enum translation group. When set, the frontend translates { value, label } cell values using:
enums.<enumName>.<value>Set via the enum field on the column in resource.json:
{
"columns": {
"status": {
"label": "Status",
"enum": "bookStatus"
}
}
}Translation file entry:
{
"enums": {
"bookStatus": {
"draft": "Concept",
"published": "Gepubliceerd",
"archived": "Gearchiveerd"
}
}
}Client-side translation
The frontend fetches a lightweight translation bundle from GET /_app/translations on startup and on language switch. It applies translations client-side via localizeDefinition, using labelKey for column headers and enumName for cell values. This means:
- Column headers and enum cell values update instantly on language switch without a full page reload.
- The bundle only contains
ui,validation,resources, andenumskeys — not the full JSON Schema titles (those are still translated server-side viaAccept-Language).
Status page
When translations are active, the status page (/crouton/status.json) includes an i18n section showing:
- Configured languages and default language
- Key count per language bundle
- Number of untranslated (empty) keys per language
This helps identify incomplete translations at a glance.