Tutorial :GB English, or US English?


If you have an API, and you are a UK-based developer with a highly international audience, should your API be




(To take one word as a simple example.)

UK-based engineers are often quite defensive about their 'correct' spellings but it could be argued that US spelling is more 'standard' in the international market.

I guess the question is does it matter? Do developers in other locales struggle with GB spelling, or is it normally quite apparent what things mean?

Should it all be US-English?


I would tend to use US-English as that has become the norm in other APIs. Speaking as an English programmer, I don't have any problem using "color", for example.


I'm not a native speaker. In writing, I always try to use en-gb. However, in programming I always use en-us instead of British English for much the same reason that I don't use German or French for my identifiers.


Depends where you see most of your customers. I personally prefer using English-GB (e.g. Colour) in my private code, but I go to Color for externally published applications/API/code!


Generally I would be a stickler for GB spelling but I think that the code reads a lot better if it is consistent and I find:

Color lineColor = Color.Red;  

to look a lot better than:

Color lineColour = Color.Red;  

I guess that ultimately it doesn't really matter.


Even though I'm usually very pedantic about correct spelling, as a UK developer I would always go with the American 'color' spelling. In all programming languages I've encountered, it's like this, so for the sake of consistency, using 'color' makes a lot of sense.


Assuming this is a Java or C# API it probably doesn't matter given the pervasiveness of auto-complete functionality in the IDEs. If this is for a dynamic language or one where modern IDEs aren't the norm I would go with the American spellings. Of course I am an American and am therefore obviously biased, but it seems like most of the code I see from developers who aren't native English speakers use US spellings for their variable names etc.


As an English programmer, I use en-US for my software dev. American english dominates so well in almost every other API that it's much easier to stick to one type of spelling and remove the ambiguity. It's a waste of time searching for a method only to find the spelling is off by one letter due to spelling localisations.


I would go with current standards and pick the US English spelling. HTML and CSS are acknowledged standards with the spelling "color", secondly, if you are working with a framework like .NET then chances are you already have color available in different name spaces.

The mental tax on having to deal with two spellings would hamper rather than help developers.

Label myLabel.color = setColour();  


I have trouble with APIs that are not in US-English. Just because of the spelling differences. I know what the words mean but the different spelling trips me up.

Most of the libraries and frameworks I'm familiar with use the US spellings. Of course, I'm an American so... US-English is my native language.


The majority of the development documentation (just like MSDN) is in American English.

So it might be better to stay with the main-stream and use American English in your API if you are targeting international audience.


I got another sample: Serialise and Serialize. :)

Personally, I don't think it matters much. I've worked on projects that were using UK-English spelling countries and they use the UK spelling. It still is English and it doesn't really matter much due to Intellisense.


As a Canadian, I run into this all the time. It's very difficult for me to type "color" as my muscle memory keeps reaching for the 'u'.

However, I tend to adopt the language of the libraries. Java has the Color class, so I use color.


I try to find alternative words if possible. I will let -ize slide. For Colour I could possibly use Hue, Ink, Foreground/Background...

If not, as an Englishman, I will use en-GB because I have some pride left in my country and origins.

If it was to be part of a bigger project however, especially an international one, I would keep the entire project consistent above having a small part be in one language variation and the rest in another.


I'm also going to have to side with US-English, simply to keep things consistent (as others have already noted here). Although I am a native US-English speaker, I have done software projects with both German and Swedish software companies, and in both cases the temptation occasionally would strike my teammates to use German or Swedish text in the code -- usually for comments, but sometimes also for variable or method names. Even though I can speak those languages, it's really jarring on the eyes and makes it harder to bring a new non-speaker into the project.

