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