I18N Package: Improve documentation / deprecate tools

[swissspidy]

The i18n package's readme currently says:

Note that you will not need to specify domain for the strings.

This might be true if you do the string extraction yourself, but it sets false expectations for developers trying to use the package.

I suggest replacing this paragraph with an information that the text domain should match the plugin slug.

I've written a lengthy blog post about the importance of the text domain in WordPress internationalization here: https://pascalbirchler.com/text-domain-wordpress-internationalization/

Also, there's this part:

This is useful to trick WordPress.org translation strings discovery since at the moment, WordPress.org is not capable of parsing strings directly from JavaScript files.

Which is totally out of date now. See https://make.wordpress.org/core/2018/11/09/new-javascript-i18n-support-in-wordpress/

[swissspidy]

Another important thing:

The WordPress i18n Babel plugin can be used to generate a .pot file containing all your localized strings.

The only legit use case for this is when you aren't developing a WordPress plugin/theme, but something entirely out of WordPress.

If you're developing a WordPress plugin hosted on WordPress.org, there's no need for either the Babel plugin or pot-to-php. This is all done automatically by the WordPress.org infrastructure. See https://make.wordpress.org/core/2018/11/09/new-javascript-i18n-support-in-wordpress/

If you're developing a private WordPress plugin, you'll want to extract all strings of your project — PHP and JavaScript.

For this, the Babel plugin and pot-to-php are less than ideal because it basically duplicates your work:

1. You generate a POT file using Babel
2. You generate a PHP file with these strings using pot-to-php
3. You generate a new POT file from your PHP strings using wp i18n make-pot.

Not only does it duplicate your work, it also is pretty pointless because the WP-CLI command scans JavaScript files just fine.

If you use pot-to-php, however, you will loose important context. Your POT file from step 3 will add references to the generated PHP file instead of the actual JavaScript files. This is bad for translators.

My suggestion:

1. Remove pot-to-php and don't advertise it anywhere anymore.
2. Explain differences between non-WordPress projects, WordPress.org-hosted plugins/themes and private plugins/themes
3. Encourage people to use WP-CLI for creating POT and JSON translation files

[simison]

Note that you will not need to specify domain for the strings

Also brought up in #13132

[bobbingwide]

During WordCamp London contributor day I was looking at the process to internationalize my own plugin and @swissspidy said the docs were out of date. Rather than use po2json developers should use wp i18n make-json. No time to work on it today as I have to fill goody bags for tomorrow.

[youknowriad]

This seems fixed.