Wondering what‚Äôs next for npm?Check out our public roadmap! ¬Ľ

    i18n-jsx
    TypeScript icon, indicating that this package has built-in type declarations

    2.0.5¬†‚Äʬ†Public¬†‚Äʬ†Published

    npm npm bundle size Build Status codecov dependabot badge semantic-release Commitizen friendly

    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 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.

    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={s => s.translations}>
        <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:

    export default withI18nProvider(s => s.translations)(YourComponent);

    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 k="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 = useI18n();
     
    <Component
      strongText={i18n('example.prop.strong', 'Default prop.strong text')} />
    </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 = 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.

    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 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!

    Install

    npm i i18n-jsx

    DownloadsWeekly Downloads

    1,723

    Version

    2.0.5

    License

    MIT

    Unpacked Size

    31.3 kB

    Total Files

    48

    Last publish

    Collaborators

    • avatar