Reorganization of translation keys

Franz Any negative performance impact of the referencing mechanism can be compensated for by simply compiling all locales into one PHP file (with references already resolved) whenever an extension is added / updated.

Ooh, nice!

It occurred to me that we'd need to put some sort of check on referencing within the same file, so that when Key A takes it to Key B and it finds another reference there, it throws an error. Otherwise a careless translator could easily send it into a loop. But we might want to make it possible for a key in an extension to reference a key in the core, and then take one further hop from there.

Okay, since it seems we all agree, I'll get underway on the assumption we'll be doing it this way.

Toby I don't think core should make accommodations for any extensions, even if they're bundled – so no, if there's no reason for a string to be a global in core, then it shouldn't be made a global.

Yes, that makes sense. Noted.

Toby Can we quickly discuss the format that references should take? Possibilities:

I agree that a plain foo.bar is probably best avoided. Any of your "Other ideas" seem good, though there's a small outside chance that someone might want to begin a string with an "@". The syntax proposed by @DSitC would probably be safe, and it might be worth memorializing the fact that he suggested it.

So unless @Franz has any objections, I'm happy to go with that.

My next question is: How soon would it be possible to put the referencing mechanism/compiler in place?

There's no hurry on this, as it'll take me a while to get the final key name taxonomy figured out. But if it seems like taking a while, I'd want to plan for it. I could do the following as I adjust the key names in the YML and code:

1. Add the reference lines to the YML file, but comment them out.
2. Add alternative lines with the unique key names in the code, and comment those out too.

Then when the compiler is ready, it would be a simple matter of uncommenting those things, and removing the old lines with the non-unique key names from the code.

Like I say, it'll be a while before I'm ready to start on the actual editing, so there's no need to set a schedule right now. I just thought it would be a good idea to bring it up here so we can coordinate our efforts.

EDIT: I suppose an alternative would be to do it as two branches, one with the non-unique keys and another with the unique ones. But since I'm new to Git, it's probably safest to do it as described above. Unless it's not necessary, of course.

Toby Will do!

Another quick question: we agreed earlier that globals should be given no prefixes, but as we've since decided to organize everything by location, I think it might be good to give the globals a standardized prefix as well. Doing so would allow us to:

• Keep them together in a clump when extracting data for one purpose or another.
• Add general comments about globals (e.g. instructions on how to reference) should we desire.

I was thinking of using a simple "x" as the prefix, to indicate that the keys could be used in various locations. But on second thought, it might be better to do something like "aaa" or "zzz" to put them together at the top or bottom of the file when we alphabetize.

... Though come to think of it, it's not very likely that we'll have many locations beginning with x, y, or z.

Do you think such a prefix would be a good idea? Any preference as to which prefix we should use?

Another oddity I noticed is that things like dialog titles will also have to be prefix-less.

Otherwise it would end up looking like: change_email_change_email_title.

@Toby and @Franz ... just a couple quick updates to keep you apprised of my progress.

I've gone through about one-fifth of the strings, devising unique key names for each and making note of global references where needed. My thinking about key names has been evolving a bit during this process, so I thought you'd want to know how things are shaping up.

Regarding globals:

As I suspected, the global strings will all use their existing key names. Not only are they all short and descriptive enough, they will also be cross-referenced back to the unique keys that reference them, so there's no need to make them any more complicated.

Regarding prefixes:

For the most part, I'm trying to stick with prefixes that are similar to the JS filenames, which tend to describe the location where strings are used well enough. But there are some cases where a bit of rearranging seems in order. For example, there are four JS files related to the composer:

• Composer
• DiscussionComposer
• EditPostComposer
• ReplyComposer

It might be useful to translators to group these together, so I'm using a general-to-specific scheme for prefixes:

• composer_
• composer_discussion_
• composer_edit_
• composer_reply_

I was afraid this might become too cumbersome, but so far it seems to be working out well enough.

Regarding suffixes:

Since we're going with unique key names, it occurred to me that the suffixes could be a bit more detailed (and therefore descriptive). For example, you had suggested "_action" as a suffix for things like buttons, links, etc. That was fine when a single key had to cover multiple uses of the same string. But unique keys give allow us to give translators more intuitive descriptions of how a string is used. If it's a button, we can call it a button.

This means the list of suffixes will get a bit longer, but I don't think it will be any less consistent. And ultimately developers may find it easier to use suffixes that are less abstract and closer to natural language.

Quick question about:

• core.controls in js/lib/components/Dropdown.js
• core.notifications in js/forum/src/components/NotificationsDropdown.js
• core.post_number in js/forum/src/components/PostMeta.js

Under what conditions would a user (or translator) be able to see these strings?

Thanks, that'll allow me to wrap up my first draft.

In a bit I should have a list of terms I'm using for suffixes; there are a couple I'd like to get your opinion on.

Toby core.controls: On the right side of a user profile page

