Polymer ^1.0 behavior that provides an easy translation service for your web components.
It uses same hierarchy as I18n
bower install --save data-translate-behavior
If you have some web components that need to be translated, but you don't want to translate it each time you use it. For example, clear button in input, or login form.
You should add it to your component's behaviors.
behaviors: [DataBehaviors.DataTranslate]Then you should add properties, that you want to be translated. For example, we'll add property labelClearButton and it's translations.
properties: {
labelClearButton: {
type: String,
computed: "t('labelClearButton', translations, currentLanguage)" //you have to specify path to property and 2 required arguments: translations and currentLanguage, which are required to notify changes in Polymer
},
translations: {
type: Object,
notify: true,
value: {
en: {labelClearButton: 'clear'}, //here you can add as many translations as you want
ru: {labelClearButton: 'стереть'}
}There are also options that you can specify for detection and changing of language.
detectLanguageFrom: {
type: String,
notify: true,
reflectToAttribute: true,
value: 'html' // any of available values
},
getLanguageFrom: {
type: String,
notify: true,
reflectToAttribute: true,
value: 'html' //all except server
}Values are:
html- detects and then gets language based onlangattribute(property) of
<html lang="en">sibling- detects and then gets language based on closest element (upper) withlangattribute(property). Ex:
<div lang="en">
<element>My Super Element</element>
</div>self- detects and then gets language based on current element'slangattribute(property). Ex:
<element lang="en">browser- detects and then gets language based onlanguageoruserLanguageorbrowserLanguageorsystemLanguageproperty ofwindow.navigator. It'll use the first not null.server- detects language based on url specified indetectRequestUrlandxhrresponse from the server.
<element detect-request-url="somecoolurl.json">-
t(string path)- returns translation based ontranslations[currentLanguage] + path. Required in Polymer computed properties. -
detectLanguage()- detects language based ondetectLanguageFromproperty and sets returned value tocurrentLanguageproperty. Useful whendetectLanguageFromwas set toserver. You'll have to calldetectLanguage()to grab language from the server. ThendetectLanguage()will automatically assign received value tocurrentLanguageproperty and update DOM. -
updateLanguage()- updates object based ongetLanguageFrom(later justobject) with value ofcurrentLanguageproperty. Basically, you should use this method if you want to updateobjectmanually. But remember that translations will only be updated ifcurrentLanguagehas changed. If you assignedservertodetectLanguageFrom, then this method will be called automatically on successful response ofupdateLanguage()after receiving new language from server. -
findAllDataTranslateOnPage()- returnsArrayof web components that was extended withDataTranslatebehavior.
Source: current document
findAllDataTranslateChildren(bool deep)- returnsArrayof web components that was extended withDataTranslatebehavior.
Source: current element's children.
bool deep - default: true. If true will search recursively, if false will search only in children property.
findDataTranslateChildrenBySelector(string selectors)- returnsArrayof web components that was extended withDataTranslatebehavior.
Source: current element's children.
It uses Element.querySelectorAll(selectors)
-
setPropToAllDataTranslateOnPage(string prop, newval)- sets the required property for all objects found byfindAllDataTranslateOnPage(). -
setPropToAllDataTranslateChildren(string prop, newval, bool self, deep)- sets the required property for all objects found byfindAllDataTranslateChildren().
Set self to true if you also want to set current element's property to newval.
setPropToDataTranslateChildrenBySelector(string selectors, string prop, newval, bool self)- sets the required property for all objects found byfindDataTranslateChildrenBySelector().
Set self to true if you also want to set current element's property to newval.
removeTranslations(string path)- removes specified translation from all languages.
path - path to translation.
data-translate-initialize- fired onattachedbefore adding Observer and detecting language.
It's better to add/change translations on this event, otherwise you'll have to switch language for changes to appear.
Also useful to set detectLanguageFrom or getLanguageFrom property. They're both reflectToAttribute: true. So, feel free to set them as atributes.
Example:
element.setPropToAllDataTranslateChildren('detectLanguageFrom', 'browser', true);current-language-change- fired whencurrentLanguageproperty changes.translations-change- fired whentranslationsproperty changes.
Data:
properties: {
mySuperLogin: {
type: String,
computed: "t('labels.login', translations, currentLanguage)"
},
mySuperTitle: {
type: String,
computed: "t('labels.mainTitle', translations, currentLanguage)"
},
mySuperPass: {
type: String,
computed: "t('labels.password', translations, currentLanguage)"
},
translations: {
type: Object,
notify: true,
value: {
en: {
labels: {
login: 'Username',
mainTitle: 'My Super Form',
password: 'Password'
}
},
ru: {
labels: {
login: 'Имя пользователя',
mainTitle: 'Моя классная форма',
password: 'Пароль'
}
}
}
}
}Use our functions:
$(document).ready(function(){
var element = document.querySelector('#ourCoolElement');
element.addEventListener('data-translate-initialize', function(e) {
element.setPropToAllDataTranslateChildren('detectLanguageFrom', 'browser', true); // when page is loading we're detecting our language from user's browser.
element.removeTranslations('labels.mainTitle'); // we don't want labels.mainTitle to show up
// we want to change some translations here
element.translations.en.labels.login = 'Email';
element.translations.ru.labels.login = 'Электронная почта';
});
element.addEventListener('current-language-change', function(e) {
console.log('My login: ' + element.mySuperLogin);
});
});