Internationalization/Markup/XFBML
From Facebook Developer Wiki
Contents |
XFBML Markup for Internationalization
In order for you to submit structured text for use with Facebook Translations on your own IFrame/website, there are a number of XFBML tags that have been created to accomplish this.
- fb:intl -- The principal tag for making a string of text translatable.
- fb:intl-token -- Replaces a token contained within fb:intl with its content.
- fb:tag-attribute -- Contains the value of an HTML attribute that should be added to the parent tag.
- fb:window-title -- Including this allows the window title of the current IFrame to be translatable. Note that this tag is only useful for Facebook Connect websites.
Note: This article assumes basic familiarity with XFBML.
Exploring Some Examples
Following are a number of examples demonstrating some common use cases.
Basics of fb:intl for XFBML
Let's assume that we want to include (and internationalize) the string "Hello World." Assuming our site was already XFBML-enabled, we would include the following in our HTML:
When rendered for the first time, the string will automatically be uploaded to Facebook to be translated, and this markup will display "Hello world!" Once a translation has been provided, it will instead return the translation in the locale of the viewing user.
Including Dynamic Content with fb:intl-token
Suppose after this greeting that we wanted to show the user a random number. Since this number has the potential to change to many different values, it's considered dynamic content that should not be translated. To include it within our site, we could do the following (assuming 42 was our number randomly generated in JavaScript, generation not shown):
Thus, when the text is translated it will number-independent, instead of needing a different translation for every random number.
Using fb:name as a Token
Suppose that we then thank the viewing user for visiting. Their real name is already available through the fb:name tag, so we can simply do the following:
A shorthand version could also be done this way:
Both versions would be translatable as ""Thanks for visiting, {name}."
Being Stylish
If we wanted the last example to be more ostentatious, we can optionally include some styling like this:
This would render as "Thanks, {name}." Note that while only one level of styling is allowed inline within fb:intl, you may use a CSS class to circumvent this restriction.
Translating Attributes of HTML Tags
There are some HTML tags which have attributes which can take on text values, like the "value" attribute of an <input> tag or the "alt" text of an image. To make situations like these translatable, we can use fb:tag-attribute. Say we start with the following markup within a form:
This would become:
Messing with Our <head>
Generally speaking, XFBML will work anywhere in the <body> tag of your page. However, there's one important text field that this doesn't account for- the title of the window. Hence, we've introduced a special tag to handle this: fb:window-title. Place it anywhere in your document where normal XFBML can be parsed, and it will take the rendered contents of the tag and re-set your document's title. We could now enable a translated window title with the following:
Best Practices
Much of this may become clearer after reading the best practices for advice on how to best prepare your applications. We strongly encourage you to do so.
Other Examples
We've created two examples for you to start with to get an idea of how to make your own application or site translatable.
- A Simple Hello World
This is a simple HTML file that demonstrates how XFBML markup can be used to make a simple string translatable. - The Run Around, International Edition
The Run Around was our original Facebook Connect example web site, so it's only appropriate that it goes international as well. This is a more complicated example which touches on several of the more complex aspects of preparing an application for internationalization.
