Add a Localization section to the guide

[rolfedh]

The localization team has specific recommendations to improve content for both non-English readers and Red Hat associates performing localization.

cc: @aireilly @rohennes [email protected]

Also see:

• Create a localization rule to highlight common errors that cause trouble for translators vale-at-red-hat#515

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

[bergerhoffer]

Outcome from the October SSG meeting: We are open to creating a localization section for the SSG (as long as it doesn't duplicate content/guidance from elsewhere in the SSG/ISG).

Rolfe will start working on this effort/a PR.

[Srivaralakshmi]

Thank you, @rolfedh for creating this PR about the localization section for the SSG.

[Srivaralakshmi]

Hi, @rolfedh any updates on this?

[reachlekha]

Here's the PR for new vale localization rule set - redhat-documentation/vale-at-red-hat#788.
Could you please help to add a separate section "Localization Guidelines" to our style guide?