feat: Add useLocale and useTimeZone

docs/usage.md

@@ -428,3 +428,18 @@ function getMessageFallback({namespace, key, error}) {
   <App />
 </NextIntlProvider>
 ```
+
+## Retrieving provider config
+
+As a convenience, two hooks exist that allow to read configuration that was passed to the provider:
+
+```js
+// Returns either an explicitly configured locale from the
+// provider or if internationalized routing is set up, it
+// returns the configured locale from Next.js.
+const locale = useLocale(); 
+
+// Note that this will be `undefined` if no explicit
+// `timeZone` was configured on the provider.
+const timeZone = useTimeZone();
+```

packages/use-intl/src/index.tsx

@@ -6,7 +6,9 @@ export {
   RichTranslationValues
 } from './TranslationValues';
 export {default as useIntl} from './useIntl';
+export {default as useLocale} from './useLocale';
 export {default as useNow} from './useNow';
+export {default as useTimeZone} from './useTimeZone';
 export {default as Formats} from './Formats';
 export {default as DateTimeFormatOptions} from './DateTimeFormatOptions';
 export {default as NumberFormatOptions} from './NumberFormatOptions';

packages/use-intl/src/useLocale.tsx

@@ -0,0 +1,5 @@
+import useIntlContext from './useIntlContext';
+
+export default function useLocale() {
+  return useIntlContext().locale;
+}

packages/use-intl/src/useTimeZone.tsx

@@ -0,0 +1,5 @@
+import useIntlContext from './useIntlContext';
+
+export default function useTimeZone() {
+  return useIntlContext().timeZone;
+}

packages/use-intl/test/useLocale.test.tsx

@@ -0,0 +1,17 @@
+import {render, screen} from '@testing-library/react';
+import React from 'react';
+import {IntlProvider, useLocale} from '../src';
+
+it('returns the current locale', () => {
+  function Component() {
+    return <>{useLocale()}</>;
+  }
+
+  render(
+    <IntlProvider locale="en">
+      <Component />
+    </IntlProvider>
+  );
+
+  screen.getByText('en');
+});

packages/use-intl/test/useTimeZone.test.tsx

@@ -0,0 +1,31 @@
+import {render, screen} from '@testing-library/react';
+import React from 'react';
+import {IntlProvider, useTimeZone} from '../src';
+
+it('returns the time zone when it is configured', () => {
+  function Component() {
+    return <>{useTimeZone()}</>;
+  }
+
+  render(
+    <IntlProvider locale="de" timeZone="Europe/Berlin">
+      <Component />
+    </IntlProvider>
+  );
+
+  screen.getByText('Europe/Berlin');
+});
+
+it('returns undefined when no time zone is configured', () => {
+  function Component() {
+    return <>{useTimeZone()}</>;
+  }
+
+  const {container} = render(
+    <IntlProvider locale="de">
+      <Component />
+    </IntlProvider>
+  );
+
+  expect(container.textContent).toBe('');
+});