@pureartisan/simple-i18n-react
v1.4.2
Published
Simple i18n React component using @pureartisan/simple-i18n library
Downloads
1
Maintainers
Readme
Simple I18n React
React component for i18n translations using @pureartisan/simple-i18n. This supports translations to have HTML tags that are safe to use (by avoiding updating the DOM html directly, disabling XSS).
Installation
Note, this module has a peer-dependency with @pureartisan/simple-i18n
. We decided to do that as this is an extension of @pureartisan/simple-i18n
for react and we don't want to double-include the dependency in the distrubition.
npm install @pureartisan/simple-i18n-react @pureartisan/simple-i18n
Getting started
For usage information of @pureartisan/simple-i18n
, please checkout the github repo.
Translations
// ES5
var Translate = require('@pureartisan/simple-i18n-react');
// ES6
import Translate from '@pureartisan/simple-i18n-react';
// assuming i18n translations are already setup using SimpleI18n as below:
const languages = {
'en': {
'help-info.body': 'Lorem ipsum'
}
};
// let's create a simple component
const HelpInfo = () => (
<div className="help-info">
<Translate i18nKey="help-info.body" />
</div>
);
Dynamic variables
// assuming i18n translations are already setup using SimpleI18n as below:
const languages = {
'en': {
'profile-header.greeting': 'Hi {firstName}'
}
};
// let's create a simple component
const ProfileHeader = ({ user }) => (
<div className="profile-header">
<Translate i18nKey="profile-header.greeting" options={{ firstName: user.first_name }} />
</div>
);
HTML tags
You are allowed to use basic HTML tags in the translations, with basic attributes. Attributes will be passed to the elements as props, so don't forget to use className
instead of class
for CSS classes.
const languages = {
'en': {
'help-info.body': 'For more information, visit our <a href="http://my-support.com">support page</a><br />Don\'t forget to leave us an amazing <strong className="red-text">review</strong>.'
}
};
// let's create a simple component
const HelpInfo = () => (
<div className="help-info">
<Translate i18nKey="help-info.body" />
</div>
);
// when rendered, will generate
<div class="help-info">
For more information, visit our <a href="#">support page</a>
<br />
Don\'t forget to leave us an amazing <strong class="red-text">review</strong>.
</div>
NOTE
The link in the above example has been converted to a #
when rendered, this is to prevent users accidentally clicking it and being redirected to another URL. In most cases, React applications will be a sinlge page application. In order to handle this link being clicked event, please see the Link Click Handling
NOTE
Illegal tags such as script
, iframe
, img
are ignored and their content text will be displayed in the translation as static text:
'en': {
...
'illegal-translation': 'I have some <script>alert('illegal');</script> translation'
...
};
// rendering
<div className="illegal-example">
<Translate i18nKey="illegal-translation" />
</div>
// will generate the following DOM with the content being static text
<div class="illegal-example">
I have some alert('illegal'); translation
</div>
NOTE
Illegal attribtues such as any event handlers onclick
, onload
, onkeypress
are ignored:
'en': {
...
'illegal-attributes': 'I have some <div onClick="myClickHandler();">Click here</div> translation'
...
};
// rendering
<div className="illegal-attribtues-example">
<Translate i18nKey="illegal-attributes" />
</div>
// will generate the following DOM with no event handlers
<div class="illegal-attribtues-example">
I have some <div>Click here</div> translation
</div>
You should not be using event handlers in translations. If you are in a situation that is required, then your code design is possibly flawed and is opening up to future issues. We recommend refactoring the approach.
Link Click Handling
In general, applcations have their own way of handling link clicks. Such as opening on a new tab, etc. This can be initialised one time at the start of your application.
import Translate from '@pureartisan/simple-i18n-react';
Translate.setDefaultLinkHandler(function(link) { // link was taken from 'href' attribute
// my awesome way to handle the link click
myAwesomeUrlClickHandler.open(link);
});
Now that you have already setup a general link handler, perhaps you want to change the way a single link works compared to the rest of the links:
const languages = {
'en': {
'feedback.body': 'Please leave us some <a href="feedback-handler">feedback</a>.'
}
};
// my custom click handler
var myFeedbackClickHandler = function() {
// open feedback popup
};
// let's create a simple component, but override the default link handler just for this component
const HelpInfo = () => (
<div className="feedback-section">
<Translate i18nKey="feedback.body" onLinkClick={myFeedbackClickHandler} />
</div>
);
NOTE In the above example, in order for link handling to be triggered when a user clicks on the link, we had to set href
to something other than empty string or #
. If href
is not provided, is empty or set to #
, the click handling is ignored.