@gasket/react-intl
React component library to enable localization for Gasket apps. Loads and manages locale files from @gasket/plugin-intl.
-
React components:
-
React hooks:
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 configurationloading
- (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
localeFilePath
- (...string[]) One or more locale file path to load.
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>;
}