Programming on a Non-English Project; best practices

As a Dutch webdeveloper, I see mostly Dutch websites being built. And I see many team struggling with how to do this well. I developed a set of best practices, which I want to share and discuss.

If your entire teams’ first language is English, this post is probably not for you. And if you are the kind of person who thinks “are there actually people out there who write Russian code, Swedish documentation or use Dutch classnames? WTF?” this post is probably not for you either (But take this with you before leaving: there are. A lot).

Edit: as offbytwo, a redditor kindly points out, it is non-English, not none-English. Guess that proves that I am none-English (sic) to begin with :).

The Client.

They will most probably communicate in your local language. Not in English. They want to produce their specifications, requirements and even designs in their native language. This input is therefore not-English.

It makes no sense trying to enforce this in English, that only creates friction in an area (feedback, requirements) where you want as little friction as possible. If anything, you may want to designate one person to translating this input before it goes into your other systems. But often it is good enough to simply put the non-English input as-is into your project.

The Team.

You might have one or two developers whom you have to communicate in English with. Either because you outsourced stuff, or because you are collaborating in Open Source, or because you have people on your team from abroad.

But even when you don’t, having all the technical communication in English pays off: all your developers understand and can write some English; but not all your potential developers speak your native tongue.

Standardising on English now, allows you to pull in such developers later. Standardising on your native language now, shuts a giant pool of potential collaborators out. Forever.

Code

All code should be English. Always. No exceptions allowed. Programming-languages, libraries and tools are all in English, so if anything, using your native language will only add inconsistency. Sure, if there is an all-Dutch programming-language, you would be writing all your code in Dutch. But such languages are rare or nonexistent.

class GebruikersController extends Controller {
  //Maakt een nieuwe gebruiker aan op basis van zijn identifier.
  def __construct($gebruikers_id) {
    //@TODO: maak de eigenlijke code
  }
}

There. I just used 5 pure English words and statements, 2 mixed words (Gebruikers-Controller and gebruikers-id_entifier_) and a load of Dutch words that no-one but a Dutch speaking person can understand.

All your objects, classes, variables, function and whatnot should be English. Always. When you are programming a shop, you don’t call that class InnKaupaKörfu < ActiveRecord but rather just Cart < ActiveRecord. Code, databasetables, tools and whatnot should be in one language only. Defaulting to English.

Documentation

When your code is all in English, a large part of your documentation will automatically be in English. It makes no sense, therefore to have the other documentation in another language.

Just default to English.

With one exception, being the input you receive from your clients. If this input is passed on to English speaking colleagues, you will need to translate it, but in that case, keep the original with the translation. In that case, you will need to appoint one person, e.g. a project manager or lead developer with the task to do the translating. And you’ll need budget for that, obviously.

Configuration and Integration

In tools like Drupal, a lot of the building is done trough UI’s within Drupal itself. Things like fields (title, body, images, colors etc.) on articles, article-types and even entire pages (views) are configured trough the interface.

Often these are made in the native tongue. That is not a good practice. Just give all these components English names. So don’t call the color-field on your “product”, couleur, or χρώμα. But rather just color.

The reason is that in situations like these with Drupal, but also Expression-engine, Typo3 and such, these names are then used all over the place. Ranging from database names, column-names to variables and autogenerated classes.

It is very ugly having to work with template-files called overzicht_block_content or les_plus_lus_page_header.

Because these names trickle through to your code, keep them English. Else you will be forced to break rule #1: all code is in English.

Interface strings

Quite often, you will be building your application in one language only. It makes little sense to write it in English first, when you are 100% certain that it will never be used in English.

In that case, simply don’t use the full text for the interface. Rather than "Thank you for registering".t, simply use tokens or symbols: "registration.messages.thankyou".t. Many languages and platforms already require this. But some have the default standards to write the full texts throughout your application. In that case, just ignore that standard, when English is too much hassle. Anything is better than having your code filled with pieces like "ขอบคุณสำหรับการลงทะเบียน".t. Only a Thai developer has any idea what is going on there; whether it is one word, two, a sentence or a token?

Obviously, this means using some kind of translation framework. But nearly every language and platform has these either built-in or as default add-on. And if not, you are probably working with the wrong tool, considering you are building a localized application in the first place.

Revision control

While many teams do adhere to the guidelines that code, and everything around it is English, their commit-messages are local.

The funny thing, however, is that I have never seen a team write only-Dutch commit-messages. They often mix English messages with Dutch. And when upstream software is English, you’ll see that even more.

In all cases, it is best to just use English for commit-messages. For one, because you will be referring to (English!) code in the messages, but also, because mixing English and non-English requires more mental energy from the reviewer, when she or he has to toggle all the time.

There is only one reason to write commit-messages in your native tongue: when otherwise people don’t write them at all. Anything lowering the barrier that makes people write good messages is good. No commit-messages is definitely worse than non-English messages.

Bug tracking

When bugs are only managed within the team, just stick to English here too. You already write most of your documentation in English, your commit-messages in English and obviously your code too. Why then, write your bugs in another language. It only adds inconsistency and might (will!) even lead to confusion and more bugs. Like when the shopping-cart is called “shopping-cart” all over your product, but suddenly a bug-report mentions that the “ostukorvi” is not working. Suddenly! Confusion over already established concepts like “the shopping-cart-icon”, versus the “shopping-cart-process”.

Only when you clients write bug-reports, should you leave them in your native tongue. Here too, you want to remove any friction from your client submitting reports (you do, don’t you?).

I’ve seen three successful methods here:

The Bug-reporting was closed for the client, they emailed issues to their contact. The contact then translated it to English and translated it to an actual usable bug-report (i.e. turn “problem with site, clicking on header not well” into “JS-overlay placing DIV over clickable area in header”). Two wins.

The Bug-reports were made in Dutch and followed up in Dutch too. But from there, the person working on it translated everything. In commit-messages, when referred to an issue the title was quoted. Like

"Fixed issue 1337 "Problemen met video. METEEN REPAREREN!!!" by
adding new CDN-urls to javascript for players.

Bug-reports were made in a separate environment and followed up in an English-only workflow. Feedback and updates for the clients were in Dutch, in the “clients-issue-tracking”, yet in-house everything remained English.

What do you think? Is English bringing your productivity down? Do you consider your cultural heritage important enough, to decide to write code in your native tongue? Are you in a team where people don’t speak a word of English? (and how can they program, in that case?)