Make hook_locale()'s documentation make any sort of sense

If this isn't fixed while I sleep, I'll do this tomorrow. Till then, it's open for anyone to grab.

This is in the wrong issue queue. And it should be fixed in Drupal 7 first, then the patch backported to Drupal 6.

So...

I took a look at the proposed documentation.

Aside from grammar/style questions, I am not sure about the documentation. I cannot find anywhere that hook_locale() is being invoked or implemented, either in Drupal core or in the Internationalization project (at least in HEAD for both), where anything but $op = 'groups' is being used.

Can anyone shed light on this?

It looks like hook_locale() is only ever called from functions in locale.admin.inc, in order to give translators a hint as to where the string originated. The greatest irony is that the example calls t() on its return value. :-)

Also, the only module I could find on my hard drive that supports this hook is Locale. Maybe better documentation will lead to more support. Which leads me to the question: Why would the group not correspond to the module name?

OK... this might be better but...
- Why is there a link to http://drupal.org/node/324602 ? That is a generic Working with Languages page. It doesn't seem directly relevant to this hook. We should instead find the section in the module dev guide that talks about internationalizing text stored in the database and link to that (http://drupal.org/node/304002).
- I don't see how t(), st(), or get_t() are really relevant links either -- how exactly are they related to hook_locale()?
- http://drupal.org/node/304002 seems to imply that hook_locale() is only used in the D6 translation system. Is that correct? Maybe hook_locale() should not exist any more?
- Where exactly did you find hook_locale() being called in locale.admin.inc? Maybe a link to those functions would be helpful?

1) I'm up for better linkage, but that's the one suggested in the OP. Perhaps http://drupal.org/node/324602 needs an update, too.

2) t() and it's friends call locale(). Locale() uses the translations. Translations are defined by Locale module. Locale module uses hook_locale() to help translators. I admit it's a stretch.

3) If hook_locale() shouldn't be in D7 then why's it there? :-) Locale module does, in fact, use it, but just for that one purpose. It looks like D6 uses it for more than just 'groups.'

4) To find where a hook is called, you'd search for module_invoke_all() with the hook name, like module_invoke_all('locale' . If everyone followed the coding standards, that should give you some results. (You can find the various *_alter hooks by searching for drupal_alter() in a similar way). It turns out Google does a better job than I did: Here. locale.inc calls it, too, but only ever in support of locale.admin.inc, in order to allow translators to search for existing translations.

A little bit of trimming, and let's try again...

1) Actually, the OOP suggested linking to 304002, which i agree with. I don't agree with 324602.
2) Yes, but translations of *user-created* content should **not** use t() and friends. We don't want to promote that idea, IMO.
3) Hook docs are only maintained by the doc team, so if someone removed the usage of hook_locale() from core and/or i18n, they probably just forgot to remove the hook doc.
4) Yes, I know how to find where a hook is invoked. I was just hoping you already knew. From the Google search you pointed to, please add an @see to locale_translate_overview_screen() and anywhere else in core you have found that invokes the hook, until we get api.drupal.org to automatically make these types of links (there's an issue).