React-message-source NPM

react-message-source

A library which aids internationalization of React applications

Install

$ npm install --save react-message-source
or
$ yarn add react-message-source

API

`Provider`

A <Provider /> component which purpose is to provide the translations down the component tree.

`value: { [key: string]: string }`

Sets the current translations.

`FetchingProvider`

A special <Provider /> which can load translations from remote URL via a GET request and pass them down the component tree.

Note: This Provider requires fetch and Promise APIs to be available on the global object in order to work properly. If you use this library in an older browser environment, please include the required polyfills.

`url: string`

An URL where text translations can be found. Whenever this prop changes, a new GET /props.url call will be made.

`blocking?: boolean`

Controls the rendering flow. When set to true it blocks the rendering of the component subtree until translations fetching is complete. When omitted, it defaults to true.

`transform?: (response: any) => { [key: string]: string }`

Applies a transform on the response received when GET /props.url finished. It comes handy in situation when the given url doesn't return translations in the expected format.

`onFetchingStart?: () => void`

An optional fetching lifecycle method. Invoked just before GET /props.url is executed.

`onFetchingEnd?: () => void`

An optional fetching lifecycle method. Invoked just after GET /props.url response is received.

`onFetchingError?: (e?: Error) => void`

An optional fetching lifecycle method. Invoked when error occurs during fetching/processing stage.

`useMessageSource`

`useMessageSource(keyPrefix?: string): ComponentAPI`

A React Hook version of the ComponentAPI.

import React from 'react'
import { useMessageSource } from 'react-message-source'

function MyComponent() {
  const { getMessage, getMessageWithNamedParams } = useMessageSource()
  return ...
}

`withMessages`

Creates a higher order component and provides the ComponentAPI as props. It can be used in two ways:

`withMessages(Component)`

Wraps the given Component and passes down the ComponentAPI.

export default withMessages(MyComponent)

`withMessages(keyPrefix?: string)(Component)`

Similar like the example above, but in a curried format. Useful when decorating a Component with many higher order components:

export default compose(
  connect(mapStateToProps, mapDispatchToProps),
  withRouter,
  withMessages,
)(MyComponent)

Additionally, the curried form of withMessages accepts an optional keyPefix which will be prepended before any translation lookup key (see the examples below). This feature comes quite useful when i18n-ing scoped presentational components.

export default compose(
  connect(mapStateToProps, mapDispatchToProps),
  withRouter,
  withMessages('app.screens.userProfile'), // scoped lookup
)(MyComponent)

// alternatively
export default withMessages('app.screens.userProfile')(MyComponent)

`ComponentAPI`

The ComponentAPI represent the props that a wrapped Component will receive once rendered in the tree.

`getMessage = (key: string, ...params?: Array<*>) => string`

Will retrieve a translation message specified by the given key with all indexed placeholders replaced according to the values given in the params array. See the examples below for more information.

`getMessageWithNamedParams = (key: string, namedParams?: { [key: string]: any }) => string`

Will retrieve a translation message specified by the given key with all named placeholders replaced according to the entries given in the namedParams object. See the examples below for more information.

`propTypes`

Exposes the ComponentAPI as standard prop-types definition.

Usage examples

`translations.json`

{
  "hello.world": "Hello World",
  "app.screen.userProfile.greeting": "Welcome {0}",
  "app.screen.userProfile.greeting.parameterized": "Welcome {userName}"
}

`App.jsx`

import React, { Component } from 'react'
import { Provider as MessageSourceProvider } from 'react-message-source'

import translations from './translations.json'

import MyComponent from './MyComponent'
import MyComponentWithIndexedParams from './MyComponentWithIndexedParams'
import MyComponentWithNamedParams from './MyComponentWithNamedParams'

export default function App() {
  return (
    <MessageSourceProvider value={translations}>
      <MyComponent />
      <MyComponentWithHooks />
      <MyComponentWithIndexedParams />
      <MyComponentWithNamedParams />
    </MessageSourceProvider>
  )
}

`FetchApp.jsx`

import React, { Component } from 'react'
import { FetchingProvider as FetchingMessageSourceProvider } from 'react-message-source'

import MyComponent from './MyComponent'
import MyComponentWithIndexedParams from './MyComponentWithIndexedParams'
import MyComponentWithNamedParams from './MyComponentWithNamedParams'

export default function FetchApp() {
  return (
    <FetchingMessageSourceProvider url="http://api.myapp.com/intl?lang=en">
      <MyComponent />
      <MyComponentWithHooks />
      <MyComponentWithIndexedParams />
      <MyComponentWithNamedParams />
    </FetchingMessageSourceProvider>
  )
}

`MyComponent.jsx`

import React from 'react'
import { withMessages } from 'react-message-source'

function MyComponent(props) {
  const { getMessage } = props;
  return <span>{getMessage('hello.world')}</span>
}

export default withMessages(MyComponent)

`MyComponentWithHooks.jsx`

import React from 'react'
import { useMessageSource } from 'react-message-source'

export default function MyComponent(props) {
  const { getMessage } = useMessageSource();
  return <span>{getMessage('hello.world')}</span>
}

`MyComponentWithIndexedParams.jsx`

import React from 'react'
import { withMessages } from 'react-message-source'

function MyComponent(props) {
  const { getMessage } = props;
  return <span>{getMessage('app.screen.userProfile.greeting', 'John Doe')}</span>
}

export default withMessages(MyComponent)

`MyComponentWithNamedParams.jsx`

function MyComponentWithNamedParams(props) {
  const { getMessageWithNamedParams } = props;

  // 'app.screen.userProfile' prefix is implicit here
  const greeting = getMessageWithNamedParams('greeting.parameterized', {
    userName: 'John Doe',
  })

  return <span>{greeting}</span>
}

export default compose(
  withMessages('app.screen.userProfile'), // scoped keys
)(MyComponentWithNamedParams)