react-translate-maker

React translation module. Internationalize your great project. This library is part of translate-maker. Star this project on GitHub.

Installation

Install via npm.

npm install react-translate-maker

Versions

If you are using react >= 15.4.0 use version >= 0.3.0 otherwise use version < 0.3.0

Features

• Build on standards (ICU Message syntax, Unicode CLDR), ES6 and Promises
• Support for 190+ languages
• Runs in the browser and Node.js
• JSON Structure
• Nested and reference translations
• Variables
• Conditioned translations (Plural, Gender etc...)
• Filters capitalize, upperCase, lowerCase etc... and custom filters
• Default translations
• Integrates with React and Angular
• Automatic extraction of translations from your project
• For more details and examples click on translate-maker

Support us

Star this project on GitHub.

Usage

Basic example

importReactfrom'react';importTranslate,{LocaleProvider,TranslateMaker}from'react-translate-maker';consttranslate=newTranslateMaker({data: {en_US: {hello: 'Hello {$user.name}',followers: `{$user.name} has {$user.followers, plural, zero {no followers} one {# follower} {# followers} }`}}});constuser={name: 'Zlatko',followers: 15,};React.render(<LocaleProvidertranslate={translate}locale="en_US"><div><h1><Translatepath="hello"user={user}/></h1><Translatepath="followers"user={user}/></div></LocaleProvider>);

The result will be

<div><h1>Hello Zlatko</h1>
Zlatko has 15 followers
</div>

File adapter

If you want to load localisation files automatically with the require function you can use File adapter.

File structure

project
│ component.jsx
└──locales
│ en_US.js

en_US.js

exportdefault{gender: `{$gender, select, male {boy} female {girl}}`,working: `{gender, $user1.gender as gender | capitalize} {$user1.name} is working with {gender, $user2.gender as gender} {$user2.name}`};

component.jsx

importReactfrom'react';importTranslate{LocaleProvider,TranslateMaker,Gender,FileAdapter}from'react-translate-maker';importpathfrom'path';consttranslate=newTranslateMaker({adapter: newFileAdapter({path: path.join(__dirname,'/locales'),});});constcurrentLocale='en_US';constuser1={gender: Gender.MALE,name: 'Zlatko',};constuser1={gender: Gender.FEMALE,name: 'Livia',};React.render(<LocaleProvidertranslate={translate}locale={currentLocale}><Translatepath="working"user1={user1}user2={user2}/></LocaleProvider>);

The result will be

Boy Zlatko is working with girl Livia

File adapter and webpack

If you want to use webpack with file adapter you need to use own function getFile. You need to use getFile instead of path because you need to change the webpack context.

component.jsx

importReactfrom'react';importTranslate{LocaleProvider,TranslateMaker,Gender,FileAdapter}from'react-translate-maker';consttranslate=newTranslateMaker({adapter: newFileAdapter({getFile: (locale,namespace)=>require('./locale/'+locale),});});constcurrentLocale='en_US';constuser1={gender: Gender.MALE,name: 'Zlatko',};constuser1={gender: Gender.FEMALE,name: 'Livia',};React.render(<LocaleProvidertranslate={translate}locale={currentLocale}><Translatepath="working"user1={user1}user2={user2}/></LocaleProvider>);

Placeholder and direct translations

importReact,{Component}from'react';importTranslate,{LocaleProvider}from'react-translate-maker';constcurrentLocale='en_US';constdata={en_US: {inputSearch: 'Search',},};React.render(<LocaleProvideradapter={data}locale={currentLocale}><Translatepath="inputSearch"defaultValue="Search...">{placeholder=>(<inputtype="text"placeholder={placeholder}/>)}</Translate></LocaleProvider>);

The result will be

<inputtype="text" placeholder="Search" />

Direct translations

importReact,{Component}from'react';import{LocaleProvider,ProvideTranslate}from'react-translate-maker';classMyComponentextendsComponent{render(){const{ translate }=this.props;return(<inputtype="text"placeholder={translate('inputSearch','Search...')}/>);}}constcurrentLocale='en_US';constdata={en_US: {inputSearch: 'Search',},};React.render(<LocaleProvideradapter={data}locale={currentLocale}><ProvideTranslate>{translate=>(<MyComponenttranslate={translate}/>)}</T></LocaleProvider>);

The result will be

<inputtype="text" placeholder="Search" />

Namespaces

Sometimes when you are using dot notation you can stack with long paths. For example: header.navigation.button.login. You can use component named Namespace which will help you to simplify your jsx file.

importReactfrom'react';importTranslate{LocaleProvider,Namespace}from'react-translate-maker';constcurrentLocale='en_US';constdata={en_US: {header: {navigation: {title: 'MyProject',button: {login: 'Log In',signup: 'Sign Up',},},},},};React.render(<LocaleProvideradapter={data}locale={currentLocale}><Namespacepath="header.navigation"><nav><ul><li><Translatepath="button.login"/></li><li><Translatepath="button.signup"/></li></ul></nav></Namespace></LocaleProvider>);

Namespace with compose component

importReactfrom'react';importTranslate{LocaleProvider,Namespace}from'react-translate-maker';constcurrentLocale='en_US';constdata={en_US: {header: {navigation: {title: 'MyProject',button: {login: 'Log In',signup: 'Sign Up',},},},},};React.render(<LocaleProvideradapter={data}locale={currentLocale}><Namespacepath="header.navigation"><h1><Translatepath="title"/></h1><nav><Namespacepath="button"compose><ul><li><Translatepath="login"/></li><li><Translatepath="signup"/></li></ul></Namespace></nav></Namespace></LocaleProvider>);

