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

I think it would be a good idea to mention that t() expects a string written in English as soon as possible, maybe even on the first line. This could help a little to prevent Drupal starters doing something that we've just found in a random (custom) module:

<?php
print t('Bonjour');
?>
Files: 
CommentFileSizeAuthor
#7 1265294-doc-t.patch1.29 KBsven.lauer
PASSED: [[SimpleTest]]: [MySQL] 35,971 pass(es).
[ View ]

Comments

Hmm...

Parameters

$string A string containing the English string to translate.

Yeah, I know. This is minor than minor, but still, you can't see this info without scrolling. I hope you see my point here (= allowing "first-time users" to get the grasp of the function as soon as possible).

The @param is normally the correct place to mention specifics of a parameter...

That said, if you can fit this into the one-line description, something like
Translates a string from English to ...
in less than 80 characters, I'd say go for it.

Otherwise, if it doesn't fit in 80 characters, I'm afraid it's a "won't fix". Thoughts?

I think a good way to do this would be in the opening paragraph. Something like (added sentence in bold):

The t() function serves two purposes. First, at run-time it translates user-visible text into the appropriate language. Second, various mechanisms that figure out what text needs to be translated work off t() -- the text inside t() calls is added to the database of strings to be translated. These texts are expected to be in English, so the first argument should always be a string in English. To enable a fully-translatable site, it is important that all human-readable text that will be displayed on the site or sent to a user is passed through the t() function, or a related function. See the Localization API pages for more information, including recommendations on how to break up or not break up strings for translation.

Putting this in the initial one-line description makes it easy to overlook it, and does not give a rationale. Having it in the first paragraph means we can be more explicit, it would still be visible without scrolling, and people would see it when they try to figure out what t() does.

I have no objection to this idea. But it should say "This text" instead of "These texts". Text (I think) is not a countable noun in English.

My initial thought was exactly the same as in #3, but I would welcome any improvement on this :)

Version:7.x-dev» 8.x-dev
Issue tags:+needs backport to D7
StatusFileSize
new1.29 KB
PASSED: [[SimpleTest]]: [MySQL] 35,971 pass(es).
[ View ]

@jhodgdon: I think you are right about "text". Anyhow, I went with "these strings", because it really refers back to the strings stored in the database for translation.

Patch attached. Also applies cleanly to 7.x.

Status:Active» Needs review

Status:Needs review» Reviewed & tested by the community

Looks fine, thanks!

Version:8.x-dev» 7.x-dev

Committed to 8.x. Thanks.

Did this patch not apply to D7? I'll retest...

#7: 1265294-doc-t.patch queued for re-testing.

Status:Reviewed & tested by the community» Fixed

Committed and pushed to 7.x. Thanks!

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