Improve documentation of hook_translated_menu_link_alter()

The cause is that "translated" does mean the common meaning of "translation" or "localization". I guess this issue can be resolved by simply clarifying what "translated" means in the phpDoc first. The remaining, existing docs read fine for me.

so you want to do this sun?

Pretty much complete starting point. Happy to review further patches, but won't have time to work further on this patch.

A few things need fixing here -- I'll make a patch later today or tomorrow if someone else doesn't get to it first.

a) Typo: "property of the mnu link." (should be menu not mnu)

b) Looking at the code in http://api.drupal.org/api/function/_menu_link_translate/7, I think that we should add a line in the doc of hook_menu_link_translate_alter clarifying that it is only called if $item['options']['alter'] has been set. This is illustrated in the examples in hook_menu_link_alter, which is good, but it should be mentioned in this other hook too I think.

c) Looking at the code, I don't see where it declines to call this hook if the access flag is FALSE necessarily. So I don't think "after the user access to the link's target page has been checked and led to a positive result." is actually accurate? I see that it returns before the hook is invoked in some cases, but I don't see anything that returns after _menu_check_access($item, $map) if the access flag is false. Maybe that's a bug?

d) We should also clarify in the explanation of what "translated" means, that it also does localize the text (i.e. the normal meaning of the English word "translate").

I just realized that the bit about the alter flag was there, but I didn't notice it due to where it was in the doc, so I moved it up.

Here's a new patch, with the changes noted in comment #4.

Thanks!

Nice clean. Committed to CVS HEAD. Thanks.