Drupal API - t()

所属文件 includes/common.inc

 

这个函数的主要功能就是把代码中需要翻译的英文翻译成本地语言, 并提供格式化功能方便在页面上显示. 需要注意的是在安装过程中要使用 st() 代替 t() , 系统提供了 get_t() 返回当前应该使用那个 t() 

 

下面是API中的函数文档

 

Translate strings to the page language or a given language.
把文本翻译成和页面设置的语言或特定的语言.

 

Human-readable text that will be displayed somewhere within a page should be run through the t() function.
通过这个方法可以得到便于阅读并能够在页面上显示的文本.

 

Examples:

<?php if (!$info || !$info['extension']) { form_set_error('picture_upload', t('The uploaded file was not an image.')); } $form['submit'] = array( '#type' => 'submit', '#value' => t('Log in'), ); ?> 

 

 

Any text within t() can be extracted by translators and changed into the equivalent text in their native language.
函数 t 能使用本地语言翻译任何文本

 

Special variables called "placeholders" are used to signal dynamic information in a string which should not be translated. Placeholders can also be used for text that may change from time to time (such as link paths) to be changed without requiring updates to translations.
在文本中可以使用"占位符"来标识不需要翻译的"动态信息"(如网站的在线人数), 还可以用"占位符"来标识那些内容很少变动,即使发生变化也不会影响理解的"动态信息"

 

 

For example:

<?php $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:
占位符有3种表现形式:

• !variable, which indicates that the text should be inserted as-is. This is useful for inserting variables into things like e-mail
  !variable, 在 t() 代码实现中直接调用了 php 函数 strtr(). 在需要在文本中插入诸如 email 等数据时这种模式会很有效.

<?php $message[] = t("If you don't want to receive such e-mails, you can change your settings at !url.", array('!url' => url("user/$account->uid", array('absolute' => TRUE)))); ?>

• @variable, which indicates that the text should be run through check_plain, to escape HTML characters. Use this for any output that's displayed within a Drupal page.
  @variable, 对文字中包含的特殊字符进行编码，使其能够在页面上正常显示. 推荐使用这种模式在 Drupal 页面上显示文本.

<?php drupal_set_title($title = t("@name's blog", array('@name' => $account->name))); ?>

• %variable, which indicates that the string should be HTML escaped and highlighted with theme_placeholder() which shows up by default as <em>emphasized</em>.
  %variable, 对文字中包含的特殊字符进行编码并可以包含样式在页面上突出显示, 默认的样式使用<em></em>

 <?php $message = t('%name-from sent %name-to an e-mail.', array('%name-from' => $user->name, '%name-to' => $account->name)); ?>

 

When using t(), try to put entire sentences and strings in one t() call. This makes it easier for translators, as it provides context as to what each word refers to. HTML markup within translation strings is allowed, but should be avoided if possible. The exception are embedded links; link titles add a context for translators, so should be kept in the main string.
当使用 t() 时应该传入整句或整段的文本以确保得到正确的结果, 并且虽然 t() 支持 HTML 标记，但也应当尽量避免在文本中包含它们. 

 

Here is an example of incorrect usage of t():
这是一个使用不当的例子, 文本中的 HTML 链接会被当成内容直接显示出来:

<?php $output .= t('<p>Go to the @contact-page.</p>', array('@contact-page' => l(t('contact page'), 'contact'))); ?>

 

Here is an example of t() used correctly:
这是正确的使用方法:

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

 

Avoid escaping quotation marks wherever possible.
避免在文本转义引号

Incorrect:
错误的:

<?php $output .= t('Don/'t click me.'); ?>

Correct:
正确的:

<?php $output .= t("Don't click me."); ?>

 

Because t() is designed for handling code-based strings, in almost all cases, the actual string and not a variable must be passed through t().
由于 t() 被设计成处理 code-based strings, 所以在大多数情况下要翻译的文本必须直接传递给 t(), 不能通过一个变量来传递.

Extraction of translations is done based on the strings contained in t() calls. If a variable is passed through t(), the content of the variable cannot be extracted from the file for translation.
翻译过程是建立在 t() 的调用过程中包含文本的基础上的, 如果把一个变量传递给 t() , t() 就无法把变量指向的文本从文件中提取出来做翻译.

Incorrect:
错误的:

<?php $message = 'An error occurred.'; drupal_set_message(t($message), 'error'); $output .= t($message); ?>

Correct:
正确的:

<?php $message = t('An error occurred.'); drupal_set_message($message, 'error'); $output .= $message; ?>

The only case in which variables can be passed safely through t() is when code-based versions of the same strings will be passed through t() (or otherwise extracted) elsewhere.
只有一种情况可以安全的使用变量，那就是变量所指向的文本在其它地方以直接方式调用过 t()

In some cases, modules may include strings in code that can't use t() calls. For example, a module may use an external PHP application that produces strings that are loaded into variables in Drupal for output. In these cases, module authors may include a dummy file that passes the relevant strings through t(). This approach will allow the strings to be extracted.
有是模块需要输出指向外部代码的文本变量, 这是不能直接使用 t() 必须通过引用一个包含相关文本的 dummy file 来实现.

Sample external (non-Drupal) code:
外部代码示例:

<?php class Time { public $yesterday = 'Yesterday'; public $today = 'Today'; public $tomorrow = 'Tomorrow'; } ?>

Sample dummy file:
dummy file 示例: 

<?php // Dummy function included in example.potx.inc. function example_potx() { $strings = array( t('Yesterday'), t('Today'), t('Tomorrow'), ); // No return value needed, since this is a dummy function. } ?>

Having passed strings through t() in a dummy function, it is then okay to pass variables through t(). 
在 dummy function 中传递真实文本到 t() 以后就是可以在 t() 调用过程中使用相关的变量了.

However tempting it is, custom data from user input or other non-code sources should not be passed through t(). Doing so leads to the following problems and errors:
无论什么时候用户输入的自定义数据和 non-code sources  都不要使用 t() 做翻译, 这样做会出现下面描述的问题和错误:

• The t() system doesn't support updates to existing strings. When user data is updated, the next time it's passed through t() a new record is created instead of an update. The database bloats over time and any existing translations are orphaned with each update.
  翻译系统不支持更新已经存在的文本. 当用户数据更新后再次使用 t() 翻译, 翻译系统会保存一份新的翻译纪录并不会更新原有记录. 保存在数据库中翻译数据会随着每次更新不断的膨胀.
• The t() system assumes any data it receives is in English. User data may be in another language, producing translation errors.
  翻译系统只能对英文文本做翻译, 用户数据可能用的是其它语言，这样会导致翻译错误.
• The "Built-in interface" text group in the locale system is used to produce translations for storage in .po files. When non-code strings are passed through t(), they are added to this text group, which is rendered inaccurate since it is a mix of actual interface strings and various user input strings of uncertain origin.
  在本地化系统中 "Built-in interface" 组是用来保存那些存储在 .po 文件中的译文数据. 传递到 t() 中的 non-code strings 也会保存到这个组中, 当用户输入与内置接口文本发生混淆时会造成翻译错误.

Incorrect:
错误的:

<?php $item = item_load(); $output .= check_plain(t($item['title'])); ?>

Instead, translation of these data can be done through the locale system, either directly or through helper functions provided by contributed modules.
正确的方法是使用 locale system, 也可以使用发布模块提供的相关方法. 

 

Parameters

$string A string containing the English string to translate.

$args An associative array of replacements to make after translation. Incidences of any key in this array are replaced with the corresponding value. Based on the first character of the key, the value is escaped and/or themed:

• !variable: inserted as is
• @variable: escape plain text to HTML (check_plain)
• %variable: escape text and theme as a placeholder for user-submitted content (check_plain + theme_placeholder)

$langcode Optional language code to translate to a language other than what is used to display the page.

Return value

The translated string.