(Facepalm) Of course. I couldn't find it because I was looking at my own profile page.

So this seems to be the only moderator-specific key in the YML file so far. Interesting! I think I'll leave it out of the reorganization for the time being, and come back to it when we're adding in some other moderator functions like Suspend and so on. (Unless it also has a non-moderator use?)

Toby core.notifications: Next to the notifications icon on mobile

... Now now that you mention it, I haven't even been thinking about mobile while coming up with key names. I hope it won't be a problem if key names are based mainly on how strings are used in the desktop layout. (I don't suppose too many translators will be using the mobile UI for localization work.)

Fortunately, this seems to be the only key I've found that doesn't seem to be used in the desktop layout. And hey, that reminds me: I've been thinking it would be good to have tooltips for the bell and flag. Would it be possible to use core.notifications for such a tooltip? Then I could call it core.notifications_tooltip or something.

On a slightly related note...

I just thought I'd mention this wee inconsistency in labeling that I noticed while working on the keys.

The Settings page refers to notifications delivered via the bell dropdown as "alerts". But everything in the bell dropdown refers only to "Notifications". Should the word "Alert" be in there somewhere?

• One possibility would be to change the string for core.notifications in NotificationDropdown.js to something like "Alerts" or "Alert Center". That string could be used as a tooltip for the desktop layout too, as I said above.

• Another way would be to change the "Alert" on the Settings page to "Header" and leave the dropdown as it is. Notifications delivered via the header, also sort of makes sense.

• Or ... you could just say that "a foolish consistency is the hobgoblin of little minds" and leave everything as it is. Also a very reasonable choice, and gives bonus points for quoting Emerson.

Please let me know which of these three options you like; it will decide how I prefix the keys for the dropdown.

Next step: Here's all the suffixes I've got. I'm trying to find names that translators will recognize easily, but they have to be easy for developers to remember and use as well. Let me know if you think any of them should be changed.

User actions

• _button

• _command -- displayed as a dropdown menu item

  • Would a suffix such as _dropdown be more appropriate?

• _confirmation -- displayed in a confirmation dialog handled by the browser

• _help -- displayed prior to a user action (e.g. click button to receive an email, etc.)

• _link

• _message -- displayed after a user action (e.g. confirmation mail has been sent, etc.)

• _prompt -- combines text prompting a user action with a link

Structural

• _column -- displayed as the heading above settings or information arranged in a column

• _dialog -- displayed as the title of a modal

  • I think this will be more recognizable for translators than _modal would be.

• _field -- displayed as a label above or next to a data entry field

• _heading -- displayed as the heading above information presented as a list

• _placeholder -- displayed as the default content of an empty data entry field

• _row -- displayed as the heading next to settings or information arranged in a row

• _section -- displayed as the label for a group of settings (e.g. "Account" on the settings page)

  • Perhaps _area would be a better name?

• _tooltip

• _title -- displayed in the window title (e.g. for the Settings page)

  • This is the reason I'm not using _title for modal titles...

Information

• _notification -- displayed as notification content (e.g. when a discussion was renamed, etc.)

• _text -- any informative string that doesn't fit any of the above categories

That's what I've got now. I've come up with a few more than I was expecting, but not nearly as many as I had feared. If you can suggest a better name for any of the above, or any ideas for better ways of organizing strings according to how they're used, I'm all ears!

PS: We'll probably have to add a few (such as _page maybe) when we get to the ACP. Hopefully not too many.

Thanks for the reply!

Toby Previously it was used as the default label for a dropdown button (if not overridden), but on second thoughts I think that's a bad idea, so I've made it specific to to the user profile dropdown.

All right ... location-wise it fits there anyway. But I'm still wondering about the naming. Unless there's a chance that you'll eventually add some commands that non-mods can use to that dropdown, it might be a good idea to add something to the prefix to tell translators that that they won't be able to view this string without mod permissions.

So I'll lump this one with the user profile stuff for now, and make a note to review it later.

Regarding the tooltips for the bell and flag:

Toby Sounds good!

Do you want me to file an issue for this?

Toby Let's change the "Alert" on the Settings page to "Web".

I like that. I'll make a note in my matrix and handle it as part of the reorganization, if you wish.

Toby I think we should combine button and command, because these elements can actually end up being the same thing.

Yes, that's why I brought up the fact that translators will probably be working mainly with the desktop view.

The main reason I decided to separate these two is that buttons are easy to find, whereas translators sometimes have to hunt for commands. I thought a clue there would help save them some time. Is deciding which of the two suffixes fits better very likely to be confusing for developers?

(I can easily add a note to the docs saying that keys should be named based on the desktop view.)

Toby I prefer section over area.

Me too!

Toby Everything else looks good, though could I please ask to see some examples of how each of the "structural" suffixes are used?

That's the next step. Instead of extracting and explaining prefixes as I've done for suffixes, I'll just show you the whole matrix in its near-finished form. You can get a better idea of the suffixes then too.