Most European software companies (at least the ones I've worked with) behave the same way -- the code stays in English, simply because that makes the code more international-friendly should another programmer come on board. The internal documentation usually tends to be done in the native language, though.

That said, the distinction here is about two different dialects of English, which isn't quite as extreme as seeing two totally different languages in the same source code file. So I would say, keep the API in US-English, but your comments in GB-English if it suits you better.


I'd say look at how other libraries in your language choose and follow their convention.

The designers of the programming language and its built-in APIs made a choice, and whether the users are international or not they are used to seeing spellings consistent with this choice. You are not targeting speakers of a different language but users of a programming language. Odds are they've learned quite a few words in the foreign language from the built-in APIs, and they might not be aware there's differences between US English and GB English. Don't confuse them by switching sides of the pond.

I use .NET languages primarily, and the .NET Framework uses US English spellings. On this platform, I'd stick with US English. I'm not aware of any languages standardized on GB English, but if yours has done so then by all means stay consistent with the language.


I agree with the "go for American" troupe. I myself prefer en-GB when writing e-mails and such, but American English is pretty much the standard in all programming circles.


Even though British English is what is spoken throughout the world - I recommend using American English which like other people have said dominate the market.


Definitely US english.


First, I'm in the US. In my current project, it's always "color" however, the word we can't seem to pick a spelling for is "grey" vs "gray".

It's actually gotten quite annoying.


I'm one of these people who's heart rate and blood pressure rises each time I'm forced to use American English in setup files, etc, due to the fact that the software doesn't give the option for British English, but that's just me :)

My personal opinion on this one however would be to provide both spellings, give them setColor() and setColour(), write up the code in one of them, and just have the second one pass the parameters through.

This way you keep both groups happy, granted your intellisense gets a bit longer, but at least people can't complain about you using the 'wrong' language.


Selection of language for identifier names has nothing to do with audience and everything to do with the original language in which the framework or API was developed.

I don't know very many languages but I cannot think of a single one that uses anything other than US English.

The dangers of introducing subtle bugs due to different spellings are too great IMHO.

A function override can easily become an pseudo-overload.

A config file could become invalid due to difference in spellings.

A situation might arise where the same conceptual object has been defined using multiple classes, using both en-US and en-GB.

So therefore, whether a piece of code is purely for internal use or intended for external use as well, the spellings used must always match the original language of the platform/framework/compiler/API.


If all of your programmers are British, use en-gb. If your code will be seen by programmers outside of Britain, then en-us would be a better choice.

One minor point, we rely on a translation service to copy our documentation in to other languages. We have found we get better translations when using en-us as the source.


You need to consider your audience. Who is going to use the code and what are they expecting to see?

I work in a company that has offices in both Canada & US. We use Canadian spelling (very similar to British English) when producing documentation and code in Canada and US spelling for what is used in the US.

Some things cross borders, but the difference in spelling is rarely an issue. It acutally can generate some interesting dialogue when American's are not aware of different spellings for Candian and British English. Sometimes they are OK with it, othertimes they insist on it changing to the "correct" spelling. This also affects date formats (dd/mm/yyyy in Canada and mm/dd/yyyy in US)

When there is an impasse, we typically go with the US spelling since the people in Canada are familiar with both variations.


The main reason I've heard for choosing US over UK English is because the UK audience, when confronted with US spelling, realise it's a US application (or presume it is so), whereas a US audience confronted with UK spelling thinks '... hey, that's wrong.. it's color not colour'

But like others have said, standardise. Pick on and stick with it.


It comes naturally for me to work in UK English without even thinking about it. However, if you are developing internal procedures it doesn't really matter. If you are creating APIs that will be used publicly, and your audience is international, why not implement both?


I prefer US English.


If you look back a few hundred years, you will find the change has nothing at all to do with the US, much as many would think so. The changes stem from European influences, particularly the French. Before that time, the English word "colour" was then actually spelt "color".

To try to standardise would be futile as half of Chinese children are learning the pre European influence and US understanding of English, while the other half are taking it up as it stands today, as the English language.

If you think language is a problem, then you should consider the Taiwan Kg which weighs in at 600g. I've yet to find out how they managed that one, but I hope they are never employed as aircraft fuelling personnel!


I always use en-GB for all my programming. I guess it's due to a heavy influence of British novels.

However, might it not be possible to have two different sets of APIs (one for en-US, one for en-GB) which internally call the same function? This might bloat the header files though, so maybe depending upon a preprocessor definition, a conditional compilation? If you're using C++, you could do something like below...

#ifdef ENGB       typedef struct Colour       {        //blahblahblah       };       void SetColour(Colour c);  #else      typedef struct Color      {        //blahblahblah      };      void SetColor(Color c);  

Next Post »