Drupal API-T ()

Document directory

• Parameters
• Return Value

File ID des/common. inc

 

The main function of this function is to translate the English language to be translated in the code, and provide the Formatting Function to facilitate display on the page. note that St () should be used to replace T () during installation. The system provides get_t () to return the current T ()

 

The following is the function documentation in the API.

 

Translate strings to the page language or a given language.
Translate text into the language or specific language set for the page.

 

Human-readable text that will be displayed somewhere within a page shocould be run through the T () function.
You can use this method to obtain the text that is easy to read and displayed on the page.

 

Examples:

<? Php <br/> If (! $ Info |! $ Info ['extension']) {<br/> form_set_error ('picture _ upload', T ('the uploaded file was not an image. '); <br/>}< br/> $ form ['submit'] = array (<br/> '# type' => 'submit ', <br/> '# value' => T ('Log in'), <br/>); <br/>?> 

 

 

Any text within T () can be extracted by translators and changed into the equivalent text in their native language.
Function t can translate any text in a local language

 

Special variables called "placeholders" are used to signal dynamic information in a string which shoshould 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.
In the text, "placeholders" can be used to identify "Dynamic Information" that does not need to be translated (such as the number of online users of the website), and "placeholders" can be used to identify content that rarely changes, even changes do not affect the "Dynamic Information" that you understand"

 

 

For example:

<? Php <br/> $ output = T ('there are currently % members and % visitors online. ', array (<br/>' % Members '=> format_plural ($ total_users, '1 user',' @ count users '), <br/> '% visitors' => format_plural ($ guests-> count, '1 guest ',' @ count guests'); <br/>?> 

 

There are three styles of placeholders:
Placeholders have three forms:

• ! Variable, which indicates that the text shocould be inserted as-is. This is useful for inserting variables into things like e-mail
  ! Variable, which directly calls the PHP function strtr () in the T () code implementation. This mode is effective when data such as email needs to be inserted in the text.

<? Php </P> <p> $ message [] = T ("if you don't want to receive such e-mails, you can change your settings! URL. ", array ('! URL '=> URL ("User/$ account-> uid", array ('absolute' => true); </P> <p >?>

• @ Variable, which indicates that the text shocould be run through check_plain, to escape HTML characters. Use this for any output that's displayed within a Drupal page.
  @ Variable: encode the special characters contained in the text so that they can be displayed on the page. We recommend that you use this mode to display the text on the Drupal page.

<? Php </P> <p> drupal_set_title ($ Title = T ("@ name's blog", array ('@ name' => $ account-> name ))); </P> <p >?>

• % Variable, which indicates that the string shocould be HTML escaped and highlighted with used automatically by T (). "href =" API/function/theme_placeholder/6 "> theme_placeholder () which shows up by default as <em> emphasized </em>.
  % Variable: encode special characters in the text and highlight the styles on the page. The default style is <em> </em>

 <? Php </P> <p> $ message = T ('% name-from sent % name-to an e-mail. ', array (' % name-from' => $ user-> name, '% name-to' => $ account-> name )); </P> <p >?>

 

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. HTML markup within translation strings is allowed, but shoshould be avoided if possible. the exception are embedded links; Link titles Add a context for translators, so shocould be kept in the main string.
When T () is used, the text of the entire sentence or segment should be passed in to ensure correct results. Although T () supports HTML tags, try to avoid including them in the text.

 

Here is an example of incorrect usage of T ():
This is an example of improper use. html links in the text are directly displayed as content:

<? Php </P> <p> $ output. = T ('<p> go to the @ Contact-page. </P> ', array (' @ Contact-page' => L (t ('Contact page'), 'Contact '))); </P> <p >?>

 

Here is an example of T () used correctly:
This is the correct method:

<? Php </P> <p> $ 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>'; </P> <p>?>

 

Avoid escaping quotation marks wherever possible.
Avoid text escape quotation marks

Incorrect:
Incorrect:

<? Php </P> <p> $ output. = T ('Don/'t click me. '); </P> <p >?>

Correct:
Correct:

<? Php </P> <p> $ output. = T ("don't click me."); </P> <p >?>

 

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 ().
Because t () is designed to process code-based strings, in most cases, the text to be translated must be directly transmitted to T () and cannot be passed through a variable.

Extraction of translations is done based on the strings contained in T () CILS. If a variable is passed through T (), the content of the variable cannot be extracted from the file for translation.
The translation process is based on the text contained in the T () call process. If a variable is passed to T (), T () the variable cannot be extracted from the file for translation.

Incorrect:
Incorrect:

<? Php </P> <p> $ message = 'an error occurred. '; <br/> drupal_set_message (T ($ message), 'error'); <br/> $ output. = T ($ message); </P> <p >?>

Correct:
Correct:

<? Php </P> <p> $ message = T ('an error occurred. '); <br/> drupal_set_message ($ message, 'error'); <br/> $ output. = $ message; </P> <p >?>

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.
There is only one situation where variables can be safely used, that is, the text pointed to by the variables has been called directly in other places t ()

In some cases, modules may include strings in code that can't use t () CILS. 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.
Some modules need to output text variables pointing to external code, which cannot be directly implemented by referencing a dummy file containing the relevant text.

Sample external (non-Drupal) code:
External code example:

<? Php </P> <p> class time {<br/> Public $ yesterday = 'yesterday'; <br/> Public $ today = 'today '; <br/> Public $ Tomorrow = 'tomorrow'; <br/>}</P> <p >?>

Sample dummy file:
Dummy file example:

<? Php </P> <p> // dummy function encoded in example. potx. inc. <br/> function example_potx () {<br/> $ strings = array (<br/> T ('yesterday'), <br/> T ('today '), <br/> T ('tomorrow'), <br/>); <br/> // No return value needed, since this is a dummy function. <br/>}</P> <p >?>

Having passed strings through T () in a dummy function, it is then okay to pass variables through T ().
After passing the real text to T () in dummy function, you can use the relevant variables during the T () call.

However tempting it is, custom data from user input or other non-code sources shocould not be passed through T (). Doing so leads to the following problems and errors:
Do not use t () for translation of custom data and non-code sources at any time. In this case, the following problems and errors will occur:

• 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.
  The translation system does not support updating existing texts. when user data is updated and T () translation is used again, the translation system will save a new translation record and will not update the original record. the translation data stored in the database expands with each update.
• The T () system assumes any data it has ES is in English. User data may be in another language, producing translation errors.
  The translation system can only translate English text. User data may be in other languages, which may cause 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.
  In the localization system, the "Built-in Interface" group is used to save those stored in. the Translation Data in the Po file. non-code strings passed to T () will also be saved to this group. If the user input is confused with the built-in interface text, a translation error will occur.

Incorrect:
Incorrect:

<? Php </P> <p> $ item = item_load (); <br/> $ output. = check_plain (T ($ item ['title']); </P> <p >?>

Instead, translation of these data can be done through the locale system, either directly or through helper functions provided by contributed modules.
The correct method is to use locale system, or the relevant methods provided by the publishing module.

 

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.