I just had an interesting chat where it became clear that some people are a little confused about the differences between a data model, and how we display (or verbalise) a data model, for a given locale.

Data models are locale neutral. They are a description of the shape of your data for a given domain.

For example, you might model a customer:

concept Customer {
o String firstName
o String lastName
o String email
}

Now, I’m British and I am writing this post in English, so the words “Customer” , “firstName” etc. are (mangled) representations of English words. You can consider these to be the “technical names” for these concepts, and in this case we’ve chosen to use a form of technical English for these.

If we want to create a web form to create a customer in English, it would look something like:

New customer

Email address: [__]
First name: [__]
Last name: [__]

The same form in French might look like:

Nouveau client

Adresse courriel: [__]
Prenom: [__]
Nom: [__]

The display labels (aka vocabulary terms) for model elements are stored alongside the model, but are distinct from the model itself. In Concerto they are stored in vocabulary YAML files, and managed by a VocabularyManager. The VocabularyManager understands that locales are hierarchical and allows you to selectively override terms from a base locale. For example, a vocabulary for the “en” locale might define the label for a concept Color as “a color”, while a vocabulary file for the locale “en-GB” would define the term as “a colour”.

You should use a Vocabulary whenever you need to display models to end-users, localising the labels based on their preference, or web-browser locale. This could be the column headings in a data table that displays query results, the labels in a form to create/update instances, or in a query builder that allows end-users to construct queries based on property values.

You should keep your data models themselves locale neutral, allowing you to interact with the models from all the locales your applications support, and remember, syntax is not semantics!