ReactJS Localization v0.2

Remember my [[A different approach for localizing ReactJS app|last post]] about React.js localization? Not 2 years passed yet and I’m happy to share with you the “proper” way to do localization in React.js.

# Globalize.js

Yes, I still use [globalize](https://github.com/globalizejs/globalize). As I said in my previous post, the Common Locale Data Repository is maintained by Unicode Consortium and have support for every possible locale. Please don’t re-invent the wheel. Languages are hard (believe me, I know Russian) and I’ve seen a lot of people trying to do their own localization and plurals. Kudos to them, its a valuable experience to get, but when you are doing a professional web site, you want to use proper plurals.

But while CLDR is only data (usually JSON, but if you are old and nostalgic you can get it in XML format), globalize is the tool. You feed globalize with data and it gives you way to produce shiny localized numbers or dates. Globalize API is very extensive and **modular**, the core library is only 1KB minified + gzipped and you can add other modules depending on your needs.

# Getting CLDR

The way you get CLDR did not change from my previous post. I still think it should be part of your build step. The only difference is that I no longer use [cldr-data-downloader](https://www.npmjs.com/package/cldr-data-downloader) since it is limited in the way it downloads the CLDR. Instead I use the combination of gulp-download and gulp-decompress as well as a custom mapping JSON file to map the different packages and versions of CLDR.

What I do recommend you pay attention to, is that CLDR package is split into two “modules”: **Locale** files and **Supplemental** files. It is important that you do not ship everything as one json file. Supplemental data is shared across all locales, so if a user switches between different locales, he will use the same supplemental file, but different locale file. This will allow the browser to cache the supplemental.json file if it was already requested once. So while you package your cldr, split it into at least 2 files: `{locale}.json` and `supplemental.json`, where `{locale}` is being the locale you are shipping.

Here are the 2 gulp tasks that I use to create `supplemental.json` and `{locale}.json` for the locales I support:

```js
gulp.task('cldr:bundle:supplemental', ['cldr:bundle:clean'], function () {
    return gulp
        .src(CLDRConfig.files.supplemental.map(function (f) {
            return path.join(CLDR_SOURCE_PATH, 'supplemental', f);
        }))
        .pipe(extend('supplemental.json'))
        .pipe(gulp.dest(CLDR_DEST_PATH));
});

gulp.task('cldr:bundle:locale', ['cldr:bundle:clean'], function () {
    const streams = Config.i18n.locales.map(function (locale) {
        return gulp
            .src(CLDRConfig.files.locale.map(function (f) {
                return path.join(CLDR_SOURCE_PATH, 'main', locale, f);
            }))
            .pipe(extend(locale + '.json'))
            .pipe(gulp.dest(CLDR_DEST_PATH));
    });

    return merge(streams);
});
```

# Localization

Now that you have your CLDR ready, you can start with the actual localization.

The main and the most important file is the GlobalizeProvider:

```jsx
import React from "react";
import PropTypes from "prop-types";
import Globalize from "globalize";

export default function provide(locale, supplemental, data) {

    Globalize.load(supplemental);
    Globalize.load(data);
    const globalize = new Globalize(locale);

    const GlobalizeProvider = class extends React.Component {

        static childContextTypes = {
            globalize: PropTypes.object
        };

        getChildContext() {
            return {
                globalize: globalize
            };
        }

        render() {
            return this.props.children;
        }

    };

    return GlobalizeProvider;

}
```

locale — is the actual locale name (e.g. “en”, “ru” etc), supplemental — is the content of supplemental.json and data is the content of `{locale}.json`.

You can theoretically load ALL locale data you will ever support, but its a huge huge huge waste. Locale is not something that users change every 5 minutes, so if I prefer an **en_US** version of you website, most likely Ill never switch to **ru** or **en_GB**, and even if I will switch, I’m ok with you reloading the website and loading the locale data again.

So we have the GlobalizeProvider. It uses context to pass the globalize instance (you can read about context in [[The land of undocumented ReactJS - The Context|one of my posts]]). We will need one more Container component that handles the locale loading based on any strategy you want (guess it from the browser, headers, make the user select; whatever, I prefer to start with en_US and let the user select). Here is a snippet of my RootContainer component that handles the locale loading (I’m using redux here):

```jsx
import React from "react";
import {connect} from "react-redux";
import {BrowserRouter as Router, Route, Switch} from "react-router-dom";

import {Actions as LocaleActions} from "../actions/locale";

import GlobalizeProvider from "../globalize/Provider";

import ErrorComponent from "../components/Display/Error";
import LoadingComponent from "../components/Display/Loading";

import "../../styles/style.sass"

class Root extends React.Component {

    componentWillMount() {
        const {dispatch, locale} = this.props;

        if (locale.supplemental === null) {
            dispatch(LocaleActions.loadSupplemental());
        }

        if (locale.data === null) {
            dispatch(LocaleActions.loadLocale(locale.locale));
        }
    }

    render() {
        const {locale} = this.props;

        if (locale.error) {
            return <ErrorComponent>Failed to load locale data</ErrorComponent>;
        }

        if ((locale.supplemental === null) || (locale.data === null)) {
            return <LoadingComponent/>;
        }

        let GlobalizeProviderContainer = GlobalizeProvider(locale.locale, locale.supplemental, locale.data);

        return (
            <GlobalizeProviderContainer>
                <Router>
                    <div>
                        <SignNDAtoViewThisComponent/>
                    </div>
                </Router>
            </GlobalizeProviderContainer>
        );
    }

}

const select = state => {
    return {
        locale: state.locale
    }
};

export default connect(select)(Root);
```

And now we have GlobalizeProviderContainer that wraps our whole application, and since it uses context we can pass initialized globalize instance to every leaf component.

# Localized Leaf Components

The only thing left is to implement Localized leaf components.

Here is an example for DateTime component to display date & time in given format:

```jsx
import React from "react";
import PropTypes from "prop-types";

export default class DateTime extends React.Component {

    static propTypes = {
        date: PropTypes.instanceOf(Date).isRequired,
        format: PropTypes.string.isRequired
    };

    static contextTypes = {globalize: PropTypes.object.isRequired};

    static _formatters = {};

    static getFormatter(format, globalize) {
        if (!(format in DateTime._formatters)) {
            DateTime._formatters[format] = globalize.dateFormatter({skeleton: format});
        }
        return DateTime._formatters[format];
    }


    render() {
        const formatter = DateTime.getFormatter(this.props.format, this.context.globalize),
            formattedDate = formatter(this.props.date);

        return <span className="component localized datetime">{formattedDate}</span>
    }

}
```

Notice the *static contextTypes* declaration. This is what gives us access to the globalize instance provided from GlobalizeProviderContainer (for more info read my [[The land of undocumented ReactJS - The Context|context posts]]).

Inside the Localized component, you use pure globalize API to access the different formatting methods.

You can even query the CLDR itself for data. Take a look at Currency component below:

```jsx
import React from "react";
import PropTypes from "prop-types";

import Currencies from "../../../../data/currencies.json";

export default class Currency extends React.Component {

    static contextTypes = {globalize: PropTypes.object.isRequired};
    static propTypes = {
        display: PropTypes.oneOf(['name', 'symbol']),
        currency: PropTypes.oneOf(Currencies).isRequired
    };
    static defaultProps = {display: 'name'};

    render() {
        switch (this.props.display) {
            case 'name':
                return <span
                    className="component currency name">{this.context.globalize.cldr.main(`numbers/currencies/${this.props.currency}/displayName`)}</span>;
                break;

            case 'symbol':
                return <span className="component currency symbol">{this.props.currency}</span>;
                break;

            default:
                return null;
        }
    }

}
```

This component, when rendered like this:

```jsx
<Currency currency="USD" display="symbol"/>
```

Will produce:

```html
<span class="component currency symbol">USD</span>
```

But when rendered like this

```jsx
<Currency currency="USD" display="name"/>
```

Will produce

```html
<span class="component currency name">US Dollar</span>
```

For *en_US* locale, and for the *ru* locale it will produce

```html
<span class="component currency name">Доллар США</span>
```

You can now go on and implement as much Localized Leaf components as you wish, depending on your needs. I have Country and Currency Selects that are entirely localized, Date Picker that is based entirely on CLDR and Globalize (as opposed to a lot of date pickers that use internal localization files) and etc.

Hope this helped you to become a better React.js developer. Best of luck :)

In my last post I've discussed ReactJS localization. Now lets find the proper way to do localization.

React.JS Localization v0.2

The land of undocumented ReactJS - The Context


*Русская версия на* [*Хабре*](http://habrahabr.ru/post/266407/)*. Перевод не мой, спасибо* [*webMarshal*](http://habrahabr.ru/users/webMarshal/)*-у за перевод.*

If you have any questions, or want to discuss some points — leave a comment here, or [tweet](https://twitter.com/skwee357) me.

If we take a look at React component we can outline some properties.

# State

Yes, each react component has state. State is something internal to the component. Only the component it self can read and write into its own state and as the name implies, the state of the component is used to store state (captain obvious here). Not interesting. Let’s move next.

# Props

Or shall we say properties. Props is the data that affects the component display and behavior. Props can be optional or mandatory, and they are provided by the **parent** component. Ideally, when you provide your component with the same props — it renders the same. Not interesting as well. Let’s move on.

# Context

Meet context, the reason I’m writing this post. Context is an undocumented feature of react.js and it is similar in a way to props, but the only difference is that props are passed explicitly by parent to child, and they do not propagate down the hierarchy, while context can be requested by children component implicitly.

## But why?

Good question. Lets draw!

![React state props tree#363x313](/images/react-state-props-tree.png)

We have a Grandparent component that renders Parent A component that renders two child components: Child A and Child B.

Lets say Grandparent component knows something that Child A and Child B wants to know as well, but Parent A doesn’t care about. Lets call this piece of data *Xdata.* How would Grandparent component give ChildA and ChildB access to *Xdata*?

Well, using Flux architecture we can store *Xdata* inside a store and let Grandparent, Child A and Child B subscribe to that store. But what if we want Child A and Child B to be *pure dumb components* that only renders some markup?

Well, we than can pass *Xdata* as prop to Child A and Child B. But Grandparent can not pass props to its grand children without going through Parent. And its not that big deal if we have only 3 level nesting, but real applications have a lot more nesting levels where top components acts as containers and leaf components are just markup. Well, we can use mixins that will automatically pass the props down the hierarchy for us, but its not elegant.

Or we can use context. As I said earlier, context allows children component to request some data to arrive from component that is located higher in the hierarchy.

Here is how it looks:

```js
var Grandparent = React.createClass({  
  childContextTypes: {
    name: React.PropTypes.string.isRequired
  },  getChildContext: function() {
    return {name: 'Jim'};
  },
  
  render: function() {
    return <Parent/>;
  }
    
});

var Parent = React.createClass({
 render: function() {
   return <Child/>;
 }
});

var Child = React.createClass({
 contextTypes: {
   name: React.PropTypes.string.isRequired
 }, render: function() {
  return <div>My name is {this.context.name}</div>;
 }
});

React.render(<Grandparent/>, document.body);
```

And here is a [JSBin with the code](https://jsbin.com/yajobivuze/edit?js,output). Change *Jim* to *Jack* and you see how your component re-renders.

## WHAT IS HAPPENING?!

Our Grandparent component says two things:

1. *I provide my children with context type named name of type string.* This is what happening in *childContextTypes* declaration.
2. *The value of context type named name is Jim.* This is what happening in *getChildContext* function.

And our child component just says “Hey I expect to have context type named *name*!” and it gets it. As far as I understand (and I’m far from being expert in react.js internals) when react renders children components it checks which components want to have context and those that want context are provided with context if parent supplies them.

## Cool!

Yep, expect when you encounter the following error

```
Warning: Failed Context Types: Required context `name` was not specified in `Child`. Check the render method of `Parent`.
runner-3.34.3.min.js:1

Warning: owner-based and parent-based contexts differ (values: `undefined` vs `Jim`) for key (name) while mounting Child (see: http://fb.me/react-context-by-parent)
```

Yes of course I checked the link, its not very helpful.

Here is the code that causes this ([JSBin](https://jsbin.com/doqeyasako/edit?js,output)):

```jsx
var App = React.createClass({
  render: function() {
    return (
      <Grandparent>
        <Parent>
          <Child/>
        </Parent>
      </Grandparent>
    );
  }
});

var Grandparent = React.createClass({  
  childContextTypes: {
    name: React.PropTypes.string.isRequired
  },  getChildContext: function() {
    return {name: 'Jim'};
  },
  
  render: function() {
    return this.props.children;
  }
    
});

var Parent = React.createClass({
  render: function() {
    return this.props.children;
  }
});

var Child = React.createClass({
  contextTypes: {
    name: React.PropTypes.string.isRequired
  },  render: function() {
    return <div>My name is {this.context.name}</div>;
  }
});

React.render(<App/>, document.body);
```

*It doesn’t make sense now, but Ill explain a setup where this is a viable hierarchy in the end of this post.*

So what is happening?

It took me a lot of time to understand why this happens. Googling the error only brought me to discussions by people who also wonders why this happens. I looked at other projects like react-router or react-redux that uses context to pass data down the component tree, when eventually I realized what is wrong.

*Note: I said I’m not expert in react internals, so everything I’m going to say now is purely what I understood about react internals. Leave a comment if you think I’m wrong (preferably with a link that backups your comment).*

Remember I said that each react component have *state*, *props* and *context*? Well, each component have as well so called *parent* and *owner*. And if we follow the link from the earlier warning (so yes, it is useful, I lied) we can understand that:

> In short, the owner of a component is whomever creates the component, while the parent of a component is whomever would be the containing ancestor in the DOM hierarchy.

It took me some time to understand this statement.

So in my first example, the owner of Child component is Parent, as well as the parent of Child is Parent. While in the second example the owner of Child component is App while the parent is Parent.

Context is something that propagates in a strange way to all the descendant components, but will be assigned only to those components who explicitly asked for context. But context does not propagate from the parent component as you’d expect but from owner! And since the owner of Child is App, React tries to find the “name” attribute in context of App instead of Parent or Grandparent.

[Here is the relevant bug report in React](https://github.com/facebook/react/issues/2112). And here is the relevant [pull request](https://github.com/facebook/react/pull/3615) that should fix this to Parent based context as opposed to Owner based context in React 0.14.

However React 0.14 is not there yet, so here is a fix ([JSBin](https://jsbin.com/yujihowuwe/edit?js,output)):

```jsx
var App = React.createClass({
  render: function() {
    return (
      <Grandparent>
        { function() {
          return (<Parent>
            <Child/>
          </Parent>)
        }}
      </Grandparent>
    );
  }
});

var Grandparent = React.createClass({  
  childContextTypes: {
    name: React.PropTypes.string.isRequired
  },  getChildContext: function() {
    return {name: 'Jack'};
  },
  
  render: function() {
    var children = this.props.children;
    children = children();
    return children;
  }
    
});

var Parent = React.createClass({
  render: function() {
    return this.props.children;
  }
});

var Child = React.createClass({
  contextTypes: {
    name: React.PropTypes.string.isRequired
  },  render: function() {
    return <div>My name is {this.context.name}</div>;
  }
});

React.render(<App/>, document.body);
```

Instead of instancing the Parent and Child components inside App, we return a function. Then inside the Grandparent we call this function hence making Grandparent the owner of Parent and Child components. Context propagates as expected now.

# Ok, cool, but… WHY?!

Remember [[A different approach for localizing ReactJS app|my previous]] post about localization in react.js? Consider the following hierarchy:

```jsx
<Application locale="en">
  <Dashboard>
    <SalesWidget>
      <LocalizedMoney currency="USD">3133.7</LocalizedMoney>
    </SalesWidget>
  </Dashboard>
</Application>
```

*This is a static hierarchy, but usually you will have some routing and eventually you will create a situation where the owner and parent of your leaf components — differs.*

Application is responsible for loading the locale data and initializing an instance of jquery/globalize. But it doesn’t use it. You don’t localize your top level components. Localization affects usually leaf components like localized text nodes, numbers, money display or time. And I’ve discussed earlier about the 3 possible ways to pass the globalize instance down the tree. Either we store it in a store and let leaf components subscribe to the store, but I think its incorrect. Leaf components should be pure dumb components.

Passing the globalize instance as props can be tedious, imagine ALL your components requires globalize instance. Its the same as making globalize instance a global variable and let those who needs it — use it.

But the most elegant way is using context. Application components says “Hey I have a globalize instance here, anyone who needs it let me know” and any Localized leaf components yells “Me! Me! I want it!”. This is an elegant solution. Leaf components stays pure, they dont depend on stores (yes they depend on context, but they have to, because they need it to render correctly). Globalize instance is not getting passed as props to your entire hierarchy. Every body is happy.

***

That’s it my friends!

May the force be with you.


The land of undocument react.js: The Context

A different approach for localizing ReactJS app


Howdy!

I’ve heard you use ReactJS? Good! I also heard you want to localize your application? That’s great! Well proper localization is hard, there are many js libraries for client side localization as well as [yahoo/react-intl](https://github.com/yahoo/react-intl) that provides localized react components based on JavaScript Intl API.



I my self use es6 syntax and avoid using mixins, because [mixins are dead](https://medium.com/@dan_abramov/mixins-are-dead-long-live-higher-order-components-94a0d2f9e750) (and well, because there is no easy way to integrate mixins into es6 syntax). So react-intl didn’t work for me. But damn I wanted those localized numbers! In this article I’m gonna show a different (not bad neither good, just different) approach on how I did it.

## Localize all the things!!

![Localize all the things!!#400x400](/images/localize-meme.jpeg)

I do like the idea of Intl API, why reinvent the wheel when we have [51M of compressed localized data](http://www.unicode.org/Public/cldr/26/) with support for dates, numbers, currencies and messages. So we do have [jquery/globalize](https://github.com/jquery/globalize) on client side to use all this data. The question is: How do I use it in a react.js application?

Well, here is the general idea

1. We need a way to identify user locale. Either we can guess it from the browser or (a preferred method, in my opinion) let the user choose his locale.
2. Once we know the locale, we need to load the needed cldr json data (we can load everything, or just the parts we really need) into Globalize.
3. ….
4. PROFIT!!!!

Simple. Yet a bit complicated.

One thing I disliked in react-intl is that each component knew about the locale data. If you have a nested tree of: App => Dashboard => SalesWidget => FormattedMoney, even though the locale data is needed only in FormattedMoney component, its passed to all the child components of App (react-intl handled that automatically using mixins). I offer a different solution. Locale data is no more than just… data! And data should be stored inside… yes right a Store!

## Show me the code!

*Note: I use* [*alt*](https://github.com/goatslacker/alt) *as my flux implementation. Ideally my locale info should be fetched from the user, but since I do a MVP, I omitted this step.*

Application component issues a UserFetch action that goes to the API and fetches the user details. Locale store listen to UserFetchCompleted action and then gets the locale from the user, and loads the needed cldr data.

Here is how it looks

```javascript
handleSetupStarted() {
    this.waitFor(ProfileStore.dispatchToken);

    let locale = 'en', //@TODO get from profile
        self = this;
    request({url: CLDR_URL + 'supplemental.json', type: 'json'})
        .then(function (supplemental) {
            request({url: CLDR_URL + locale + '.json', type: 'json'})
                .then(function (localeData) {
                    self.handleSetupFinished(locale, supplemental, localeData);
                })
                .fail(self.handleSetupFailed);
        })
        .fail(self.handleSetupFailed);
}

handleSetupFinished(locale, supplemental, localeData) {
    Globalize.load(supplemental, localeData);
    this.setState({translator: Globalize(locale)});
}
```

(Yes, I know, I do an ajax call from the store. I couldn’t find a better way to do it. For some reason I wans’t able to dispatch an action inside the ProfileStore once the user data loaded because I got this weird message of: *Dispatch.dispatch(…): Cannot dispatch in the middle of a dispatch.* and was lazy to investigate on how to fix it. Ideally this should be inside an action or an alt term called source. I’ll figure it out later).

See, the handleSetupStarted waits for the ProfileStore to finish loading the user, and once its done, we get its locale and load 2 files: supplemental.json (which is a common set of data for every locale) and en.json (which is data related to the en locale). Once it finished loading, it creates a new instance of Globalize.

Here is an example of a LocalizedMoney component

```jsx
class Money extends React.Component {
    constructor(props) {
        super(props);
        this.state = {
            locale: LocaleStore.getState()
        }
    }

    render() {
        let amount = parseFloat(this.props.children),
            translator = this.state.locale.translator,
            cls = classNames({
                money: true,
                positive: amount >= 0,
                negative: amount < 0
            });

        return (
            <div className={cls}>
                {translator.formatCurrency(amount, this.props.currency)}
            </div>
        );
    }
}
```

And a usage example

```jsx
render() {
    return (
        <FormattedMoney currency="USD">1337.93</FormattedMoney>
    );
}
```

See! No need to pass the locale data from the Application component to the LocalizedMoney component! LocalizedMoney just uses the Locale Store. You can even setup listener on localized components, to listen to changes on the Locale store, and when the user fires a Change Locale Action, you can change the locale on the fly without reloading the page. But I wouldn’t mind reloading the page. Locale is not something you change twenty times a day.

You can as well implement caching for different formatters inside the LocaleStore as well, and instead of using the translator (which is just an instance of Globalize) directly, you can use something like

```js
LocaleStore.getCurrencyFormatter(“USD”).format(123.45);
```

Which internally looks like (pseudo code):

```js
getCurrencyFormatter(currencyCode) {
    if(!this.state.currencyFormatters[currencyCode]) {
        this.state.currencyFormatters[currencyCode] = this.state.translator.currencyFormatter(currencyCode);
    }
    return this.state.currencyFormatters[currencyCode];
}
```

*Note: formatter identified not only by currency, but by options as well. You can have two USD formatters: One that shows the number as*

```
$1,000.00
```

*And another one as*

```
1,000.00 US Dollars
```

*In short: RTFM.*

## A note about CLDR shipping

The process of shipping the locale data should be a build step of your application. There is [cldr-data-downloader](https://www.npmjs.com/package/cldr-data-downloader). Its a node module to download the CLDR data from unicode.org.

I then use gulp to bundle the supplemental (common) and locale based data into merged json file.

Less talk, more code:

```js
gulp.task('cldr:download', function (cb) {
    cldrDataDownloader('http://www.unicode.org/Public/cldr/' + CLDR_VERSION + '/json.zip', cldrPath, function (err) {
        if (err) return cb(err);
        cb();
    });
});

gulp.task('cldr:bundle:supplemental', function () {
    var files = ['likelySubtags.json', 'currencyData.json', 'numberingSystems.json', 'plurals.json', 'ordinals.json'];
    return gulp
        .src(files.map(function (f) {
            return path.join(cldrPath, 'supplemental', f);
        }))
        .pipe(extend('supplemental.json'))
        .pipe(gulp.dest(path.join(distDir, 'cldr')));
});

gulp.task('cldr:bundle:locale', function () {
    var files = ['currencies.json', 'numbers.json'];

    var tasks = locales.map(function (locale) {
        return gulp
            .src(files.map(function (f) {
                return path.join(cldrPath, 'main', locale, f);
            }))
            .pipe(extend(locale + '.json'))
            .pipe(gulp.dest(path.join(distDir, 'cldr')));
    });
    return gulpMerge(tasks);
});
```

At this point I need only currency formatting, so I use the required files in both supplemental bundle and locale bundle. [jquery/globalize](https://github.com/jquery/globalize#requirements) actually giving a nice table that shows, what json files from the cldr you need in order to use different localization modules.

## A final note

For now I am happy with this approach. In my opinion it decouples the components from the actual localization implementation. Components stays reusable even if you decide to switch to a different localization implementation. Your store can expose an API like the *getCurrencyFormatter()* I showed earlier, and actual implementation can be based on Intl, or your own. FormattedMoney component doesn’t care.

Intl API is [supported in all major browsers](http://caniuse.com/#search=Intl) and those that do not support it, can be [polyfilled](https://github.com/andyearnshaw/Intl.js/). Of course Intl API can be an overkill for most applications, especially if all you want is translating strings. But if your application requires displaying localized numbers, dates, times — I think there is no better solution other than Intl API.

Best of luck and may the force be with you.



Howdy!

I’ve heard you use ReactJS? Good! I also heard you want to localize your application? That’s great! Well proper localization is hard, there are many js libraries for client side localization as well as yahoo/react-intl that provides localized react components based on JavaScript Intl API.



React

Latest Posts

React.JS Localization v0.2

The land of undocument react.js: The Context

A different approach for localizing react.js app