Welcome to another post in our “Did You Know?” series! I’m Sandy, part of the Customer Success team at Transifex, and in this post, we’ll explore how you can customize the Transifex Live snippet for even greater control over your website translations. Whether it’s language detection, the placement of the language picker, or managing how dynamic content is translated, the window.liveSettings object offers a flexible way to fine-tune how Transifex Live works on your site.
In this post, we’ll explore how to customize the Transifex Live snippet, using practical examples and real-world use cases to help you get the most out of it.
The Snippet component
Before we get into specific examples, let’s look at the general structure of the Transifex Live snippet. Most of the customization happens through the window.liveSettings object, which defines the behavior of the Transifex Live API:
window.liveSettings = {
api_key: "<key>", // Your Transifex Live API key
detectlang: true, // Automatically detects user language
picker: "top-right", // Places the language picker in the top-right corner
version: 'latest', // Specifies the version of the Transifex Live snippet
autocollect: true, // Automatically collects translatable content
dynamic: true, // Detects and translates dynamic content
staging: false, // Defines whether it's a staging environment
xss_protect: true, // Enables protection against XSS attacks
parse_attr: ["title", "alt"], // Attributes to parse for translation
ignore_tags: ["code", "script"], // HTML tags to ignore during translation
ignore_class: ["no-translate"], // Classes to ignore during translation
manual_init: false, // Automatically initializes Transifex Live
translate_urls: true // Enables translation of URLs
};
Let’s break down some common use cases for customizing this snippet with practical examples.
1. Initialization Parameters
api_key (string, required)
The api_key is required and links the snippet to your Transifex project. This is essential for authenticating the translations.
Example:
window.liveSettings = {
api_key: "your-transifex-live-api-key",
};
Use Case: This key is necessary to establish a connection between your website and your Transifex project. Always include this when you’re setting up the Transifex Live snippet for the first time.
detectlang (boolean | function)
Automatically detects the user’s language based on browser settings or allows you to define a custom detection function.
Example (Auto-detect language):
window.liveSettings = {
api_key: "your-transifex-live-api-key",
detectlang: true,
};
Example (Custom language detection):
window.liveSettings = {
api_key: "your-transifex-live-api-key",
detectlang: function() {
return navigator.language || navigator.userLanguage;
}
};
Use Case: If you want to automatically detect the user’s preferred language based on their browser settings, you can enable detectlang: true. In cases where you have custom rules for language detection (e.g., based on user profile settings), use the custom detection function.
picker (string | selector)
Defines where the language picker appears on the page. It can be positioned in the four corners of the screen or attached to a specific element using a CSS selector.
Example (Position picker in the top-right corner):
window.liveSettings = {
api_key: "your-transifex-live-api-key",
picker: "top-right"
};
Example (Attach picker to an element with a specific ID):
window.liveSettings = {
api_key: "your-transifex-live-api-key",
picker: "#language-picker"
};
Use Case: You may want the language picker to be easily accessible, like in the top-right corner of the screen, or placed in a specific part of the website, like the footer or navigation bar.
version (string)
Specifies the version of the Transifex Live script to use. By default, it uses the latest version.
Example:
window.liveSettings = {
api_key: "your-transifex-live-api-key",
version: "latest"
};
Use Case: In most cases, you should use the latest version to ensure you have all the latest features and bug fixes. However, if you’re testing or developing with a specific version, you can specify it here.
autocollect (boolean)
Automatically collects and sends translatable content to your Transifex project.
Example:
window.liveSettings = {
api_key: "your-transifex-live-api-key",
autocollect: true
};
Use Case: For a basic setup where you want all text on the page to be automatically detected and sent to Transifex for translation, you can leave autocollect set to true. This is ideal for static content-heavy sites.
dynamic (boolean)
Enables detection and translation of dynamically loaded content.
Example:
window.liveSettings = {
api_key: "your-transifex-live-api-key",
dynamic: true
};
Use Case: For Single Page Applications (SPAs) or websites with AJAX-driven content (like user comments or product updates), enabling dynamic ensures that content loaded after the initial page load is also translated.
staging (boolean)
Defines whether the environment is a staging environment. If true, content is collected but not visible on the production site.
Example:
window.liveSettings = {
api_key: "your-transifex-live-api-key",
staging: true
};
Use Case: This is perfect when you’re testing translations in a staging environment and don’t want those translations to affect the live site.
xss_protect (boolean)
Enables protection against Cross-Site Scripting (XSS) attacks during translation.
Example:
window.liveSettings = {
api_key: "your-transifex-live-api-key",
xss_protect: true
};
Use Case: Security-conscious sites that handle sensitive data or have large user bases should enable XSS protection to prevent malicious scripts from being injected into translated content.
parse_attr (array)
An array of HTML attributes to parse for translation (e.g., title, alt).
Example:
window.liveSettings = {
api_key: "your-transifex-live-api-key",
parse_attr: ["title", "alt"]
};
Use Case: If you have important content stored in HTML attributes, like image alt text or link titles, this setting ensures those are translated along with the visible text.
ignore_tags (array)
Defines which HTML tags to ignore during translation.
Example:
window.liveSettings = {
api_key: "your-transifex-live-api-key",
ignore_tags: ["code", "script"]
};
Use Case: If your site has code blocks or scripts that shouldn’t be translated (like programming tutorials or backend scripts), you can list those tags here to prevent them from being processed.
ignore_class (array)
Defines which CSS classes to ignore during translation.
Example:
window.liveSettings = {
api_key: "your-transifex-live-api-key",
ignore_class: ["no-translate"]
};
Use Case: Sometimes, you have specific elements (like product names or trademarks) that shouldn’t be translated. Assigning them a class (e.g., no-translate) ensures they remain in the original language.
manual_init (boolean)
If true, Transifex Live will only initialize when manually triggered.
Example:
window.liveSettings = {
api_key: "your-transifex-live-api-key",
manual_init: true
};
Use Case: This is useful when you want to control when Transifex Live starts translating, such as waiting for the user to perform an action or after all page content is fully loaded.
translate_urls (boolean)
Enables translation of URLs in the page content.
Example:
window.liveSettings = {
api_key: "your-transifex-live-api-key",
translate_urls: true
};
Use Case: In multilingual websites, URLs may also need translation to make the navigation fully localized (e.g., /es/contacto instead of /en/contact). Enabling translate_urls ensures these links reflect the correct language.
Conclusion
With these customization options and examples, you can tailor the Transifex Live snippet to meet the specific needs of your website. Whether you’re managing dynamic content, setting up secure translations, or ensuring certain elements remain untranslated, the window.liveSettings object gives you full control.
These features streamline the localization process, ensuring your multilingual site provides an excellent user experience in every language. Take advantage of these options to optimize your workflow and deliver seamless translations for your global audience.
We encourage you to try out these features today and see the difference they can make. If you have any questions or need further assistance, feel free to respond to this post or reach out to us for help. For a deeper dive into each option, check out our full documentation and start customizing!