Fabulous Adventures In Coding : localization

Properties vs. Attributes

Eric Lippert — Tue, 03 Feb 2009 00:02:26 GMT

Here is yet another question I got from a C# user recently:

I have a class that represents a business rule. I want to add some rule metadata that could be used by consumers to retrieve a friendlier rule name, description, and anything else that makes sense. Should this information be exposed as an attribute or property on the class?

I would say to absolutely go for a property in this case, for four reasons.

First, properties are highly discoverable. Consumers of this class can use IntelliSense to see that there is a property on the class called "Description" much more easily than they can see that there is an attribute.

Second, properties are much easier to use than attributes. You don't want to muck around with the code to extract strings from metadata attributes unless you really have to.

Third, data such as names and descriptions is highly likely to be localized in the future. Making it a property means that the property getter code can read the string out of a resource, a resource which you can hand off to your localization experts when it comes time to ship the Japanese version.

And fourth, let's go back to basic object-oriented design principles. You are attempting to model something -- in this case, the class is modeling a "business rule".

Note that a business rule is not a class. Nor is a rule an interface. A rule is neither a property nor a method. A rule isn't any programming language construct. A rule is a rule; classes and structs and interfaces and whatnot are mechanisms that we use to implement model elements that represent the desired semantics in a manner that we as software developers find amenable to our tools. But let's be careful to not confuse the thing being modeled with the mechanisms we use to model it.

Properties and fields and interfaces and classes and whatnot are part of the model; each one of those things should represent something in the model world. If a property of a "rule" is its "description" then there should be something in the model that you're implementing which represents this. We have invented properties specifically to model the "an x has the property y" relationship, so use them.

That's not at all what attributes are for. Think about a typical usage of attributes:

