API page: http://api.drupal.org/api/drupal/includes%21bootstrap.inc/function/t/7

The docs for t() on D6 [http://api.drupal.org/api/drupal/includes!common.inc/function/t/6] have excellent examples of how to correctly use the placeholders in different circumstances:

For example:

$output = t('There are currently %members and %visitors online.', array(
'%members' => format_plural($total_users, '1 user', '@count users'),
'%visitors' => format_plural($guests->count, '1 guest', '@count guests')));

There are three styles of placeholders:

!variable, which indicates that the text should be inserted as-is. This is useful for inserting variables into things like e-mail.

[... etc]

These appear to have been lost.

t() now directs the reader to:

a) the Localization API page at http://drupal.org/node/322729, which does not have very detailed examples
b) the format_string() function, which has a very dry summary of placeholders that doesn't explain to the uninitiated what the different types actually do.

I used to be able to direct people on IRC to the docs for t() and all would be well. Today someone has just told me "There's much contention about how to do it and with what function".

Perhaps these comprehensive examples were moved somewhere rather than removed, but I can't find them after specifically looking for them for 5 minutes, so I doubt that someone who doesn't know they exist will be able to stumble upon then.

Please could they be restored to the documentation for t().

Files: 
CommentFileSizeAuthor
#4 placeholder_doc-1862198-4.patch959 bytesplopesc
PASSED: [[SimpleTest]]: [MySQL] 49,849 pass(es).
[ View ]

Comments

Status:Active» Closed (works as designed)

The docs on how to use the placeholders for t() have been moved to the format_string() docs, and the t() docs do say "See format_string() for details" in the appropriate place.

Status:Closed (works as designed)» Active

Yes, that's correct. But that doesn't say to newcomers 'You need to go and read this link to use this properly'. It seems to say, 'There are extra dry details for developers who tinker with the internals over there'. The information that everyday developers need to not use t() incorrectly needs to be on the actual page were it will be seen.

Title:important details on how to correctly use t() have been lostIt's not clear that you have to look at format_string() to find details of t() arg handling

OK, then let's make a small patch to t() that would make it clearer where to find the docs, but let's NOT duplicate the documentation on format_string().

StatusFileSize
new959 bytes
PASSED: [[SimpleTest]]: [MySQL] 49,849 pass(es).
[ View ]

Hello.

Attaching patch indicating that the arg handling doc is in format_string() function.

If you consider that the message should be more clearer or explicit, let me know.

Regards.

Status:Active» Needs review

Changing status

Status:Needs review» Reviewed & tested by the community

Seems fine to me, thanks!

Status:Reviewed & tested by the community» Fixed

Thanks again -- committed to 8.x and 7.x.

Automatically closed -- issue fixed for 2 weeks with no activity.