Meta: improve add-on messages in regards to grammar, possible spelling, shortening messages

[josephsl]

Hi,

Stemming from #73 discussion on messages:

There has been requests by translators to make the add-on messages easier to understand and translate. Part of the reason for translation difficulties is grammar and message verbosity.

This issue is aimed to serve as a meta discussion issue for messages that will need to be improved, could see some improvements, or shortened. For example, when one tries to edit Braille Extender profiles, the message shown is:

You must have a braille display to editing a profile

It should say:

You must have a braille display connected to edit a profile

Or better yet, a more precise message might be:

A braille display must be in use to view and edit profiles.

Currently the following issues with messages are seen:

• Use of "a" versus "an" for vowels
• Grammar issues
• Verbose messages for settings
• No translator comments (see Add-on messages: add translator comments #74)

Please comment if you know (or think) there are messages in this add-on that can see an improvement.

Thanks.

[AAClause]

Totally open to receive this kind of fix. Indeed, my English is not good and I'm aware that it's a problem for translators. If some strings are completely incomprehensible, please also report it to me. I'll reformulate them.
By the way, I'd like to release a (major) stable version with PRs #56 and #64 for August. So if we can fix some grammatical and spelling errors for this deadline, it'll be awesome! :)
Regarding the Profile Editor, this feature is not finished and is paused since awhile. Please note that I'll remove this feature from the stable version soon.

[josephsl]

Hi,

I'll take care of minor grammar issues ("a" versus "an", for instance).

Thanks.

[josephsl]

Hi,

By the way, while we are at it, can we go through add-on GUI messages (such as add-on settings) so they can be more concise and straight to the point? Examples include:

Add-on settings/general:

• Check for updates automatically -> Automatically check for Braille Extender updates
• Add-on update channel -> add a colon
• Say current line while scrolling in -> Say current line while scrolling (and add a colon)
• Feedback for volume change in -> let's make it more concise
• First braille display preferred/Second braille display preferred -> I think it would be best to call them "primary" and "secondary" braille displays

Settings/document formatting (development):

• Representation of attributes -> it can be made less verbose (say, "Attributes...")

Braille tables:

• Groups of tables -> Table groups

Others:

• Representation of undefined characters -> quite verbose, actually. Let's shorten it a lot.

ONe-hand mode:

• Enable this feature -> what are you talking about? What feature are you enabling?

Also, I suggest calling this "one-handed mode".

Role labels:

• Enable this feature -> again, what are you talking about? What is "this" feature?

advanced:

• Try to avoid cursor positions issues with some characters such as variation selectors -> What is this? Is there a less verbose (and short) way of describing what it does?

Others:

• Overview of the current input braille table -> I think this is way verbose.
• Settings toggles (Dots 7 and 8, for example) -> remove colon to align with how NVDA Core actually announces toggled values.

Now would you like me to make these changes or are you comfortable with thinking about the above suggestions?

Thanks.

[AAClause]

Thanks! I'd prefer that you make a pull request for these changes. Please update the master branch only.
Regarding strings present in the development version, I'll fix them soon. However I'd prefer that you report the errors in the concerned pull requests, if this doesn't bothers you!

[josephsl]

Hi, I would rather wait for development features to be integrated before making changes to these, as these things are still under development. Note that as part of this work, I’ll start adding source code comments to make our lives (and lives of future maintainers) easier. Thanks. From: André-Abush Clause <[email protected]> Sent: Thursday, July 16, 2020 4:43 PM To: Andre9642/BrailleExtender <[email protected]> Cc: Joseph Lee <[email protected]>; Author <[email protected]> Subject: Re: [Andre9642/BrailleExtender] Meta: improve add-on messages in regards to grammar, possible spelling, shortening messages (#75) Thanks! I'd prefer that you make a pull request for these changes. Please update the master branch only. Regarding strings present in the development version, I'll fix them soon. However I'd prefer that you report the errors in the concerned pull requests, if this doesn't bothers you! — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#75 (comment)> , or unsubscribe <https://github.com/notifications/unsubscribe-auth/AB4AXECLDQN7QDTOY6SYUP3R36F6NANCNFSM4O4V563Q> .

[josephsl]

Hi,

An important note for others: there are instances where we see "%s..." when initializing Braille Extender submenu. These indirece interpolation will be removed as part of this work. Another common theme we see is that the add-on name is indirectly referenced. That too will be changed to reference the add-on name directly in order to make the messages more contextual, easy to translate, and reduce headaches for linters.

Thanks.

[josephsl]

Hi,

I know I'm posting a lot of messages:

Although use of %s is fine, as part of this work, translatable strings will be given more descriptive names, or in some cases, index-based interpolation syntax will be employed designed to make the code more readable and to reduce confusion (and some cases, lower potential security problems).

Thanks.