feat!: Revamp augmented types and add support for typed Locale

docs/src/pages/docs/environments/actions-metadata-route-handlers.mdx

@@ -154,8 +154,9 @@ Note that by default, `next-intl` returns [the `link` response header](/docs/rou
 
 Next.js supports providing alternate URLs per language via the [`alternates` entry](https://nextjs.org/docs/app/api-reference/file-conventions/metadata/sitemap#generate-a-localized-sitemap) as of version 14.2. You can use your default locale for the main URL and provide alternate URLs based on all locales that your app supports. Keep in mind that also the default locale should be included in the `alternates` object.
 
-```tsx filename="app/sitemap.ts" {4-5,8-9}
+```tsx filename="app/sitemap.ts" {5-6,9-10}
 import {MetadataRoute} from 'next';
+import {Locale} from 'next-intl';
 import {routing, getPathname} from '@/i18n/routing';
 
 // Adapt this as necessary
@@ -179,7 +180,7 @@ function getEntry(href: Href) {
   };
 }
 
-function getUrl(href: Href, locale: (typeof routing.locales)[number]) {
+function getUrl(href: Href, locale: Locale) {
   const pathname = getPathname({locale, href});
   return host + pathname;
 }
@@ -206,12 +207,16 @@ You can use `next-intl` in [Route Handlers](https://nextjs.org/docs/app/building
 
 ```tsx filename="app/api/hello/route.tsx"
 import {NextResponse} from 'next/server';
+import {hasLocale} from 'next-intl';
 import {getTranslations} from 'next-intl/server';
 
 export async function GET(request) {
   // Example: Receive the `locale` via a search param
   const {searchParams} = new URL(request.url);
   const locale = searchParams.get('locale');
+  if (!hasLocale(locales, locale)) {
+    return NextResponse.json({error: 'Invalid locale'}, {status: 400});
+  }
 
   const t = await getTranslations({locale, namespace: 'Hello'});
   return NextResponse.json({title: t('title')});

docs/src/pages/docs/environments/error-files.mdx

@@ -77,14 +77,15 @@ export default function RootLayout({children}) {
 }
 ```
 
-For the 404 page to render, we need to call the `notFound` function in the root layout when we detect an incoming `locale` param that isn't a valid locale.
+For the 404 page to render, we need to call the `notFound` function in the root layout when we detect an incoming `locale` param that isn't valid.
 
 ```tsx filename="app/[locale]/layout.tsx"
+import {hasLocale} from 'next-intl';
 import {notFound} from 'next/navigation';
+import {routing} from '@/i18n/routing';
 
 export default function LocaleLayout({children, params: {locale}}) {
-  // Ensure that the incoming `locale` is valid
-  if (!routing.locales.includes(locale as any)) {
+  if (!hasLocale(routing.locales, locale)) {
     notFound();
   }
 

docs/src/pages/docs/getting-started/app-router/with-i18n-routing.mdx

@@ -147,16 +147,15 @@ When using features from `next-intl` in Server Components, the relevant configur
 
 ```tsx filename="src/i18n/request.ts"
 import {getRequestConfig} from 'next-intl/server';
+import {hasLocale} from 'next-intl';
 import {routing} from './routing';
 
 export default getRequestConfig(async ({requestLocale}) => {
-  // This typically corresponds to the `[locale]` segment
-  let locale = await requestLocale;
-
-  // Ensure that a valid locale is used
-  if (!locale || !routing.locales.includes(locale as any)) {
-    locale = routing.defaultLocale;
-  }
+  // Typically corresponds to the `[locale]` segment
+  const requested = await requestLocale;
+  const locale = hasLocale(routing.locales, requested)
+    ? requested
+    : routing.defaultLocale;
 
   return {
     locale,
@@ -186,7 +185,7 @@ const withNextIntl = createNextIntlPlugin(
 The `locale` that was matched by the middleware is available via the `locale` param and can be used to configure the document language. Additionally, we can use this place to pass configuration from `i18n/request.ts` to Client Components via `NextIntlClientProvider`.
 
 ```tsx filename="app/[locale]/layout.tsx"
-import {NextIntlClientProvider} from 'next-intl';
+import {NextIntlClientProvider, Locale, hasLocale} from 'next-intl';
 import {getMessages} from 'next-intl/server';
 import {notFound} from 'next/navigation';
 import {routing} from '@/i18n/routing';
@@ -196,10 +195,9 @@ export default async function LocaleLayout({
   params: {locale}
 }: {
   children: React.ReactNode;
-  params: {locale: string};
+  params: {locale: Locale};
 }) {
-  // Ensure that the incoming `locale` is valid
-  if (!routing.locales.includes(locale as any)) {
+  if (!hasLocale(routing.locales, locale)) {
     notFound();
   }
 
@@ -297,12 +295,12 @@ export function generateStaticParams() {
 
 ```tsx filename="app/[locale]/layout.tsx"
 import {setRequestLocale} from 'next-intl/server';
+import {hasLocale} from 'next-intl';
 import {notFound} from 'next/navigation';
 import {routing} from '@/i18n/routing';
 
 export default async function LocaleLayout({children, params: {locale}}) {
-  // Ensure that the incoming `locale` is valid
-  if (!routing.locales.includes(locale as any)) {
+  if (!hasLocale(routing.locales, locale)) {
     notFound();
   }
 

docs/src/pages/docs/routing.mdx

@@ -297,11 +297,12 @@ In case you're using a system like a CMS to configure localized pathnames, you'l
 
 ```tsx filename="page.tsx"
 import {notFound} from 'next';
+import {Locale} from 'next-intl';
 import {fetchContent} from './cms';
 
 type Props = {
   params: {
-    locale: string;
+    locale: Locale;
     slug: Array<string>;
   };
 };