Best practices: Always clarify ambiguous translatable string

[afercia]

Opening a discussion because this is a problem that spans through the editor codebase and it's not related to some specific component. I'm not sure creating an issue would be appropriate, not even sure what labels to use. Suggestions welcome. Anyways, I feel this is important enough to be brought to all contributors attention.

Traditionally, WordPress core always tried to make its best to provide context for ambiguous translatable strings. English, by its own nature, is a contextual language. Many terms have different meaning depending on the context or the object they refer to. There are a few ways to provide translators with more context, for example:

• translators comments
• the translation function with context e.g. _x( 'string to translate', 'context info' )

I'm not sure these best practices are well known to all the editor contributors, as I'm seeing many cases where translatable strings would need more love.

A simple example: the string __( 'Outline' )

In English, it can be a verb or a noun. As a noun, it has a few different meanings e.g.:

• border, contour
• short for 'document outline'

Turns out some of the translations of 'Outline' in the List View component are wrong. I'm not sure we can blame translators for the wrong translations. This string doesn't provide any contextual information.

I checked the UI in a few different languages and it turns out this string is often translated as 'border / contour' while it actually refers to the Document outline. Very confusing for users.

Screenshot:

Note: this screenshot was taken a while ago. Some translations may have been updated i the meantime.

In Spanish, French, Italian, Russian, Japanese, Portuguese, Dutch, Polish, it is translated as 'border':

• Contorno
• Contour
• Bordo in evidenza
• Контур
• アウトライン
• Contorno
• Omtrek
• Kontur

These languages represent a good percentage of the overall WordPress users. I'm not sure we're providing these users with the best experience. As said earlier, I'm not sure the root problem is up to translators. As developers we should make sure to provide translators with the most appropriate information to correctly translate.

I think there;s some good room for improvements in the editor codebase and I'd appreciate any feedback, ideas, actions, to make sure all contributors are aware of the best practices they should use. ❤️

[t-hamano]

I have had this problem several times before. These are examples of adding context because a literal translation in Japanese would not convey the correct meaning depending on where the text is used.

• i18n: Add context to labels related to CSS position properties #49135
• Group block: Add context to the word "Row" #42255

These problems are often received from the local community after WordPress major release. The number of people involved in translation in the local community varies from language to language. And there might be cases where people feel uncomfortable but leave it as is, or are not familiar with the WordPress or Gutenberg codebase even if they want to report it.

Another problem is that when you try to translate the text on GlotPress, it only knows what line the text is on in the source code. Also, if the translated text is in a JavaScript file, it will point to a built/compressed file, making it more difficult to imagine which text is being referred to on the actual screen.

I don't know much about it, but if Translation Playground could be made compatible with WordPress core and Gutenberg's React, it could be part of the solution 🤔

[afercia]

I'd think one small thing that could improve awareness and knowledge amongst contributors is starting to group all the issues related to localization and translations best practices under a new GitHub label: l10n. So I just created it.