README
i18n tools for React
This library is meant to be used as glue code between React and your favorite i18n library. You can use it standalone, too.
Features
- Compatible with any i18n library.
- Compatible with isomorphic/server-side rendering.
Example
import React from 'react';
import ReactDOMServer from 'react-dom/server';
import { I18nProvider, Translate } from 'react-i18n-wrapper';
const translations = {
en: {
'hello-world': 'Hello World!',
},
fr: {
'hello-world': 'Bonjour Monde!',
},
};
const MyComponent = props => (
<div>
<Translate message="hello-world" />
</div>
);
console.log(
ReactDOMServer.renderToString(
// Wrap our top-level component in an `I18nProvider`
<I18nProvider language="en" translations={translations}>
<MyComponent />
</I18nProvider>
)
);
API
I18nProvider
Component used to provide i18n context to child components.
Props:
translate({translations, language, message, params})
- A function to call to translate a message. If you don't providetranslate()
, a simple default implementation is used. See below for details.translations
- An arbitrary object which will be passed along to yourtranslate()
function. Using the defaulttranslate()
function, this should be an object where keys are locales, and values are maps of message keys to translated strings.language
- The locale to translate things into. This is a default and can be changed viauseI18n().setLanguage()
.noEscape
- If true, then all Translate components will behave likenoEscape
was set by default.
Translate
Props:
message
- The message key to translate. This is passed on to yourtranslate()
function.params
- Parameters to pass on to thetranslate()
function. This is an arbitrary object.noEscape
- If true, the translated message will be rendered without escaping the result.tagName
- Controls the element created by Translate. By default,Translate
will return a bare string, setting this will wrap the returned value in the specified type. Note that ifnoEscape
is true, this will default to 'span'.className
- Class name to add to the generated element. Only used iftagName
is set.
withI18n
This is a higher order component which provides the i18n
context object via
props. In most cases, you probably want to use Translate
to translate
messages, but in some cases you may want to access this directly:
import { withI18n } from 'react-i18n-wrapper';
class MyForm extends React.Component {
render() {
<textarea placeholder={this.props.i18n.translate('placeholder_text')} />;
}
}
export default withI18n(MyForm);
Here, this.props.i18n.translate(message, params)
is a function that can
translate a string, and this.props.i18n.language
is the current locale.
useI18n
An alternative to withI18n
, useI18n
provides a React hook which lets you
call into the translate function directly within your code:
import { useI18n } from 'react-i18n-wrapper';
export function MyForm(props) {
const i18n = useI18n();
return <textarea placeholder={i18n.translate('placeholder_text')} />;
}
Default translate() function
The default translate()
function expects translations
to be an object where
keys are locales, and values are maps of message keys to translated strings. The
default translate()
can also do some simple substitutions:
const translations = {
en: {
hello: 'Hello {name}!',
},
};
const MyComponent = props => <Translate message="hello" params={{ name: 'Jason' }} />;
The default translate()
can also accept a message
that is an object with
locales as keys:
const translateableObject = {
en: 'here',
fr: 'ici',
};
const MyComponent = props => <Translate message={translateableObject} />;