react-message-source

KO | EN

gitlite — search

#python #ai #llm #golang #machine-learning #deep-learning #macos #nodejs #java #windows #awesome-list #vue #security #openai

react-message-source

(★ 15)

A lightweight library which aids internationalization of React applications

react-message-source Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# react-message-source

> A library which aids internationalization of React applications

[![NPM](https://img.shields.io/npm/v/react-message-source.svg)](https://www.npmjs.com/package/react-message-source)
[![Build Status](https://travis-ci.org/netceteragroup/react-message-source.svg?branch=master)](https://travis-ci.org/netceteragroup/react-message-source)
[![Coverage Status](https://coveralls.io/repos/github/netceteragroup/react-message-source/badge.svg?branch=master)](https://coveralls.io/github/netceteragroup/react-message-source?branch=master)

# Install

```bash
$ 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](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) and [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/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](#ComponentApi).

```js
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](#ComponentAPI) as `props`. It can be used in two ways:

##### `withMessages(Component)`
Wraps the given `Component` and passes down the [ComponentAPI](#ComponentAPI).
```js
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:
```js
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.
```js
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](#ComponentApi) as standard `prop-types` definition.

# Usage examples

#### `translations.json`
```jsx
{
  "hello.world": "Hello World",
  "app.screen.userProfile.greeting": "Welcome {0}",
  "app.screen.userProfile.greeting.parameterized": "Welcome {userName}"
}
```

#### `App.jsx`
```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`
```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`
```jsx
import React from 'react'
import { withMessages } from 'react-message-source'

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

export default withMessages(MyComponent)
```

#### `MyComponentWithHooks.jsx`
```jsx
import React from 'react'
import { useMessageSource } from 'react-message-source'

export default function MyComponent(props) {
 const { getMessage } = useMessageSource();
 return {getMessage('hello.world')}
}
```

#### `MyComponentWithIndexedParams.jsx`
```jsx
import React from 'react'
import { withMessages } from 'react-message-source'

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

export default withMessages(MyComponent)
```

#### `MyComponentWithNamedParams.jsx`
```jsx
function MyComponentWithNamedParams(props) {
  const { getMessageWithNamedParams } = props;

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

return {greeting}
}

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

## License

react-message-source

react-message-source Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

react-message-source

react-message-source Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README