[Obsolete]
[Serializable]
public class Giraffe : Animal
{ ...

Attributes typically do not have anything to do with the semantics of the thing being modeled. Attributes are facts about the mechanisms - the classes and fields and formal parameters and whatnot. Clearly this does not mean "a giraffe has an obsolete and a serializable." This also does not mean that giraffes are obsolete or serializable. That doesn't make any sense. This says that the class named Giraffe is obsolete and the class named Giraffe is serializable.

In short: use attributes to describe your mechanisms, use properties to model the domain.

JScript, Localization and Those Wacky Newfoundlanders

Eric Lippert — Tue, 18 May 2004 19:25:00 GMT

I was talking about localization in general the other day. Today, some brief notes on localization in JScript Classic.

A while back, a coworker asked me:

Does toLocaleString() do anything different than toString() when locale changes? I am especially interested date formats when you run code in a place inside the United States that has weird Daylight Savings Time rules.

That's actually quite a complicated question. I'm going to break that down into many sub-questions.

What locale does JScript Classic use when it needs to change its output based on locale?

It depends on the host. JScript and VBScript have their own locale settings which may be independent from the host, user and machine settings. A web browser host could, for example, set the script engine to be French if it were displaying a French web page.

IE has changed their algorithm (both intentionally and accidentally) many times over the years. Sometimes they used the locale of the user, sometimes they always defaulted to US-English. I believe we are now in "always default to US-English" mode in IE. It's confusing because the script engines have the ability to change the locale used for the error messages independent of the locale used to format dates, numbers, etc. This allows for exotic scenarios like a VBScript host which displays French error messages while running scripts which use Japanese date formats.

I am not aware of any hosts which actually use these features! We added them when IE4 shipped, but it turned out that IE didn't need the feature after all. However, in the interests of completeness, I'm going to document JScript's behaviour as though there actually were a host that exposed this feature.

How many methods are there in JScript intended for localization, and what are they?

Nine. On the String prototype there are three: toLocaleLowerCase, toLocaleUpperCase and localeCompare. The Date prototype has toLocaleDateString, toLocaleTimeString, and toLocaleString. The Array, Object, and Number prototype objects each have an implementation of toLocaleString.

Do any of these methods change their output when the script engine is in a different locale?

Yes, eight of them do. Of course, they depend on the script engine locale, which as I noted above may different from the user locale, depending on the whim of the script host.

Object.prototype.toLocaleString simply calls toString. No localization behaviour here unless of course you have overridden the prototype.

Array.prototype.toLocaleString uses the operating system's localized list separator and recursively calls toLocaleString on each of its members to generate a localized, comma-or-whatever-your-locale-prefers separated list.

Number.prototype.toLocaleString uses GetNumberFormat to get the number separator and decimal point. If for any reason that fails, we fall back to OLE Automation's VariantChangeTypeEx, which is locale-sensitive.

Date.prototype.toLocaleDateString, toLocaleTimeString, and toLocaleString are complicated by some bizarre weirdnesses in the Win32 NLS API. To work around various problems, only dates between 1600 and 10000 AD are localized. Hebrew date formats for years after 2240 AD are also not supported. Once we jump through those hurdles, the Win32 APIs GetDateFormat and GetTimeFormat are used to format the strings. (I'm vaguely recalling that there was also a bug in there involving the Thai calendar but I don't remember the details.)

String.prototype.toLocaleLowerCase, toLocaleUppercase, toLowerCase and toUpperCase are buggy -- they use the default user locale, not the script engine locale. Looks like I was careless when I implemented the script engine locale feature. I wouldn't expect those bugs to be fixed any time soon, since as far as I know, I'm the first person to find the bugs since I implemented them!

They just use LCMapCase to change the case of a string using the localized rules.

String.prototype.localeCompare uses the script engine locale to call CompareString on two Unicode strings.

What about Daylight Savings Time?

The JScript runtime library always determines the local time zone offset by calling into various operating system APIs. If the operating system gets the DST calculation right in whatever weird state you're in, JScript will also get it right. If the operating system gets it wrong, complain to the Windows guys, not me.

Speaking of that, exactly which of the United States have weird Daylight Savings Time rules?

They are Alabama, Alaska, Arkansas, California, Colorado, Connecticut, Delaware, Florida, Georgia, Idaho, Illinois, western and eastern portions of Indiana, Iowa, Kansas, Kentucky, Louisiana, Maine, Maryland, Massachusetts, Michigan, Minnesota, Mississippi, Missouri, Montana, Nebraska, Nevada, New Hampshire, New Jersey, New Mexico, New York, North Carolina, North Dakota, Ohio, Oklahoma, Oregon, Pennsylvania, Rhode Island, South Carolina, South Dakota, Tennessee, Texas, Utah, Vermont, Virginia, Washington, West Virginia, Wisconsin and Wyoming.

These bizarre states actually legally mandate millions of people to change their clocks twice a year in a confusing, pointless and error-prone light-saving gimmick.

Arizona, Hawaii and central portions of Indiana have a single, sensible, simple DST rule: "we do not observe Daylight Savings Time."

For what it's worth, My Home And Native Land doesn't fare much better. All young Canadians grow up knowing the phrase "Coming up at two-o'clock-two-thirty-in-Newfoundland..."

A half-hour timezone? What the heck?

Yep. They're half an hour ahead of the rest of us in Newfoundland. One year Newfoundland decided to try an experiment in "Double Daylight Savings Time" -- they sprang forward TWO hours. Of course, they were already sprung forward half an hour as it was. It didn't get dark until 11 PM. There was no end of problems. The failed experiment was described in the Newfoundland assembly a few years later like this:

We were up all night, all day; we could not get to sleep. You could not get a coffee in the morning at Tim Horton's because there was no coffee; there was no morning. It was just going around - the sun never set. Newfoundland - the place where the sun never set. I think the Minister of Environment at that time was the honourable John Butt. I believe he led the way in that great endeavour. He had Newfoundlanders going around - they did not know whether they were asleep, whether they should go to bed, whether they should get up. I think it was at 1:00 a.m. that we used to get a little bit of dusk, and before you knew it, it was daylight again. John even had the sun running the way he wanted it. He had the sun slowed down. That is how the Tories operated. He said he did that after consultation with the people. The only thing he consulted with must have been a crystal ball or something. He must have looked into a crystal ball, because before half the summer was out, the Premier of the day was trying to have the time switched back again.

Somehow I managed to segue from localization rules to Newfie partisan politics; this would probably be a good time to stop.

Some LΘ℃αℓization Questions

Eric Lippert — Tue, 11 May 2004 01:47:00 GMT

A reader asked me a few questions about localization the other day. That's not a subject that I have a lot of experience on, but I can speak to it a bit. (I know that I've seen a blog from a Microsoft localization PM somewhere in the last six months, but cannot for the life of me remember who, and my google-fu has failed me. Anyone know about whom I'm thinking?)

If your employer does not have a "current need" but maybe a "future need" for internationalization, how far do you go while coding?

Hard question. Accessibility and localization have a lot in common; both are about making software usable by people who may have quite different UI needs than the "typical" user. My friend and world-famous accessibility guru Matt has often made the point that accessibility is not a "feature" that can be added on post hoc, but rather something that has to be baked in. Well, the same goes for localization.

It's a hard question because it really depends a lot on what you're doing. I mostly write dev tool back end systems -- compilers and code generators and whatnot. I leave the UI to other people. Since my code mostly turns one kind of string (source code) into another kind of string (machine code), I do not require much localization support. Some, yes. I make sure that all the error strings are in resource files and all the string manipulation plays well with Unicode, and I'm pretty much done. The people who write the tooltips and help system and all the other UI-heavy stuff have a lot more internationalization worries.

Do you hard code strings until the class unit tests OK, then go back and add them to a resource file?

I wouldn't. Sounds like more work than doing it right in the first place.

Something we did when we started our current project -- I mean, like, day one of coding -- was wrote up a dead simple class that was just a "string server". We give it a magic constant, it gives us back a string. That meant that we were then free to figure out later how the strings would actually be stored. They started off as hard-coded in the string server class for the first couple days, and then we figured out how to get it all working in resource files. Make it flexible enough and you'll be able to change the underlying storage without disturbing all the string consumers.

Do you always/sometimes/never calculate UI layout fields using MFC's GetTextExtent() or similar?

I haven't written an MFC app for a long, long time. But how else would you do it? What, just guess at how big it's going to be, and hope that you never change the text, font, size, layout, etc? It seems fundamentally brittle, and hence more work, to make assumptions. (Raymond talked about a similar issue with determining rectangle extents a while back.)

Do you think about right-to-left reading languages up front?

Oh yeah -- any time there is the potential for bidirectional text, it pays to think about it early. Something we did in the script engine syntax colouring code for instance was add a bit that basically meant "this chunk of text is probably a human-readable string, and therefore the dev environment needs to figure out whether it is an RTL or LTR string." (I just got a bug on that code a couple weeks ago, actually, which is why it immediately comes to mind.)

Is the UI abstracted to a resource DLL along with the string table?

We did in WSH. I'm not sure that I could really speak to the pros and cons. Like I said, user interfaces are not my strong suit.

Does the average programmer at Microsoft just do their thing and pass the code down to an internationalization expert who then adapts the code?

No, all the devs are responsible for writing the localization code. The actual translation of the resources into foreign languages is done by experts of course. Most teams have at least one "loc PM" and "loc tester" who are a good people to know when you have technical problems, need to track down bugs that only repro on the Korean build, etc.

We often do what we call "pseudolocalization" builds as easy sanity checks. That is, we run the resources and whatnot through a pseudolocalizer, which replaces all the English text with stuff that is still readable, but is not normal English. For instance, it might replace an instance of u0041 (LATIN CAPITAL LETTER A) with u24B6 (CIRCLED LATIN CAPITAL LETTER A). It replaces every letter with a similar-looking letter in some random Unicode range, makes strings longer (to see if things fall off the ends of dialog boxes) by padding stuff out, bumps up font sizes in dialogs, etc.

Then we do a test run and see what breaks, what looks godawful, etc. But since it is only pseudo-localized, we can still read the dialog boxes and error messages and whatnot without running down the hall to find a colleague who speaks Bulgarian. (Not that you'd have to go far; my team just hired our third Bulgarian speaker last week.) Using pseudolocalization is way, way faster and easier than actually sending the bits to Ireland and Japan for localization and then testing the real-localized bits.

And something you didn't mention, but I'll call out right now: it is much more expensive to localize bitmaps than text, and very hard to make them accessible. If you care about localization, don't go putting words onto bitmaps. For that matter, don't go putting any picture on there that only makes sense to North Americans (like, say, most traffic signs.)

This is a topic that no green programmer is aware of (that I ever found), and many experienced developers don't even consider.

One of the reasons that Microsoft has been successful is very straightforward: we look for things that make people NOT use our products, and try to eliminate them. As I said in an earlier blog entry, we care about legally blind Catalan-speaking customers. If we didn't, they wouldn't be customers.

You are correct, and I would add security and accessibility to the list of things that some developers never think about, which is too bad. None of those things are easy to add post hoc, and all of them are barriers to entry. We're trying to get security, accessibility and localizability baked into the framework itself -- nothing will make these things easy, but we can at least make it a little less mind-bogglingly difficult.

But, like I said, I am far, far from an expert on localizability. If you have questions for a real expert, go ask Doctor International, or read the good doctor's book.