i18n-jsx
👉 Take note that this package is in still early stage of development, and there might be breaking changes introduced while we are finalizing on the API
Simple React (JS) text internationalization with formatting support. Uses redux
as the source of translations data.
yarn add i18n-jsx # or with npm npm install i18n-jsx --save
Example
...<span> <I18n ="example.key.1">Some sample text</I18n></span>...
Unsurprisingly renders:
Some sample text
The text passed as a child
to I18n
component is a default fallback value, while actual translation is picked up from context via key specified with k
prop.
Providing the translations
Translations
object
Translations object is a simple dictionary style object that should contain all your internationalized strings. You can use aether string
or a number
as a key to identify the translation, and values can be templates string using {0..}
as placeholders.
All translations are stored in the Redux Store. Your application has to be wrapped with react-redux
<Provider />
component, and the I18nProvider
has to nested underneath it.
<I18nProvider />
component
Your app should we wrapped at the root level, under the redux store provider, and you have to pass selector function for the store.
// store: {// user: {// name: 'John'// },// translations: {// 1: 'Some translation'// }// } <Provider store=store> <I18nProvider selector= stranslations> <AppRoot ...props /> </I18nProvider></Provider>
withI18nProvider()
higher order component
Instead of adding node to the JSX you can wrap your root component export with a HOC:
stranslationsYourComponent;
Accessing the translations
There are 3 main use cases / scenarios that this library supports - accessing them directly in JSX, using a function to obtain the value and a Higher Order Component to bind translations to props of a component. We will explain each usage with an example:
<I18n />
directly in JSX
The <I18n />
component should be used, when the text in your component is static and bound to the component itself.
<p> <I18n ="example.key.1">Default fallback text</I18n></p>
API
prop | type | required | defaultValue | Description |
---|---|---|---|---|
k |
string \| number |
true | - | key value used to look up the translation in the Translations object. |
children |
string |
true | - | The default fallback value to render in case when value under the k key has not been found |
args |
(string \| number)[] |
false | null | Set of arguments to be used for string formatting with the template. Please see Formatting for more details |
useI18n()
react hook
React hook useI18n()
can be used to access a selector function in a scope of a component, to obtain translations values and reuse them for some calculations / building the composition props. Typical scenario would be getting the value to be passed down as a non JSX prop into some component that takes content/translations as dynamic.
const i18n = ; <Component = /></Component>
API
param | type | required | defaultValue | Description |
---|---|---|---|---|
k |
string \| number |
true | - | key value used to look up the translation in the Translations object. |
notFound |
string |
true | - | The default fallback value to render in case when value under the k key has not been found |
...args |
(string \| number)[] |
false | null | Set of arguments to be used for string formatting with the template. Please see Formatting for more details |
withI18n()
Higher Order Component
In case you would like to bind components props to some internationalized content (in a similar way as you would bind a component to a data provided by a redux store) you can use a withI18n()
HOC to export a component as internationalized.
const mapI18nToProps = strongText: const TranslatedComponent = Component
mapI18nToProps
is a selector function, similar to react-redux
mapStateToProps
that allows you to access i18n
selector function and map your translations to component props.
API
hoc
:
param | type | required | defaultValue | Description |
---|---|---|---|---|
component |
React.ComponentType |
true | - | An react component that we want to bind internationalized props to. |
mapI18nToProps |
(i18n: I18nSelector) => TranslatedProps) |
true | - | Selector function to be called when mapping translations to props. |
i18n
selector:
param | type | required | defaultValue | Description |
---|---|---|---|---|
k |
string \| number |
true | - | key value used to look up the translation in the Translations object. |
notFound |
string |
true | - | The default fallback value to render in case when value under the k key has not been found |
...args |
(string \| number)[] |
false | null | Set of arguments to be used for string formatting with the template. Please see Formatting for more details |
Formatting
All translations accessing functions / components support formatting via format-to-jsx
. The formatting params for the template can be passed either by args when using selector from react hook / Higher Order Component, or with a args prop:
/// example.key.1 = "Some string with {0}"<p> <I18n ="example.key.1" =>`Default fallback text {0}`</I18n></p> // Will render// <p>Some string with template</p>
const i18n = ; <Component = /></Component> // strongText = "prop.strong text replaced value"
For more details on usage of formatting please check the format-to-jsx
documentation page!