I18n: check use of consistent translator comment style

[jrfnl]

trafficstars

Is your feature request related to a problem?

Translator comments can be written using both single-line // .. or multi-line /* ... */ comment style.

The tooling used to generate a .pot file will often only take one type of comment into account for translators comments. If I remember correctly, this, most notably, applies to tooling using the xgettext command-line tool under the hood, though it should be verified if this is still the case in current versions of the various tools.

If this is still the case, it should be recommended that all translators comments within a project use the same style throughout the project, either // ... or /* ... */. Mixing the comment style for translators comments should be discouraged.

I would like to do some analysis on existing projects to back this up, but solely based on my experience, /* ... */-style comments are predominantly used for translators comments.

So, as an alternative, we could choose to recommend for translators comments to always be /* ... */-style and to discourage/warn against the use of // ...-style translators comments.

Opinions welcome, as well as any current information on relevant tooling which should be considered and how the tool deals with mixed comment styles.

Describe the solution you'd like

If a check for this should be added, it can go into the existing WP.I18n sniff.

The way I envision this, would be for the sniff to:

1. Record metrics on comment-style used for translators comments which could be used by developers to determine the predominant comment style for a project.
2. The first time the sniff encounters a translators comment, set a property to record which comment style to accept. For each subsequent translators comment encountered, verify that it uses the same style as the first translators comment encountered. Note: the first comment could be the exception instead of the "rule", which is why the addition of the metrics is important.

If the alternative implementation of always recommending /* ... */-style translators comments would be chosen, then the implementation can be simplified.

1. While metrics could still be considered a "nice to have", they would not be needed for determining the predominant style in a project.
2. Instead of checking against the comment style of the first translators comment encountered, the sniff could just check that translators comments are in /* ... */ format.

[dingo-d]

Will this be used on .php files only, or on .js files as well?

Because Gutenberg editor is using babel-plugin-makepot for translation generation in the .js files.

I'm not sure if this encompasses the scope of this issue, but thought it wouldn't hurt to ask 🙂 We could get somebody from the GB team to see how they handle translations.

[swissspidy]

@dingo-d Note that Gutenberg itself does not actually use @wordpress/babel-plugin-makepot. Like any other plugin, strings are extracted on WordPress.org using WP-CLI. But I don't see how that package is relevant here. If anything, @wordpress/eslint-plugin could have a similar rule.

[swissspidy]

Consistency for translator comments would be great!

I would like to do some analysis on existing projects to back this up, but solely based on my experience, /* ... */-style comments are predominantly used for translators comments.

Ditto.

We could choose to recommend for translators comments to always be /* ... */-style and to discourage/warn against the use of // ...-style translators comments.

+1 to this suggestion. In core we generally advocate for using that style. There are only few exceptions, as for some reason the new Site Health feature sometimes uses the // ... style 🤷‍♂

[GaryJones]

The plugin and theme handbooks have a couple of different instances, and they all use /*...*/.

It would seem odd to use a multi-line comment format for a single line comment though. Should that be a consideration? It's also longer to type – more characters at start and end of the line – and not what the keyboard shortcuts for IDEs tend to do.

If there's going to be an explicit entry in the handbook on the preferred format, we should aim to get it right, and not just go with whatever the current majority uses (spaces vs tabs, anyone?).

[marekdedic]

Coming from #1723:

I always took it that one of the points of WPCS is to enforce consistent code style throughout different WP codebases. If it indeed it so that a majority translators comments uses the block style, I would just enforce that. (Even though in my personal opinion, using the // ... style makes more sense for single-line comments)

Just my 2 cents...

[garretthyder]

Coming from core#47691

It was noted the translator comments should check the capitalization of the 'translators: ' prefix to ensure it's lowercase.

It would also be nice for the multi-line translator comments if they were consistent starting on the second line of the comment.