Update Plugin Handbook with a reason why text-domains must be identical to the WordPress Org Repo Slug of the plugin

[smileBeda]

Issue Description

In WP there are 2 details about text domain that often get missed:

• Textdomain MUST NOT be defined as a $variable since it MUST be a string literal due to how gettext() works.
• Textdomain MUST be identical to the WordPress.org Slug, if this plugin is published on .org repo.

URL of the Page with the Issue

Some of it is talked about here but might profit from some add-on details

• clear warning to NOT use @var. But the "why" is missing. Perhaps too technical?: https://developer.wordpress.org/plugins/internationalization/how-to-internationalize-your-plugin/#basic-strings
• Seems a good "solution" to the problem with "cannot use a $var": It expedites changes... https://developer.wordpress.org/plugins/internationalization/how-to-internationalize-your-plugin/#add-text-domain-to-strings
• clearly stating the text domain MUST be equal to the slug of plugin, but could elaborate more on the why https://developer.wordpress.org/plugins/internationalization/how-to-internationalize-your-plugin/#text-domains

Why is this a problem?

Well, it just comes up very often that devs or users want to use $var (and then one needs to inefficiently google for the "reason why not"), and it is also not very prominently documented that the text-domain must match the WP Org Slug.... which is truly confusing and even I as a Plugin dev, discovered this only after the fact. It is confusing because in a WP Plugin there are several "slugs":

• the plugin main file
• the text domain
• the plugin folder name
• the plugin repo slug best is, all these just match.... but this is NOT required. Required is that the repo slug and the text-domain match and one can have custom repo urls, even if they usually get automatically generated based on... the main plugin file name? Duh, see, I forgot.

Suggested Fix

@theMikeD suggested he will look at some possible ways to add specifically the "why" to the doc.

[anandau]

Plugin developers must ensure that the text domain they are using in their plugin should be unique. But I think this is not the rule that the text domain "must" match the slug of the plugin.

Why do I think so? The plugin review team does not apply this rule while reviewing plugins. This is my experience so far with 10+ plugins. I don't think I can be lucky to bypass a rule so many times 😀

I think it will be best to get this rule verified by the plugin review team and then update the docs with the appropriate verbiage.

[github-actions[bot]]

Heads up @theMikeD - the "plugins" label was applied to this issue.