Create a localization rule to highlight common errors that cause trouble for translators

[aireilly]

Vale can help us produce content that makes localization easier. There are many English language usages that can cause problems for localization. For example, in the ISG, "should" is a use with caution word. "Should" can have multiple meanings depending on the context. This makes extra work for translators.

ISG:

Use with caution should verb
Whenever possible, rewrite in a more direct way. 
Do not use should to refer to an action that must be performed.
For example, when parameters must be reset, write “Reset the parameters” and not “You should reset the parameters”.

We do catch "should" as a suggestion term, but it would be good to review existing rules, and pull current errors that affect localization into a single rule if possible, or a group of localization rules if not.

"Should" usage being just an example of the kind of errors we should investigate.

Additional context:

• Localization Newsletter Issue 8, April 2020 (internal Red Hat email)
• Translation project started
• VRH Slack conversation

[dfitzmau]

LGTM. Localization issues defo deserve a place in the word-usage spotlight.

[rolfedh]

Excerpt from Localization Newsletter Issue 8, April 2020 (internal Red Hat email)

Localization-friendly Technical Writing Tips by Junkito

Should or Should Not Use "Should"

The word "should" is a modal auxiliary verb that is commonly used in our documentation to express obligation/correctness or expectation/probability.

Clear-cut Use Cases for "Should"

I often see the word "should" in sentences like the following:

Expressing expectation/probability

• After entering the command, you should see the following output.
• 12 GB of RAM should be sufficient for this use case.

Expressing obligation/correctness

• You should perform this procedure only when you have the issue.
• The values you specify should be A or B.

These are the clear-cut sentences that I don't have to think twice about.

The Ambiguity of "Should"

However, because "should" has multiple meanings as described above, a sentence containing "should" might be interpreted in multiple ways. Take a look at the following example:

• The process is suspended during the operation. After the completion of the operation, the process should continue from where it was suspended.

For this example, I could not work out at first whether "the process is expected to continue" or "the process needs to continue." The former interpretation implies that the process itself will resume from where it stopped, whereas the latter interpretation implies that the process needs to resume from where it stopped, hinting that a form of intervention might be required to make this happen.

Localization-friendly Suggestions

After a brief investigation, I concluded that "should" in this case was used to express expectation/probability ("the process is expected to continue"). It was also the case that machine translation selected the other interpretation (obligation/correctness: "the process needs to continue").

My localization-friendly suggestion is to use "will" instead of "should" in this particular example. "Will" is a more definite word that confirms the occurrence of an event. If you want to emphasize the possibility rather than the confirmation of an event to occur, I suggest using "might" instead of "will."

[rolfedh]

@aireilly, would you add [email protected] as a repo member?

[aireilly]

@rolfedh done. Welcome @[email protected] :)

On a side note, would be good to review existing rule terms and see if it makes sense to pull out other localization terms under this new rule.

[rolfedh]

other localization terms under this new rule.

We're developing a set of guidelines and will bring others into the fold as the list grows.

[aireilly]

Excellent :)

[aireilly]

re: "should". IMO would be great to figure out where this is allowed and tune the rule to allow for correct usages.

[reachlekha]

@[email protected] had spoke about this during the Oct 26th 2023 CSS Best practices meeting. She promised to come up with a draft listing all the words that can be avoided to make translation easier.

Here's her presentation - https://docs.google.com/presentation/d/1_1UOqZlRHqwajCRzzEUXtS5mrJKaIlkAA5_OQHS1dRU/edit#slide=id.g213857fa2d1_0_68

[aireilly]

Considering the above, it might make sense to create a distinct and separate Red Hat Localization rule set. E.g.,

Styles/
    AsciiDoc/
    OpenShiftAsciiDoc/
    RedHat/
    Localization/

[rolfedh]

create a distinct and separate Red Hat Localization rule set.

On it. I've made a first pass at creating a Localization rule set #688. Anyone, please share your thoughts and suggestions.

[rolfedh]

Considering the above, it might make sense to create a distinct and separate Red Hat Localization rule set.

@aireilly Please have a look at https://github.com/redhat-documentation/vale-at-red-hat/pull/688 to see if I've set it up correctly as a first step.