The hook_help() API documentation page uses t() incorrectly.

Example:

Every web link, l(), or url() must be replaced with %something and put into the final t() call: $output .= 'A role defines a group of users that have certain privileges as defined in %permission.'; $output = t($output, array('%permission' => l(t('user permissions'), 'admin/user/permission')));

According to t()'s documentation, it should be used like this:


$output .= '<p>'. t('Go to the <a href="@contact-page">contact page</a>.', array('@contact-page' => url('contact'))) .'</p>';

Comments

betz’s picture

betz commented
Project: Documentation » Drupal core
Version: » 7.x-dev
Component: Documentation in CVS » documentation
todd nienkerk’s picture

todd nienkerk commented

To be more specific, the t() function shouldn't contain any HTML in its translatable string. The documentation for hook_help() displays <p> tags inside the strings for all versions (4.6, 4.7, 5.x, 6.x, 7.x).

todd nienkerk’s picture

todd nienkerk commented
Status: Closed (works as designed) » Active

Several misuses of t() appears in core itself. Check out help_help() in 6.x:

function help_help($section) {
  switch ($section) {
    case 'admin/help':
      $output = t('<p>This guide explains what the various modules in <a href="@Drupal">Drupal</a> do and how to configure them. Additionally, you will find a glossary of basic Drupal terminology to help get you started.</p>
<p>It is not a substitute for the <a href="@handbook">Drupal handbook</a> available online and should be used in conjunction with it. The online reference handbook might be more up-to-date and has helpful user-contributed comments. It is your definitive reference point for all Drupal documentation.</p>
', array('@Drupal' => 'http://drupal.org', '@handbook' => 'http://drupal.org/handbook'));
      return $output;
    case 'admin/help#help':
      $output = '<p>'. t('The help module displays context sensitive help information. Users can learn how to use modules and accomplish tasks quicker with less errors by clicking on links in provided by the help module.') .'</p>';
      $output .= t("<p>Modules can make documentation available to other modules with this module. All user help should be presented using this module. Some examples of help: </p>
<ul>
<li>The module's help text, displayed on the <a href=\"@help\">help page</a> and through the module's individual help link.</li>
<li>More elaborate help text on sites a module defines.</li>
<li>The help for a distributed authorization module (if applicable).</li>
</ul>
", array('@help' => url('admin/help')));
      $output .= '<p>'. t('For more information please read the configuration and customization handbook <a href="@help">Help page</a>.', array('@help' => 'http://drupal.org/handbook/modules/help/')) .'</p>';
      return $output;
  }
}

Not sure how to handle reporting both a core and documentation error.

todd nienkerk’s picture

todd nienkerk commented
Status: Active » Closed (works as designed)

Per webchick on IRC, markup is allowed in t() when the context of the markup is necessary to translate the text. I will open an issue to amend the documentation on t() to reflect this approach.

keith.smith’s picture

keith.smith commented

Re: #4, are you sure that's the help_help() from Drupal 6?

Drupal 6's actual help_help() function says, as far as I know, says:

/**
 * Implementation of hook_help().
 */
function help_help($path, $arg) {
  switch ($path) {
    case 'admin/help':
      $output = '<p>'. t('This guide provides context sensitive help on the use and configuration of <a href="@drupal">Drupal</a> and its modules, and is a supplement to the more extensive online <a href="@handbook">Drupal handbook</a>. The online handbook may contain more up-to-date information, is annotated with helpful user-contributed comments, and serves as the definitive reference point for all Drupal documentation.', array('@drupal' => 'http://drupal.org', '@handbook' => 'http://drupal.org/handbook')) .'</p>';
      return $output;
    case 'admin/help#help':
      $output = '<p>'. t('The help module provides context sensitive help on the use and configuration of <a href="@drupal">Drupal</a> and its modules, and is a supplement to the more extensive online <a href="@handbook">Drupal handbook</a>. The online handbook may contain more up-to-date information, is annotated with helpful user-contributed comments, and serves as the definitive reference point for all Drupal documentation.', array('@drupal' => 'http://drupal.org', '@handbook' => 'http://drupal.org/handbook')) .'</p>';
      $output .= '<p>'. t('For more information, see the online handbook entry for <a href="@help">Help module</a>.', array('@help' => 'http://drupal.org/handbook/modules/help/')) .'</p>';
      return $output;
  }
}

Now, the function you quote may be in Drupal 5. A concerted effort was made to move tags out of strings, except where they are necessary to provide context. If any tags like <p> still exist in HEAD, then please file an issue. Older versions are string-frozen; patching these strings in other versions would break translations.

dave reid’s picture

dave reid
he/him
Primary language English
Location Nebraska USA
commented

Wow....so I've been doing this all wrong. The documentation for t() itself is wrong as well:

Here is an example of t() used correctly:

$output .= '<p>' . t('Go to the <a href="@contact-page">contact page</a>.', array('@contact-page' => url('contact'))) . '</p>';
keith.smith’s picture

keith.smith commented

@Dave Reid: What's wrong with that example? It looks right to me. The paragraph tags are not in t(), and the a tags are, so it's clear what is a link and what's not.

dave reid’s picture

dave reid
he/him
Primary language English
Location Nebraska USA
commented

Ah, I thought it was being discussed that <a href="@contact-page">contact page</a> was the mis-use. Nevermind. :)

todd nienkerk’s picture

todd nienkerk commented
Status: Active » Closed (works as designed)

@keith.smith re: #6: It appears the API documentation for help_help() has changed since I posted #4. (I think this is the case because the API has undergone some significant changes recently.)

@Dave Reid: The use of <a> elements was part of the confusion. The original documentation for t() (on d.o, not in the API) flatly denied the use of markup, yet it specifically said <a> elements should be included inside the translation string. Per #5 above, markup is allowed, so long as it's necessary for context.

todd nienkerk’s picture

todd nienkerk commented

Here's the issue I said I'd file in #5 above: #362324: API: t() documentation flatly denies markup