Ubiquitous Language in a non-english domain

As a German company with mostly German clients, this is a situation we encounter every day. Over the past twenty years, we have pursued different approaches to deal with language in our projects, some more successful than others.

The decision for a specific language in the domain model has far-reaching implications and a long life span, so we felt it was crucial to reach consensus within the team and establish a binding regulation.

It is also important to note that this regulation has no automatic consequences for related questions. For example, a decision for German does not mean that we will never employ non-German native speakers in the future. If our conditions change (e.g. different team composition, remote work), we will reopen the discussion.

The obvious question is whether we choose German or English. We quickly noticed that each of us has distinct personal habits and preferences.

Unfortunately, there are no definite rules that allow a clear decision for all use cases. Code, comments, commit messages and documentation are aimed at different audiences which can in turn benefit from different language choices.

The following is a (translated) excerpt from our internal knowledge base and documents our results.

Basics

The choice of language is an important topic in every project: The principle of Ubiquitous Language prescribes the use of an all-encompassing language from technical discussions and analysis with customers to writing code and documentation. Technical terms from the project's business domain should be used literally in the source code.

Building on the rationale behind Ubiquitous Language as a concept, we have coined this ground rule to help us in our discussions:

Our choice of language aims to minimize cognitive load (e.g. translations).

We want to avoid inconsistencies and miscommunication due to translation problems or misunderstandings and, if possible, even make a project glossary unnecessary.

That means that specialized concepts should not have to be "mentally mapped" to structurally different contexts in code, nor should there be translations of technical terms e.g. from German to English.

In our current setup, German is the native language for all team members. It is therefore also the language in which we can best assess linguistic nuances and differences of meaning and choose specific terms. When we express ourselves in English, we may not even notice the inaccuracies or ambiguities that we create for a native speaker.

Language in the code

We keep all terms, particularly in domain-specific parts of the code base, in the language we use to communicate with the customer.

This simple rule could get complicated if the customer is internationally positioned and has several internal languages. We will then take care to agree on English terms for the customer's technical concepts and also use these when we conduct a conversation in German.

It is helpful to consciously make this decision at the beginning of a project and document it in a kind of "charter", as in the end it is less important what language is chosen compared to the fact that there is a conscious and documented decision, which is also "lived" by all parties (customers and developers).

If we write code that we want to release as open source, we generally have an international (specialist) audience. It follows:

Open source code is written completely in English - unless it is aimed at a non-English domain.

Another rule that is derived directly from the principle of Ubiquitous Language is:

Language and terms are used uniformly and consistently in all parts of the code, e.g. PHP, HTML, Javascript, CSS etc.

As an example, it is considered bad practice to create a view template suchergebnis.twig.html and use search-result as class name inside the HTML.

On the other hand, most of the commonly used frameworks, tools, patterns etc. are created or conceived of in English. Because we still want to avoid cognitive load caused by translations, it follows that

Set professional expressions and framework conventions are preserved. Examples are get...() ,  set...() ,  ...Controller ,  ...Factory ,  ...FormType or common usages like click(), toggle(), submit() .

Perhaps one can say that the closer we are to the "infrastructure" layer, the more appropriate the language of English is in the code.

Documentation

For documentation that is intended to be shared with the customer, the same principle applies: We keep it in the language that we speak with the customer.

Language in comments, commit messages, and readme files

Comments, commit messages, readme files, etc. are nothing but postponed ("asynchronous") explanations to colleagues or our future self, which is why they should be written in the language that we would use to talk with the same person if she was sitting right in front of us.

Write a comment exactly how you would say it out loud in a conversation with a colleague.

The difference to the code is that we share terms from the code with the customer, while comments etc. are mostly notes for ourselves. 

Open source projects are, again, treated differently, as the audience is bigger than just our team: Comments, commit messages and all other documentation are written solely in English.

In closing

We are aware that this strong commitment to German might entail future costs of various kinds, if at any point German no longer were to be the intuitive choice of language for our team.

However, we do not think it makes sense to accept very real issues like ambiguous expressions, misunderstandings and translation errors just to avoid theoretical problems in the future.

Also, any non-German native speaker will most likely need to have at least sufficient command of German to be able to understand the key concepts of our German customers' domains - and then this problem is not any "worse" than an English term would be for us today