Non-English Variable, Function, and Symbol Names in Code

Recently, I switched jobs from karriere.at, Austria’s largest job platform, to the Austrian Federal Computing Centre, where my colleagues and I work on modernizing Austria’s digital tax services.

One of the first things I noticed, looking at the new codebase, was that we heavily use German terms for naming certain classes, functions, and variables. At first, this seemed to me like a giant red flag.

After all, at my previous job, a pet peeve of mine was to call out the wrongful naming of a “homeoffice” column in our database (which seems like it is English but really is the German word for “work from home”). I wasn’t willing to tolerate German words in our codebase (even if they looked like English words). But now, after seeing the problem through a different lens, I realize that in many instances, it can make a lot of sense to use our native tongue to name certain things in our codebase.

Domain-Specific Languages and Internationalization

A common mistake in the German web sphere is to translate the German word Impressum to Imprint. In some instances, it might be the correct translation, yet in the case of websites, it isn’t. In the domain of the German web, Impressum is a legal term with a particular meaning not well reflected by the English word Imprint. Here is how smashingmagazine.com, located in Freiburg, Germany, is handling this conundrum:

Because websites published in Germany (and Austria) are subject to the Impressumspflicht (the legal obligation to state who is responsible for the publication of a website or printed material), Smashing Magazine explicitly uses the German legal term Impressum in addition to the English About us although the rest of the website is English only.

There is no 1:1 translation to other languages for many terms, especially for many legal terms. Translating these terms in our codebase can be confusing at best and, at worst, lead to legal issues or errors due to misunderstandings of a word’s precise meaning in a particular context.

You Wouldn’t Translate Names of Persons, so Don’t Translate Names Within Your Problem Domain!

My name is Markus Oberlehner, and that’s how I introduce myself to people of any language. Yet, technically, we could translate Oberlehner to something like Upper tenant, Upper landholder, or Top leaseholder. But we can quickly see two problems with that:

1. There are various ways how to translate my name.
2. If we’d translate names, they wouldn’t serve their purpose anymore, which is to identify a particular person.

In my new problem domain, Austrian tax law, there are many words we can’t easily translate into English without altering their meaning. Let’s take Familienbeihilfe for example. This isn’t simply one of those long German words the English-speaking world likes to make fun of; the word Familienbeihilfe is the name for a particular kind of subsidy for families defined by Austrian tax law. Even in other German-speaking countries like Germany and Switzerland, the same word could have a different meaning!

What is true for names of persons is also true for certain words we use in particular problem domains. Sure, there are literal translations for Familienbeihilfe like family allowance or child benefit. But first of all, there are multiple possible translations, and second, they’re not unambiguously referring to the one thing codified in the Austrian tax law, the one and only Familienbeihilfe.

❌
const enrollForChildBenefits = ({ taxpayer, children }) => {
  // ...
}

✅
const enrollForFamilienbeihilfe = ({ taxpayer, children }) => {
  // ...
}

Which Words Should We Translate?

Let’s go back to the problem domain of my previous job at karriere.at. In general, I’d say that in the job marketplace domain, most words can be easily translated into English (if we do not already use the English terms anyway, as we do with Job, for example). The German word for Application is Bewerbung, and if you apply for a Job in German, you bewirbst dich für einen Job. There is no ambiguity here.

But what about my pet peeve, which I mentioned earlier? Using Homeoffice, the “German” word for both (!) an office at home and work from home. At karriere.at, we primarily used it to mean work from home, which I thought (and still think) was not correct because we strived to use English terms for everything else.

Yet, it is not as clear-cut as it seems. And here, my old and new problem domains converge. The neo-German term Homeoffice found its way into Austrian law as the Homeoffice-Maßnahmenpaket. Again, while with Homeoffice, there is a clear and unambiguous way to translate it (work from home), with Homeoffice-Maßnahmenpaket, there is not. The Homeoffice-Maßnahmenpaket, which we can (or rather can not) translate to work-from-home measures package, includes measures to regulate both working from home and tax benefits for furnishing your home office, the Home-Office-Pauschale (note the different ways of spelling Homeoffice when describing work from home and Home-Office when talking about the home office in the sense of an office room at home).

So now that I confused you with my thoughts on how Homeoffice is actually a German word and why we should translate it in one problem domain (job marketplace) but not another (Austrian tax law), let’s come up with a straightforward rule of thumb when and when not to translate non-English words in our code.

Ask yourself:

To an English-only speaker, would translating a term be more helpful or more harmful to understanding the underlying problem our application is dealing with?

For example, in the job marketplace domain, if you want to enable people to filter jobs by the possibility of working from home, using the German term Homeoffice also on our English page would be rather confusing because an English-only speaker might wonder if it is a prerequisite that you have a fully furnished home office to qualify for this job.

Yet when it comes to doing your taxes online, literally translating the Homeoffice-Maßnahmenpaket to work-from-home measures package or Homeoffice-Pauschale to work-from-home allowance would make it more confusing because no official sources are referring to those literal English translations, and there are various other ways how you could translate those two terms. Furthermore, translating names for certain things makes them ambiguous. While Homeoffice-Maßnahmenpaket and Homeoffice-Pauschale are the official terms used by the tax authorities, a work-from-home measures package or work-from-home allowance might also refer to something your employer does to support its employees working from home.

All or Nothing?

Now, if our problem domain deals with many name-like terms that can’t easily be translated, wouldn’t it be more straightforward to use our native language for the whole of our domain-specific language (DSL)?

✅
const beantrageFamilienbeihilfe = ({ steuerzahler, kinder }) => {
  // ...
}

This is a valid option! Yet even when going down the path of using our native language for our whole problem domain, I still recommend sticking to English when dealing with logic outside of our core problem domain:

❌ (German)
const zeigeBenachrichtigung = ({ titel, nachricht }) => {
  // ...
}

❌ (Spanish)
const mostrarNotificacion = ({ titulo, mensaje }) => {
  // ...
}

❌ (French)
const afficherNotification = ({ titre, message }) => {
  // ...
}

✅ (English)
const showNotification = ({ title, message }) => {
  // ...
}

Although using only our native language for the DSL of our problem domain has its perks, I still only recommend it if we’re 100% certain that we’ll never internationalize our product and don’t plan to hire any people unfamiliar with our native language. In my experience, the only situation where this is realistic is when you’re working in the US, and if that’s the case, why are you even reading this article? So, in practice, our best bet is to use our native language only for terms without unambiguous English translation and translate everything else.

I highly recommend you document your DSL in both languages so there is no ambiguity about which English word to use for a particular native term. For example, we could translate the English enrollFor in the enrollForFamilienbeihilfe function from above to German in many ways, like beantrage and anmeldenFuer. By having a single source of truth in the form of our DSL documentation, we remove any ambiguity.

Wrapping It Up

When translating a term to English makes it easier for English-only speakers to understand the true and unambiguous meaning of a term, we probably also should translate it in our code. But when translating would make it ambiguous, we better go with the original term, even if it looks weird to see a mix of English and non-English terms in our codebase.

Always document your DSL to clarify which terms we translate to English and how, and which we aren’t because they act as unambiguous, non-translatable names instead of generic, translatable terms.