Reorganization of translation keys

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

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

Franz

Dominion I'll make a note in my matrix

Dominion, the guy who edits the matrix.

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