Naming keys in resource files best practice

Question

Does anyone have any recommendations on naming keys in resource files? For instance, do you base the name of your key on the text that needs to be localized or on the control that uses the text?

Say you have an edit button in several screens (one to edit a user, one to edit a group). You could use the following keys:

• editUserButton.label=Edit User...
• editGroupButton.label=Edit Group...

or

• editUser=Edit User...
• editGroup=Edit Group...

or

• user.edit=Edit User...
• group.edit=Edit Group...

What scheme do you prefer and why?

Answer 1

I prefix my literals by usecase or action classname. eg:

PlaceOrder.invalidId=Invalid id for order {0}
PlaceOrder.success=Your order {0} was successful
PlaceOrder.fail.visa=Your visa was ...
PlaceOrder.fail.communications=We could not...
PlaceOrder.submit=Buy now

Login=Login
Login.fail=Your credentials did not...
Login.alread=You are already logged in

This way you avoid collisions:

EditStudent=Edit
EditClass=Edit
EditCourse=Edit Course

...and can also find what you need easier.

Another way I group is by entity:

Person.id=#
Person.name=First name
Person.surname=Surname

These can appear as headers on tables with the entities. It saves you in cases such as this:

Person.id=#
Class.id=#
Course.id=Course Id

Lastly by providing context in the property keys you can save yourself from false translations. For example I once had:

no=no

which was being used as an id (#) table header on the top left cell, but our french translator did this for French:

no=non

... he thought it was the word "no" (negative of yes). :)

Last (but not least) prefixing with classname will help you when you want to refactor/rename classes and quickly update these property keys without having to look at the templates.

Answer 2

We base it on the English version of the term. Ex:EditUser That was it is easily readable by our developers and can be reused in multiple locations that term is required throughout the app.

Answer 3

Base it on the English text, but prefix with the window/dialogue/what have you in which the word or phrase appears. At least when layout space is limited, you may want to avoid falling in the trap of having exactly the same string everywhere: this prevents you from abbreviating to get decent layouts, especially in polysyllabic languages like Finnish.

Of course, you should still strive to be consistent in naming stuff. Increasing the number of strings will also increase translation costs if you're doing this commercially.

And don't ignore the danger of homonyms. Providing context helps prevent that. Don't be afraid make the resource name longer than the actual English term, this can help translators substantially.

Answer 4

+1 for @cherouvim's answer, but it always comes down to documentation.

Document each value (using whatever comment mechanism is supported by the resource source file format), including the data type of each parameter if the string is formattable. For example, the VS editor for the .resx format exposes a comment field which makes it very easy.

So a message like:

Unable to schedule the {0} job before {1}.

would be documented as something like:

Logged error message, {0}: job name, {1} date/time in ISO 8601 format.

Answer 5

I think that in the first place you should use some kind of XML files to store that kind of data.

Something like :

<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
<xml>
    <button>
        <edit>
            <user>***Edit User*</user>
            <group>Edit group</group>
        </edit>
    </button>
</xml>**

And then use a "translate" Class to get (and set/save) the text.

Something like :

myTranslateClass.load( 'translate.xml' );
myTranslateClass.get( 'button' , 'edit' , 'user' );

That's a simple example.