Skip to content

Commit 0fe60da

Browse files
oliverlazoliverlaz
committed
revamping of the basic documentation
1 parent c2df78f commit 0fe60da

File tree

1 file changed

+144
-33
lines changed

1 file changed

+144
-33
lines changed

‎README.md‎

Lines changed: 144 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -5,25 +5,140 @@
55
[![NPM](https://img.shields.io/npm/v/react-message-source.svg)](https://www.npmjs.com/package/react-message-source)
66
[![Build Status](https://travis-ci.org/netceteragroup/react-message-source.svg?branch=master)](https://travis-ci.org/netceteragroup/react-message-source)
77

8-
## Install
8+
# Install
99

1010
```bash
1111
$ npm install --save react-message-source
1212
or
1313
$ yarn add react-message-source
1414
```
1515

16-
## Usage examples
16+
# API
17+
## `Provider`
18+
A `<Proivider />` component which purpose is to provide the translations down the component tree.
1719

20+
##### `value: { [key: string]: string }`
21+
Sets the current translations.
22+
23+
## `FetchingProvider`
24+
A special `<Provider />` which can load translations from remote URL via a `GET` request and pass them down the component tree.
25+
26+
_**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._
27+
28+
##### `url: string`
29+
An URL where text translations can be found. Whenever this prop changes, a new `GET /props.url` call will be made.
30+
31+
##### `blocking?: boolean`
32+
Controls the rendering flow. When set to `true` it blocks the rendering of the component subtree until translations fetching is complete.
33+
When omitted, it defaults to `true`.
34+
35+
##### `transform?: (response: any) => { [key: string]: string }`
36+
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.
37+
38+
##### `onFetchingStart?: () => void`
39+
An optional fetching lifecycle method. Invoked just before `GET /props.url` is executed.
40+
41+
##### `onFetchingEnd?: () => void`
42+
An optional fetching lifecycle method. Invoked just after `GET /props.url` response is received.
43+
44+
##### `onFetchingError?: (e?: Error) => void`
45+
An optional fetching lifecycle method. Invoked when error occurs during fetching/processing stage.
46+
47+
## `withMessages`
48+
Creates a higher order component and provides the [ComponentAPI](#ComponentAPI) as `props`. It can be used in two ways:
49+
50+
##### `withMessages(Component)`
51+
Wraps the given `Component` and passes down the [ComponentAPI](#ComponentAPI).
52+
53+
##### `withMessages(keyPrefix?: string)(Component)`
54+
Similar like the example above, but in a curried format. Useful when decorating a `Component` with many higher order components:
55+
```js
56+
compose(
57+
connect(mapStateToProps, mapDispatchToProps),
58+
withRouter,
59+
withMessages,
60+
)(Component)
61+
```
62+
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.
63+
64+
```js
65+
compose(
66+
connect(mapStateToProps, mapDispatchToProps),
67+
withRouter,
68+
withMessages('app.screens.userProfile'), // scoped lookup
69+
)(Component)
70+
```
71+
72+
## `ComponentAPI`
73+
The `ComponentAPI` represent the `props` that a wrapped `Component` will receive once rendered in the tree.
74+
75+
##### `getMessage = (key: string, ...params?: Array<*>) => string`
76+
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.
77+
78+
##### `getMessageWithNamedParams = (key: string, namedParams?: { [key: string]: any }) => string`
79+
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.
80+
81+
## `propTypes`
82+
Exposes the [ComponentAPI](#ComponentApi) as standard `prop-types` definition.
83+
84+
85+
# Usage examples
86+
87+
#### `translations.json`
1888
```jsx
19-
// translations.json
2089
{
2190
"hello.world": "Hello World",
22-
"userProfile.greeting": "Welcome {0}",
23-
"userProfile.greeting.parameterized": "Welcome {userName}"
91+
"app.screen.userProfile.greeting": "Welcome {0}",
92+
"app.screen.userProfile.greeting.parameterized": "Welcome {userName}"
93+
}
94+
```
95+
96+
#### `App.jsx`
97+
```jsx
98+
import React, { Component } from 'react'
99+
import * as MessageSource from 'react-message-source'
100+
101+
import translations from './translations.json'
102+
103+
import MyComponent from './MyComponent'
104+
import MyComponentWithIndexedParams from './MyComponentWithIndexedParams'
105+
import MyComponentWithNamedParams from './MyComponentWithNamedParams'
106+
107+
export default function App() {
108+
return (
109+
<MessageSource.Provider value={translations}>
110+
<MyComponent />
111+
<MyComponentWithIndexedParams />
112+
<MyComponentWithNamedParams />
113+
</MessageSource.Provider>
114+
)
24115
}
116+
```
117+
118+
#### `FetchApp.jsx`
119+
```jsx
120+
import React, { Component } from 'react'
121+
import * as MessageSource from 'react-message-source'
25122

26-
// in MyComponent.jsx
123+
import translations from './translations.json'
124+
125+
import MyComponent from './MyComponent'
126+
import MyComponentWithIndexedParams from './MyComponentWithIndexedParams'
127+
import MyComponentWithNamedParams from './MyComponentWithNamedParams'
128+
129+
export default function FetchApp() {
130+
return (
131+
<MessageSource.FetchingProvider url="http://api.myapp.com/intl?lang=en">
132+
<MyComponent />
133+
<MyComponentWithIndexedParams />
134+
<MyComponentWithNamedParams />
135+
</MessageSource.FetchingProvider>
136+
)
137+
}
138+
```
139+
140+
#### `MyComponent.jsx`
141+
```jsx
27142
import React from 'react'
28143
import { withMessages } from 'react-message-source'
29144

@@ -32,44 +147,40 @@ function MyComponent(props) {
32147
return <span>{getMessage('hello.world')}</span>
33148
}
34149

35-
// the standard scenario
36150
export default withMessages(MyComponent)
151+
```
152+
153+
#### `MyComponentWithIndexedParams.jsx`
154+
```jsx
155+
import React from 'react'
156+
import { withMessages } from 'react-message-source'
37157

38-
// in MyOtherComponent.jsx
39-
function MyOtherComponent(props) {
158+
function MyComponent(props) {
159+
const { getMessage } = props;
160+
return <span>{getMessage('app.screen.userProfile.greeting', 'John Doe')}</span>
161+
}
162+
163+
export default withMessages(MyComponent)
164+
```
165+
166+
#### `MyComponentWithNamedParams.jsx`
167+
```jsx
168+
function MyComponentWithNamedParams(props) {
40169
const { getMessageWithNamedParams } = props;
41-
// 'userProfile' prefix is implicit -> actual text lookup key is 'userProfile.greeting.parameterized'
170+
171+
// 'app.screen.userProfile' prefix is implicit here
42172
const greeting = getMessageWithNamedParams('greeting.parameterized', {
43173
userName: 'John Doe',
44174
})
175+
45176
return <span>{greeting}</span>
46177
}
47178

48-
// sometimes you might like to scope the text keys and avoid repeating the common key segments
49-
// in that case, you can use the curried version
50179
export default compose(
51-
withMessages('userProfile'),
52-
)(MyOtherComponent)
53-
54-
// in App.jsx
55-
import React, { Component } from 'react'
56-
import * as MessageSource from 'react-message-source'
57-
58-
import translations from './translations.json'
59-
60-
import MyComponent from './MyComponent'
61-
import MyOtherComponent from './MyOtherComponent'
62-
63-
export default function App() {
64-
return (
65-
<MessageSource.Provider value={translations}>
66-
<MyComponent />
67-
<MyOtherComponent />
68-
</MessageSource.Provider>
69-
)
70-
}
71-
180+
withMessages('app.screen.userProfile'), // scoped keys
181+
)(MyComponentWithNamedParams)
72182
```
183+
73184
## License
74185

75186
MIT © [Netcetera AG](https://github.com/netceteragroup)

0 commit comments

Comments
 (0)