I've finished my first pass at the translation keys, looking at cases where a string is being used in more than one place. There are 19 such cases, of which 13 will pose no problem (i.e., the string is used with the same sense everywhere).
The remaining six cases are described below. Please bear in mind that the goal at present isn't to decide what to do about key names in these cases, but to think about whether or not we should do something about splitting them, and what that decision will imply for translation key naming in general.
Button vs. Dialog Title
There are four cases where a string is used as both a button and the title of a dialog box:
- core.change_email: Change Email
- core.change_password: Change Password
- core.log_in: Log In
- core.sign_up: Sign Up
I think most translators will be able to handle all these without requesting separate strings, so there's probably no need for preemptive action. On the other hand, they are few enough and short enough that we could split them up now and not worry about the duplicate phrases being a burden on translators. I'll discuss this in more detail below.
Table Heading vs. Link
The string "Discussions" (core.discussions) is currently being used in two places:
- As a heading in the dropdown box listing the results of a search
- As a link on the user page (followed by a number indicating quantity)
The fact that it's a heading in one case and a link in the other doesn't make any difference to the meaning. But the fact that the latter is followed by a number (how many discussions the user has started) does add an additional sense to the latter. This may become a reason for handling it as a separate string.
For that matter, it may also be a good idea in the second case to include the number in the string. This is because some languages may need to do linguistic things to it. (For example, Japanese generally adds a character after any quantity to indicate the type of thing being counted.) Of course, this would make the second case a different string.
The same would be true of the "Posts" link (core.posts) that appears above the "Discussions" link on the user page.
Table Heading vs. Text Box Label
The string "Email" (core.email) is currently being used in four places:
- As a label or placeholder for a text entry box (three instances)
- As a header in the notification settings table (one instance)
This is a clear case of a word being used in two different senses. As a text box label, it's prompting the user to enter his or her email address. As a table header, it's talking about email as a notification method, and has nothing to do with the address. It's very likely that a translator will want to translate the word differently in each of these two contexts.
Moreover, there's a big difference between the two in the amount of space available to the translator. This is another factor that will determine how the phrase can/should be translated. So I think we may have ample reason to go ahead and separate the latter instance out as a separate string.
Discussion
With the above information in hand, we're now ready to take our first steps toward settling on a key naming scheme.
@Toby has said that key names should be descriptive and consistent. These are worthwhile goals, but there are times when it is hard to do both at once. The problematic cases of string reuse described above will help us see why. Let's begin by asking:
Are prefixes and suffixes really necessary?
After all, when we're talking about a one- or two-word string (which is what most of the reused strings are), there's really no better way to describe the string than to use the string itself as the string name! This is especially true when a string is used in several different places in the UI. In such cases, we can't add prefixes or suffixes to indicate where the string is used without creating a number of duplicate strings, which will increase the translator's workload.
Granted, it might be nice to add some information to help the translator figure out what sense a word is being used in, where it can be found in the UI, and so on. But that's only really necessary when the meaning of the string is inherently ambiguous, as I pointed out here. In most cases it's not all that hard for a translator to guess what, say, "Log In" means. (Especially if it's spelled correctly. I congratulate @Toby on being one of the virtuous few who get it right! π )
But let's say that, in order to remain consistent, we want to tag the string for every button name and dialog box title with a suffix that will let the translator know how the string is being used. That's reasonable, because it's also descriptive after another fashion. But in cases where strings are being reused, such as the four "Button vs. Dialog Title" cases described above, this will end up forcing our hand: we will have to split those four strings to accommodate the consistent naming. We will no longer be able to put that off until a translator requests a split.
That isn't a huge problem. After all, it's only four little strings. But as we add more strings, and take the extensions into account, the number of duplicate strings created for the sake of consistency will continue to grow. Eventually we could end up with a real Stumbling block 3 situation.
Key names should be descriptive and consistent, but there's a case to be made for efficiency too!
What happens when we decide to split a string?
Let's forget (temporarily) about the possibility of adding prefixes and suffixes to everything and talk about what happens when we decide to split a string. The "Button vs. Dialog Title" cases will come in handy for that, too.
Take, for example, the strings core.log_in and core.sign_up. Each is used in four places: three times as a button name and once as a dialog title. If we decide to split off the dialog titles as separate strings, using suffixes as described here to distinguish between them and the buttons, we can proceed in one of two ways:
- We can add a suffix to the title string only (core.log_in_title), leaving the button string as-is (core.log_in).
- We can add a suffix to both the title string (core.log_in_title) and the button string (core.log_in_action).
The former course would result in a pair of string names that are not consistent with each other. But at least one of the pair will remain consistent with any other dialog title or button strings that don't have suffixes yet. One benefit of this approach is that it is easy to implement, since you only have to change one string name, which is used in two places.
The latter course would result in a pair of string names that are consistent with each other, but inconsistent with any dialog title and button string names that don't have suffixes. (Of course we could fix that by going the "suffixes for all" route described above; but we're forgetting about that possibility now, remember?) The downside to this approach is that you end up having to make a lot more changes: two string names, used in a total six places.
It seems it might be good to think about efficiency not only in terms of key name length and quantity of duplicate keys, but also ease of implementation.
Two approaches to key naming
I think we can boil down all the above (Yes! At last, a TL/DR! π ) by saying that we can slant our key naming scheme in one of either two directions:
- Greater consistency, at the expense of efficiency
- Greater efficiency, at the expense of consistency
I should add that while I've been looking to cases of string reuse for clues, single-use strings won't remain unaffected.
Let's say we're using the word "Thingamajig" as a button name, and that button is the only place it appears it in the UI. Do we need to give it a suffix to indicate it's a button? The greater consistency approach would argue yes.
And let's not forget the possibility that we may eventually add a dialog box titled "Thingamajig". If we somehow arrive at a policy that requires suffixes on every string that's being used in more than one context, we'll not only have to add a new core.thingamajig_title string, we'll have to rename core.thingamajig to core.thingamajig_button at that point. Or something like that. I think.
My question for Toby (and anyone else who's interested)
Sorry for making you read all this stuff, but I wanted to get your informed opinion on how to go forward. Ultimately, it comes down to a rather simple choice: more consistency, or more efficiency?
I didn't want to make that decision by fiat ... in fact, the more I think about this stuff, the more I'm inclined to toss it all aside and go with the key names you've got. (By which I mean: limit myself to minor tweaks, slanted heavily in favor of efficiency.) I think there's a limit to what can be achieved using key names as the sole tool; which is why I think it might be a good idea to give some thought at this point to a translation UI capable of providing translators with more info about the strings than we can put into the key names.
I'm not saying we have to think about starting work on such a UI right away. But if we know we'll have one eventually, then for the time being we can settle for key names that are less than optimally descriptive and consistent.
Please let me know what you think!
PS: As for extensions, at this point I think we'll just have to pick a policy and hope it scales well. π
