Fb:intl
From Facebook Developer Wiki
Contents |
Description
Marks a string of English text as translatable into other languages. The text will appear in the user's language if it has been translated, and will be recorded in your application's list of translatable strings if not already present. For more information, see Internationalization.
To incorporate variables into the text, your text should contain tokens, which are delimited by curly braces (by default) and act as placeholders. The tokens are replaced at display time with corresponding values from fb:intl-token tags enclosed by this tag. Use tokens and fb:intl-token instead of directly including your dynamic values in the text itself; otherwise each dynamic value will have to be individually translated. See the examples below. Any tokens with numbers or dates as their values will be automatically localized.
Your text can contain FBML and HTML tags. See the #Notes section below for more information.
Attributes
| Required | Name | Type | Description | |
| optional | desc | string | Descriptive text to clarify the context in which the text is used, and the meaning if it is ambiguous. This is shown to translators in the bulk translation user interface, among other places, and should describe the text well enough that someone can translate it without seeing it in the context of your application. In general a piece of text should always have a description unless it is a complete sentence whose meaning would be clear to a user who has never seen your application. | |
|---|---|---|---|---|
| delimiters | string | Text may contain tokens to represent variables (dynamically generated values). Tokens are normally delimited by open and close curly braces, e.g., {name}. This attribute allows you to use alternate characters. Its value must be two characters long; the first character marks the start of a token and the second marks the end. These two characters must be distinct. |
Examples
This text is self-explanatory and is a complete sentence including ending punctuation, so a translator will be able to correctly translate it even without a description.
Here the description tells the translator both where the text appears (as a form label) and what it refers to (a restaurant, as opposed to a person.) Thanks to the description, a translator can choose the correct word here even in languages that have a different word for "name" depending on whether the name is a person's or a place's.
The token "{number}" is replaced by the contents of the <fb:intl-token> tag with the same name.
The link text is translatable, but the link target is not. See the Notes section for more on this technique.
Notes
Tokens and Dynamic Text
Since every unique piece of text inside an <fb:intl> tag is entered into the database of translatable phrases, you should be careful to use tokens for values that change depending on context. For example, an application dealing with events might display a message like, "Your event starts at 6:15." A simple (and incorrect) approach is to insert the time directly into your text and wrap the result in <fb:intl>, like so:
This will cause "Your event starts at 6:15." to appear in the Translations application. But then, when the next user sees the same message with a time of 8:30, this approach will cause a separate translatable string ("Your event starts at 8:30.") to be added to the database. You will effectively be asking your volunteer translators to translate hundreds of versions of that message for all the possible time values. The problem gets even worse when you're dealing with something less constrained than time, such as people's names -- there will be a potentially infinite amount of work for translators to do, and your application will never be fully translated.
The correct way to do this is to use a token for the part of the text that can change from request to request:
Only the text inside the <fb:intl> tag gets inserted into the translatable strings database, and the contents of the <fb:intl-token> are inserted at display time. Now your translators only have to translate this sentence once.
It is perfectly legal to nest <fb:intl> tags inside <fb:intl-token> tags; this is used when making link text translatable, and will be described below.
HTML Tags, Including Links
Your translatable strings may contain HTML tags. HTML tags are included verbatim in the translatable text, and translators will be free to rearrange them or get rid of them as they see fit. For that reason, you should only include tags that indicate emphasis -- <b>, <i>, and so on. Tags such as <div> or, worst of all, <a>, should never be included in your translatable text. Instead, use a token to denote a link, like this:
The enclosing translatable string ("Click {here} to update your settings.") does not contain any HTML tags; the "{here}" token represents the link. The value of the token is the opening <a> tag (which is not translatable), followed by the translatable word "here" with a desc that describes the context in which it appears, followed by the closing </a> tag (which is not translatable.) Translators will translate the enclosing sentence and put the token in the appropriate place in the translated sentence, and will also translate the word "here", but will not ever see the <a> tag in the translation tool.
Use this technique for any HTML markup that is functional rather than grammatical in nature, as well as for things like images that you want to display inline:
If a tag has an attribute (such as a caption or title) that needs to be translatable, render the tag with fb:tag, which allows you to embed <fb:intl> tags in the attribute value. See fb:tag for more details.
You should almost always put structural elements outside <fb:intl> tags, since you won't want translators rearranging your page.
For example, do this:
But don't do this:
FBML Tags
Your translatable strings may also contain FBML tags. These are treated differently than regular HTML tags, since they usually involve dynamic content. In general, FBML tags are divided into two categories: Tags like fb:name that can output arbitrary text and markup, and enumerable tags like fb:pronoun that always output one of a fixed set of values. The FBML interpreter handles these two types of tags very differently.
The FBML interpreter automatically turns tags such as fb:name into tokens in your translatable text, and uses the output of the tag as the token value.
For example:
Results in the following text in the Translations application:
This is done so that translators can translate the sentences without knowing anything about FBML tags. You may freely change the attributes of the <fb:name> tag here; for example, no matter which user ID you use, the same translation will be looked up.
Most FBML tags fall into this first category.
The second category, whose most common member is the <fb:pronoun> tag, is handled very differently. If you have the following text:
This is actually turned into three separate entries in the translation database:
He sent you a message.
They sent you a message.This allows the sentence to be translated correctly in languages where the verb "sent" needs to change depending on the gender of the subject.
The two styles of tags can, of course, be combined:
This causes three separate entries to be created in the translation database:
See Also
- Fb:fbml-attribute for text within HTML attributes
