email_example.module中@name等标记的作用、实现机制及t函数规范问询

Hey there! Let's break down those @ markers you're seeing in Drupal's email_example.module—they're a core part of Drupal's translation and dynamic string handling system, and super important for keeping your code secure and translatable.

These are placeholders used with Drupal's t() function (the core translation function). They act as dynamic slots in text strings, letting you insert variable content (like a username or your site's name) while keeping the base string intact for translation. Instead of hardcoding or concatenating variables directly into text (which breaks translation workflows), you use these placeholders to keep everything clean.

Let's use the code snippet you shared to walk through this:

$message['body'][] = t('@name sent you the following message:', array('@name' => $user->name), $options);

Here's the play-by-play:

1. The t() function first looks for a translated version of the base string '@name sent you the following message:' (based on the site's active language).
2. It then replaces the @name placeholder with the value from the second parameter—$user->name—in the translated string.
3. Critically, the @ prefix tells Drupal to automatically escape HTML special characters in the replacement value. So if a username had something risky like <script>malicious-code</script>, it would get converted to safe text (<script>malicious-code</script>) to prevent XSS attacks.

Drupal has three main placeholder types, each with a different behavior:

• @ (safe, escaped): Default choice for most dynamic content (usernames, node titles, etc.)—prevents XSS and keeps text safe.
• % (safe, escaped + emphasized): Same as @, but wraps the content in <em> tags for visual emphasis (e.g., %site-name would become <em>My Awesome Site</em>).
• ! (raw, unescaped): Only use this if you're 100% sure the content is safe (like static HTML you've written yourself). It outputs the value exactly as-is, no escaping—so it's a security risk if used with user-generated content.

As for @site-name, that's a built-in global placeholder in Drupal. It automatically pulls your site's name from the system configuration (the one you set in /admin/config/system/site-information), so you don't need to pass it in the replacement array—t() handles it for you automatically.

• Always wrap translatable text in t(): Don't concatenate variables directly into strings (e.g., avoid $user->name . ' sent you a message'). This ensures translation tools can pick up the full string.
• Pick the right placeholder type: Prioritize @ for safety, use % only when you need emphasis, and avoid ! unless you have no other option.
• Use descriptive placeholder names: Names like @username or @node-title make it clear to translators what the placeholder represents, instead of vague labels like @x or @val.
• Never include special characters in placeholder names: Stick to alphanumeric characters and underscores to avoid issues with parsing.

内容的提问来源于stack exchange，提问作者alec