HTML content

Sometimes you need to provide HTML content.

importReactfrom'react';import{LocaleProvider,Translate}from'react-translate-maker';constcurrentLocale='en_US';constdata={en_US: {welcome: 'Welcome back {$user}. How is it going?',},};constuser={name: 'Zlatko',};React.render(<LocaleProvideradapter={data}locale={currentLocale}><Translatepath="welcome"params={{user: <b>{user.name}</b>}}/></LocaleProvider>);

The result will be

<span>Welcome back <b>Zlatko</b>. How is it going?</span>

Locale switch

We are providing a component for the locale switch. It is a select with everything what do you need. You can use it in two ways. Here is first example.

importReact,{Component}from'react';importTranslate{LocaleProvider,LocaleSwitch}from'react-translate-maker';constdata={en_US: {language: 'Language',button: {login: 'Log In',signup: 'Sign Up',},},sk_SK: {language: 'Jazyk',button: {login: 'Prihlasit sa',signup: 'Odhlasit sa',},},};constlocales=[{label: 'English',value: 'en_US',},{label: 'Slovenčina',value: 'sk_SK',}];constDEFAULT_LOCALE='en_US';classAppextendsComponent{constructor(props,context){super(props,context);this.state={locale: DEFAULT_LOCALE,};}handleLocaleChange(locale){this.setState({locale: locale,});}render(){const{ data, locales }=this.props;constcurrentLocale=this.state.locale;return(<LocaleProvideradapter={data}locale={currentLocale}><nav><ul><li><Translatepath="button.login"/></li><li><Translatepath="button.signup"/></li><li><Translatepath="language"/><LocaleSwitchlocales={locales}onChange={this.handleLocaleChange.bind(this)}/></li></ul></nav></LocaleProvider>);}}React.render(<Appdata={data}locales={locales}/>);

As you can see in previous example. We are using onChange event. The main reason for that is that LocaleProvider is a controlled component. That means if you wanted to change property named locale of the LocaleProvider you need to change it directly in the render function.

If you want to use LocaleProvider as uncontrolled component you can do that. But all properties of the LocaleProvider will be used only as initialisation properties. Here is a second example (please take a loon on the property named controlled of the LocaleProvider).

importReact,{Component}from'react';importTranslate{LocaleProvider,LocaleSwitch}from'react-translate-maker';constdata={en_US: {language: 'Language',button: {login: 'Log In',signup: 'Sign Up',},},sk_SK: {language: 'Jazyk',button: {login: 'Prihlasit sa',signup: 'Odhlasit sa',},},};constlocales=[{label: 'English',value: 'en_US',},{label: 'Slovenčina',value: 'sk_SK',}];constDEFAULT_LOCALE='en_US';classAppextendsComponent{render(){const{ data, locales }=this.props;constcurrentLocale=this.state.locale;return(<LocaleProvideradapter={data}locale={DEFAULT_LOCALE}controlled={false}><nav><ul><li><Translatepath="button.login"/></li><li><Translatepath="button.signup"/></li><li><Translatepath="language"/><LocaleSwitchlocales={locales}/></li></ul></nav></LocaleProvider>);}}React.render(<Appdata={data}locales={locales}/>);

The main difference is that you are not able to change locale of the LocaleProvider with property named locale after first render.

Properties of the LocaleSwitch

• onChange (function): Callback witch a new locale (immediate change)
• onLocaleChange (function): Callback witch a new locale (after success change)
• setLocale (Boolean): It will set locale automatically in the translate-maker after change (default: true)
• locales (array): Array of the available locales. [{ label: 'English', value: 'en_US' }]
• all properties of the standard select component

Filters

Sometimes you need to provide HTML content.

importReactfrom'react';importTranslate,{LocaleProvider}from'react-translate-maker';constcurrentLocale='en_US';constdata={en_US: {welcome: 'Welcome {$user.name | star}',},};constfilters={star: functionstar(value){return'*** '+value+' ***';},};constuser={name: 'Zlatko',};React.render(<LocaleProvideradapter={data}locale={currentLocale}filters={filters}><Translatepath="welcome"user={user}/></LocaleProvider>);

The result will be

<span>Welcome *** Zlatko ***</span>

Options of Locale Provider

• locale (String): Current locale ID (default null)
• locales (Array): List of available locales IDs (default null)
• cache (Instance of Cache): Cache of the translations (default MemoryCache)
• adapter (Instance of Adapter | data): Adapter provides translations (default see option defaultAdapter)
• defaultAdapter (Class of Adapter): Default adapter (default MemoryAdapter)
• dotNotation (Boolean): You can turn of dot notation. This is useful if you are using PO translation files (default true)
• mode (Enum): You can use full compatible ICU version with Mode.ICU. After that you can use external variables witout dolar character (Default Mode.MAIN)
• references (Boolean): You can turn on/off references. (Default true)
• variables (Boolean): You can turn on/off variables. (Default true)
• combinations (Boolean): You can turn on/off combinations. (Default true)
• defaultValue (Function): What you will see for missing translations (Default (path, attrs) => Missing default translation for: ${path})
• filters (Object): Object with custom filters
• controlled (Boolean): You can set component as uncontrolled (default true). More information.

More examples

Please take a look on translate-maker

Roadmap

• Locales property of the LocaleSwitch can be an object
• Locales property of the LocaleSwitch can be autopopulated from the adapter
• Locales property of the LocaleSwitch can be translated automatically by translate-maker

Support us

Star this project on GitHub.

Running Tests

To run the test suite, first invoke the following command within the repo, installing the development dependencies:

npm install

Then run the tests:

npm test