Product
Introducing License Enforcement in Socket
Ensure open-source compliance with Socket’s License Enforcement Beta. Set up your License Policy and secure your software!
👉 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
...
<span>
<I18n k="example.key.1">Some sample text</I18n>
</span>
...
Unsurprisingly renders:
<span>Some sample text</span>
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.
Translations
objectTranslations 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 />
componentYour 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={s => s.translations}>
<AppRoot {...props} />
</I18nProvider>
</Provider>
withI18nProvider()
higher order componentInstead of adding node to the JSX you can wrap your root component export with a HOC:
export default withI18nProvider(s => s.translations)(YourComponent);
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 JSXThe <I18n />
component should be used, when the text in your component is static and bound to the component itself.
<p>
<I18n k="example.key.1">Default fallback text</I18n>
</p>
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 hookReact 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 = useI18n();
<Component
strongText={i18n('example.prop.strong', 'Default prop.strong text')} />
</Component>
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 ComponentIn 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 = i18n => ({
strongText: i18n('example.hoc.strong', 'Default value for HOC'),
})
const TranslatedComponent = withI18n(mapI18nToProps)(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.
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 |
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 k="example.key.1" args={['template']}>{`Default fallback text {0}`}</I18n>
</p>
// Will render
// <p>Some string with template</p>
const i18n = useI18n();
<Component
strongText={i18n('example.prop.strong', 'Default prop.strong text {0}', 'replaced value')} />
</Component>
// strongText = "prop.strong text replaced value"
For more details on usage of formatting please check the format-to-jsx
documentation page!
FAQs
React (JS) text internationalization
We found that i18n-jsx demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Product
Ensure open-source compliance with Socket’s License Enforcement Beta. Set up your License Policy and secure your software!
Product
We're launching a new set of license analysis and compliance features for analyzing, managing, and complying with licenses across a range of supported languages and ecosystems.
Product
We're excited to introduce Socket Optimize, a powerful CLI command to secure open source dependencies with tested, optimized package overrides.