Skip to main content

@gasket/react-intl

React component library to enable localization for Gasket apps. Loads and manages locale files from @gasket/plugin-intl.

Installation​

npm i @gasket/react-intl

Components​

withMessagesProvider​

Use this to wrap a component to provide messages through context and/or set up an intl provider such as react-intl.

Signature

  • withMessagesProvider(intlManager, options?)(Component)

Props

  • intlManager - (object) An instance of the intl manager created by @gasket/plugin-intl.
  • [options] - (object) Optional configuration

Example PageRouter with react-intl​

// pages/_app.js
import { useRouter } from 'next/router';
import { IntlProvider } from 'react-intl';
import { withMessagesProvider } from '@gasket/react-intl';
import intlManager from '../path/to/intl.js';

const IntlMessagesProvider = withMessagesProvider(intlManager)(IntlProvider);

export default function App({ Component, pageProps }) {
  const router = useRouter();
  
  return (
    <IntlMessagesProvider locale={router.locale}>
      <Component {...pageProps} />
    </IntlMessagesProvider>
  );
}

Example with custom provider​

You can wrap any intl provider, passing the messages and locale as props.

import { withMessagesProvider } from '@gasket/react-intl';
import intlManager from '../path/to/intl.js';

const IntlMessagesProvider = withMessagesProvider(intlManager)(
  function CustomWrapper({ locale, messages, children }) {
    return <CustomIntlProvider messages={messages} locale={locale}>
        {children}
      </CustomIntlProvider>
  }
);

withLocaleFileRequired​

Higher-order component to wrap pages or components in an app. This checks to see if a locale file has been loaded, and fetches it if not. Once loaded, the wrapped component will be rendered.

Signature

  • withLocaleFileRequired(localeFilePath, options)

Props

  • localeFilePath - (string|string[]) The locale file path to load.
  • [options] - (object) Optional configuration
    • loading - (string|node) Content to render while loading, otherwise null.
    • forwardRef - (boolean) Add a ref to the connected wrapper component.

Example​

import { withLocaleFileRequired } from '@gasket/react-intl';
import { FormattedMessage } from 'react-intl';

const Component = props => <h1><FormattedMessage id='welcome'/></h1>

export default withLocaleFileRequired('/locales/extra')(Component);

LocaleFileRequired​

This component can also require locale files. This can be useful for components that want to render certain content quickly, while deferring rendering other content until a dynamic locale file loads.

Signature

  • <LocaleFileRequired { ...props } />

Props

  • localeFilePath - (string|string[]) The locale file path to load.
  • loading - (string|node) Content to render while loading, otherwise null.
import { LocaleFileRequired } from '@gasket/react-intl';
import { FormattedMessage } from 'react-intl';

const Component = props => (
  <>
    <LocaleFileRequired localeFilePath='/locales'>
      <h1><FormattedMessage id='welcome'/></h1>
    </LocaleFileRequired>
    <LocaleFileRequired localeFilePath='/locales/paragraphs' loading='Loading...'>
      <p><FormattedMessage id='long-description'/></p>
    </LocaleFileRequired>
  </>
)

export default Component;

Hooks​

useMessages​

This hook will return an object containing all messages for the current locale.

Signature

  • useMessages(): Messages
import {
  useMessages
} from '@gasket/react-intl';

export default function MyComponent(props) {
  const messages = useMessages();

  return <p>{ messages.welcome }</p>;
}

useLocaleFile​

Use this hook when you need more control versus what the components provide. The hook will return the current loading status of the dynamic locale file(s).

Signature

  • useLocaleFile(...localeFilePath): loadState

Props

import {
  useLocaleFile,
  LocaleFileStatus,
  useMessages
} from '@gasket/react-intl';

export default function MyComponent(props) {
  const status = useLocaleFile('/locales/custom');
  const messages = useMessages();
  
  if (status === LocaleFileStatus.error) return 'Could not translate.';
  if (status !== LocaleFileStatus.loaded) return 'Fetching translations...';

  return <p>{ messages.custom_welcome }</p>;
}

License​

MIT