Reorganization of translation keys

Dominion

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.

Toby

Dominion 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?)

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.

Dominion I hope it won't be a problem if key names are based mainly on how strings are used in the desktop layout.

That's fine. We've tried to keep the mobile layout as semantically similar to the desktop layout as possible, so I don't think there will be any issues here.

Dominion 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.

Sounds good!

Dominion 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?

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

Thoughts on the Suffixes

I think we should combine _button and _command, because these elements can actually end up being the same thing. For example, take a look at the "Reply" button and the commands in the adjacent dropdown on the right... Now take a look on mobile by tapping the three dots in the header... The "Reply" button shows up as a command! Same code/element, just different appearance.

In terms of picking one, I think I prefer _command.
I prefer _section over _area.
Everything else looks good, though could I please ask to see some examples of how each of the "structural" suffixes are used?

Dominion

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.

Toby

Dominion Unless there's a chance that you'll eventually add some commands that non-mods can use to that dropdown

There is definitely a chance that extensions will add non-mod commands (e.g. start a private discussion, follow a user).

Dominion Do you want me to file an issue for this?
Dominion I like that. I'll make a note in my matrix and handle it as part of the reorganization, if you wish.

Yes please!

Dominion Is deciding which of the two suffixes fits better very likely to be confusing for developers?

I'm not worried so much about confusingness, but more the fact that it's impossible to use two different suffixes in the instance of the Reply button/command because they're the same thing. Can we not give a clue to a string's location in its comment? e.g.

# This command appears in the controls dropdown menu of a post
delete_command: Delete

# This command appears as a button in the footer of a post
like_command: Like

# This command appears as a button on desktop, and in a dropdown menu on mobile
reply_command: Reply

Franz

Dominion I'll make a note in my matrix

Dominion, the guy who edits the matrix.

Dominion

Toby Yes please!

Done and done!

Toby I'm not worried so much about confusingness, but more the fact that it's impossible to use two different suffixes in the instance of the Reply button/command because they're the same thing.

True, but if we think about what the key names need to accomplish:

Designers need to be able to choose key names without too much fuss.
Translators need to use those key names to find the string in the interface.

Separating them gives translators more of the descriptiveness they need. And by limiting the frame of reference to the desktop view, we can provide developers with the consistency they need. I think as long as both these needs are fulfilled, it doesn't really matter that the key name can't describe how the string is used under every circumstance.

(That information is already in the code, where it's really needed.)

The core.notifications_tooltip string mentioned above is a perfect case in point. We can add a tooltip by reusing the string that was added for the mobile view, but that means it will be a tooltip in one view and more properly described as a label in the other. So the problem wouldn't end with just buttons and commands.

I can merge them if you feel it's important, but my choice would be to give the translator more information. If we do go that way, I'd probably argue for the _button suffix because commands are revealed by clicking buttons. 😉

Toby Can we not give a clue to a string's location in its comment? e.g.

That strikes me as a lot of unnecessary comments to convey information that could be in the suffix. 🙂

Toby

OK, fair enough, let's keep them split 🙂

Dominion

Gotcha ... I wasn't dead opposed to the idea, I just wanted to be sure we're doing it for good reasons.

I'll get right to work on polishing up my matrix and show it to you later today.

Dominion

Okay, the first draft of new key names is more or less ready for inspection. A few notes:

I've tried to stay close to the JS filenames where possible, but in some cases I've opted to go with something that would make more sense to a translator, who shouldn't really be concerned what JS files are called.

I've broken some locations up into smaller chunks in some cases; in others, I've used prefixes to gather related chunks together, so that translators will have an easier time navigating the YML file. In many such cases there's a judgment call to be made, and I've got with what strikes me as convenient.

There's still room for discussion on a lot of the names, especially in regards to the granularity of the chunks.

As mentioned earlier, a couple of links (one log_in and one sign_up) need to be merged with the text strings that precede them to create prompts. I'll have a look at the code as I get started on editing, and I can't manage the changes, I'll call for help.

All in all, I think this is turning out pretty well...

Dominion

Yes ... but I am not the Architect, merely the Keymaker! 😉

... Although I do tend to run on like that Architect guy at times ...

Dominion

@Toby , regarding this:

Dominion Is it possible to combine strings?

I think I may have been a bit too optimistic about a couple of reuse instances. Cases in point:

The "Log In" link at the bottom of the signup modal

The "Sign Up" link at the bottom of the login modal

At first glance, these two links look like the other "Log In" and "Sign Up" links/buttons. But they're different in that they come with context, i.e. the core.before_log_in_link and core.before_sign_up_link strings, respectively. Some translators may need the freedom to embed the link in the context sentence, like so:

If you already have an account, please log in instead.

Even if there is no need for non-link text after the link, the hardcoded space separating the link from the context is bound to cause trouble for some translators. So each of these string pairs should be handled as one.

After staring at this for a while, I've concluded that most translators will probably be able to make do with the two existing strings, so there's no need to preemptively merge them with the "before" strings. Let's leave them as they are (with the "before" strings appropriately renamed) until someone really needs this.

However, the hardcoded space between the "before" string and the link could be a problem, so it would be best to move it inside the "before" string. I think I can manage that small a change to the JS on my own, but wanted to check on how it's handled in the YML. Am I correct in assuming that all I'd have to do is enclose the string in quotes, like so:

"Already have an account? "

... with an extra space after the question mark? Or is it going to be more complicated than that?

Toby

Dominion Nope, that's all there is to it 🙂

Dominion

Great! Then that's one less thing to worry about before the big reorganization.

Dominion

@Toby and @Franz :

Okay, I think I'm finally set to get down to actual editing. But first, a quick note on the composer_ chunks:

I think there's more to be gained from grouping them together than from separating them. Putting them right next to each other will enable translators to easily compare the three composer variations and decide how they want to handle the differences. (In many cases they may want to reuse strings, making the variations more similar.)

Compared to that extra convenience, making the prefixes feel more like natural language is really an aesthetic issue; it won't necessarily make them easier to find. (And remember, every chunk will be accompanied by a comment with a natural language description. 😉 )

Here's how I plan to proceed:

Crunch the matrix down into YML file format.
Add comments, and eyeball the entire thing for errors.
Show you the completed YML file for a final check.
Create a new branch and edit in all the new keys.
PR that, and get working on documentation as follows:
- Create a i18n specification for developers, explaining how to name keys.
- Update the l10n specs, to explain string referencing and reuse to translators.
- Create a migration guide to help translators migrate any existing work.
When the docs are ready, get cracking on extension keys.

I figure that if I edit and PR before I start on the docs, it will give you time to devise and test the compiler (and make sure my changes actually work). But if you'd rather see the documentation before I start editing (say, to get a better overview of how it all hangs together) then I can do that too. Just let me know.

Toby

Dominion All sounds good 😃

« Previous Page