Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat!: next-intl@4 #1412

Draft
wants to merge 97 commits into
base: main
Choose a base branch
from
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
97 commits
Select commit Hold shift + click to select a range
a8fb0e3
fix: Don't commit canary releases
amannn Jun 20, 2024
cf3f8b0
Improve docs [skip ci]
amannn Jun 20, 2024
4fd9b20
fix: Try out updated credits
amannn Jun 20, 2024
47239f9
v3.15.3-canary.0
amannn Jun 20, 2024
0d60a72
Revert "v3.15.3-canary.0"
amannn Jun 20, 2024
c459669
Merge remote-tracking branch 'origin/main' into canary
amannn Jun 20, 2024
8d3ab38
fix: Prefer more specific routes in `usePathname` when detecting the …
amannn Jun 26, 2024
605c9a6
Merge remote-tracking branch 'origin/main' into canary
amannn Jun 26, 2024
cb15046
Merge branch 'fix/sort-pathnames-usepathname' into canary
amannn Jun 26, 2024
11262b8
Merge remote-tracking branch 'origin/main' into canary
amannn Jul 11, 2024
7976376
feat: Support `trailingSlash: true` in Next.js config (#1188)
amannn Jul 11, 2024
b352c10
fix: Release please?
amannn Jul 11, 2024
cba448a
Merge remote-tracking branch 'origin/main' into canary
amannn Jul 11, 2024
0c670b2
Merge remote-tracking branch 'origin/main' into canary
amannn Jul 12, 2024
5dc7f53
Merge remote-tracking branch 'origin/main' into canary
amannn Jul 12, 2024
11dcbcc
Merge remote-tracking branch 'origin/main' into canary
amannn Jul 12, 2024
1b074da
Merge remote-tracking branch 'origin/main' into canary
amannn Jul 12, 2024
e98682b
Merge remote-tracking branch 'origin/main' into canary
amannn Jul 15, 2024
7c6f533
Merge branch 'main' into canary
amannn Aug 23, 2024
8b4c7c4
feat!: Automatically inherit `formats` when `NextIntlClientProvider` …
amannn Aug 26, 2024
d80d691
feat!: Inherit context between providers (#1413)
amannn Oct 9, 2024
8158de4
Merge remote-tracking branch 'origin/canary' into HEAD
amannn Oct 9, 2024
7dd54c1
Merge remote-tracking branch 'origin/canary' into v4
amannn Oct 24, 2024
ccaef97
fix lint
amannn Oct 24, 2024
25a0dc8
bump size
amannn Oct 24, 2024
9f4754c
feat!: Make package ESM-only, target modern browsers, use modern JSX …
amannn Oct 29, 2024
5b5f0e3
feat!: Remove deprecated APIs (#1479)
amannn Oct 29, 2024
eb5bf09
feat!: Bump minimum required `typescript` version to 5 for projects u…
amannn Oct 29, 2024
a6238f4
feat!: Remove deprecated APIs pt. 2 (#1482)
amannn Oct 29, 2024
829998e
feat!: Infer default `locale` for `NextIntlClientProvider` from `useP…
amannn Oct 29, 2024
a9c35db
add comment
amannn Oct 29, 2024
5402851
feat!: Require `locale` to be returned from `getRequestConfig` (#1486)
amannn Oct 29, 2024
b4e4d1d
feat!: Decrease cookie expiration to 5 hours, only set cookie when ne…
amannn Oct 30, 2024
d83abc2
feat: Return type-safe `IntlMessages` from `useMessages` & `getMessag…
amannn Oct 30, 2024
a7aaf56
feat!: Revamp augmented types and add support for typed `Locale` (#1495)
amannn Nov 1, 2024
2388c9b
remove unused file
amannn Nov 1, 2024
01268f6
feat: Type-safe ICU arguments (#1499)
amannn Nov 7, 2024
0bb75c5
decrease size by making plain message error handling dev-only
amannn Nov 7, 2024
dd28ac1
fix: Allow to merge inline formats with global formats in `t` (#1523)
amannn Nov 7, 2024
4675f7e
Merge remote-tracking branch 'origin/main' into v4
amannn Nov 8, 2024
c154409
move/rename file
amannn Nov 8, 2024
887034d
simplify signature
amannn Nov 8, 2024
ab22a92
temporarily disable exports that cause OOM
amannn Nov 8, 2024
b9c515e
simplify types for `createTranslator`
amannn Nov 8, 2024
8ac7206
fix: Fix recursion bug in typed ICU args (#1527)
amannn Nov 8, 2024
21f2dac
remove outdated constant
amannn Nov 12, 2024
2a92f17
feat!: Remove default of `now={new Date()}` from `NextIntlClientProvi…
amannn Nov 14, 2024
dc36097
feat!: Don't read a default for `useLocale` from `useParams.locale` o…
amannn Nov 14, 2024
3ff1923
decrease size, relax next.js peer dependency
amannn Nov 14, 2024
f44ae15
feat: Adopt shared ICU type parser (#1549)
amannn Nov 14, 2024
7d89d54
chore: Strict type imports with ESLint (#1524)
amannn Nov 14, 2024
c2a8984
Merge remote-tracking branch 'origin/main' into v4
amannn Nov 15, 2024
00a79d4
feat: publish v4 prerelease
amannn Nov 15, 2024
ba18078
rename canary workflow
amannn Nov 15, 2024
6f1a39d
unique workflow names [skip ci]
amannn Nov 15, 2024
486a7bd
docs: minor fixes
amannn Nov 15, 2024
dfa5ea0
docs: blog post draft
amannn Nov 18, 2024
9ea117c
fix: Disallow string dates, improve autocomplete (#1557)
amannn Nov 18, 2024
c8eb4ad
fix: Use `fs.watch` instead of `chokidar`
amannn Nov 19, 2024
5a7f7be
fix: Move locale validation to `defineRouting` (#1560)
amannn Nov 19, 2024
bfcd251
docs: Proofread blog post
amannn Nov 19, 2024
7b755e9
fix: update warning for now fallback in `createFormatter`
amannn Nov 19, 2024
18156c4
fix: use v4-beta tag instead
amannn Nov 19, 2024
0b2c951
docs: reference new tag
amannn Nov 19, 2024
6275030
feat!: Disallow passing `null`, `undefined` or `boolean` as an ICU ar…
amannn Nov 20, 2024
c323050
fix: release for "feat!: " as well
amannn Nov 20, 2024
8cce53e
docs: performance notes of messages augmentation
amannn Nov 20, 2024
6d94a9e
docs: fix toc, note in gdpr release notes [skip ci]
amannn Nov 28, 2024
db95243
docs: Update legacy example to use `next-intl` instead of `use-intl` …
amannn Nov 28, 2024
21b882a
docs: improve relative time formatting docs (also fix release conditi…
amannn Nov 28, 2024
cb6b998
Merge remote-tracking branch 'origin/main' into v4
amannn Nov 28, 2024
8f37883
fix: Change error messages to not mention provider (since there might…
amannn Dec 2, 2024
8b9a2fc
Merge remote-tracking branch 'origin/main' into v4
amannn Dec 18, 2024
7e7011d
fix: Fix hard reload when using `<Link />` in Next.js 15 (#1620)
amannn Dec 18, 2024
9f3a4b0
docs: Improve blog post wording
amannn Dec 19, 2024
dac018a
docs: blog post wording
amannn Dec 19, 2024
c224d1c
docs: Remove blog post
amannn Dec 20, 2024
0825f08
feat: Re-introduce `locale` argument for `getRequestConfig` to be use…
amannn Dec 20, 2024
56f59a7
docs: v4 banner
amannn Dec 20, 2024
e65f4f9
Merge remote-tracking branch 'origin/main' into v4
amannn Dec 20, 2024
ddd5ae5
fix: Make locale cookie a session cookie (#1634)
amannn Dec 23, 2024
a1a70cb
docs: Improve wording about GDPR compliance
amannn Dec 23, 2024
32dfcc2
docs: Note on `await connection()` in relative time docs
amannn Dec 23, 2024
f10dbba
feat: Allow overriding typed `Messages` when using `createTranslator`…
amannn Jan 10, 2025
32fc4e3
fix: Retain index files in dist output to match declarations (#1665)
amannn Jan 17, 2025
bb49880
Revert "fix: Retain index files in dist output to match declarations …
amannn Jan 17, 2025
f511797
fix: Remove scripts from published packages
amannn Jan 17, 2025
5ec7f45
fix: Remove scripts from ignored pkg fields
amannn Jan 17, 2025
5b218d4
fix: Change imports to use `.js` to make them compatible with `eslint…
DuckThom Jan 24, 2025
67507cc
fix: Accept a deep partial of `Messages` for `messages` prop of provi…
amannn Jan 24, 2025
c40c5c9
feat: Inherit messages by default in `NextIntlClientProvider` (#1682)
amannn Jan 27, 2025
40d535a
fix: Start watcher during a hot reload of `next.config.ts` (#1690)
amannn Jan 28, 2025
77949ef
feat: Allow to override options of global formats (#1693)
amannn Feb 3, 2025
bae1131
feat: Use overloads for `relativeTime`
amannn Feb 3, 2025
9e73cbe
feat: Validate locale returned from `i18n/request.ts` (#1695)
amannn Feb 4, 2025
c4c5986
fix: Handle watch events on macOS caused by git (#1696)
amannn Feb 4, 2025
ca3fcd5
feat: change createMessagesDeclaration to also accept array for monor…
felix-quotez Feb 5, 2025
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
2 changes: 1 addition & 1 deletion .github/workflows/main.yml
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ on:
jobs:
build:
name: Build, lint, and test
runs-on: ubuntu-latest
runs-on: macos-15
env:
TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
TURBO_TEAM: ${{ vars.TURBO_TEAM }}
Expand Down
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
name: prerelease
name: prerelease (canary)

on:
push:
Expand Down Expand Up @@ -26,7 +26,7 @@ jobs:
- run: |
sed -i 's/"use-intl": "workspace:\^"/"use-intl": "workspace:"/' ./packages/next-intl/package.json && git commit -am "use fixed version"
- run: pnpm lerna publish 0.0.0-canary-${GITHUB_SHA::7} --no-git-reset --dist-tag canary --no-push --yes
if: "${{startsWith(github.event.head_commit.message, 'fix: ') || startsWith(github.event.head_commit.message, 'feat: ')}}"
if: "${{startsWith(github.event.head_commit.message, 'fix: ') || startsWith(github.event.head_commit.message, 'feat: ') || startsWith(github.event.head_commit.message, 'feat!: ')}}"
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
Expand Down
33 changes: 33 additions & 0 deletions .github/workflows/prerelease-v4.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
name: prerelease (v4)

on:
push:
branches:
- v4

jobs:
main:
runs-on: ubuntu-latest
permissions:
contents: write
id-token: write
steps:
- uses: actions/checkout@v4
- uses: pnpm/action-setup@v4
- uses: actions/setup-node@v4
with:
registry-url: 'https://registry.npmjs.org'
node-version: 20.x
cache: 'pnpm'
- run: pnpm install
- run: |
git config --global user.name "${{ github.actor }}"
git config --global user.email "${{ github.actor }}@users.noreply.github.com"
- run: |
sed -i 's/"use-intl": "workspace:\^"/"use-intl": "workspace:"/' ./packages/next-intl/package.json && git commit -am "use fixed version"
- run: pnpm lerna publish 4.0.0-beta-${GITHUB_SHA::7} --no-git-reset --dist-tag v4-beta --no-push --yes
if: "${{startsWith(github.event.head_commit.message, 'fix: ') || startsWith(github.event.head_commit.message, 'feat: ') || startsWith(github.event.head_commit.message, 'feat!: ')}}"
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
NPM_CONFIG_PROVENANCE: true
2 changes: 1 addition & 1 deletion .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ jobs:
git config --global user.name "${{ github.actor }}"
git config --global user.email "${{ github.actor }}@users.noreply.github.com"
- run: pnpm run publish
if: "${{startsWith(github.event.head_commit.message, 'fix: ') || startsWith(github.event.head_commit.message, 'feat: ')}}"
if: "${{startsWith(github.event.head_commit.message, 'fix: ') || startsWith(github.event.head_commit.message, 'feat: ') || startsWith(github.event.head_commit.message, 'feat!: ')}}"
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
Expand Down
1 change: 0 additions & 1 deletion docs/src/components/StayUpdated.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,5 @@

**Let's keep in touch:**

- [GitHub releases](https://github.com/amannn/next-intl/releases)
- [Bluesky (Jan Amann)](https://bsky.app/profile/amann.work)
- [X (Jan Amann)](https://x.com/jamannnnnn)
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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;
}
Expand All @@ -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')});
Expand Down
7 changes: 4 additions & 3 deletions docs/src/pages/docs/environments/error-files.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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();
}

Expand Down
24 changes: 10 additions & 14 deletions docs/src/pages/docs/environments/server-client-components.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -69,14 +69,17 @@ These functions are available:

Components that aren't declared with the `async` keyword and don't use interactive features like `useState`, are referred to as [shared components](https://github.com/reactjs/rfcs/blob/main/text/0188-server-components.md#sharing-code-between-server-and-client). These can render either as a Server or Client Component, depending on where they are imported from.

In Next.js, Server Components are the default, and therefore shared components will typically execute as Server Components.
In Next.js, Server Components are the default, and therefore shared components will typically execute as Server Components:

```tsx filename="UserDetails.tsx"
import {useTranslations} from 'next-intl';

export default function UserDetails({user}) {
const t = useTranslations('UserProfile');

// This component will execute as a Server Component by default.
// However, if it is imported from a Client Component, it will
// execute as a Client Component.
return (
<section>
<h2>{t('title')}</h2>
Expand Down Expand Up @@ -112,11 +115,13 @@ Regarding performance, async functions and hooks can be used interchangeably. Th

## Using internationalization in Client Components

Depending on your situation, you may need to handle internationalization in Client Components. While providing all messages to the client side is typically the easiest way to [get started](/docs/getting-started/app-router#layout) and a reasonable approach for many apps, you can be more selective about which messages are passed to the client side if you're interested in optimizing the performance of your app.
Depending on your situation, you may need to handle internationalization in Client Components. Providing all messages to the client side is the easiest way to get started, therefore `next-intl` automatically does this when you render [`NextIntlClientProvider`](/docs/usage/configuration#nextintlclientprovider). This is a reasonable approach for many apps.

However, you can be more selective about which messages are passed to the client side if you're interested in optimizing the performance of your app.

There are several options for using translations from `next-intl` in Client Components, listed here in order of enabling the best performance:

### Option 1: Passing translations to Client Components
### Option 1: Passing translated labels to Client Components

The preferred approach is to pass the processed labels as props or `children` from a Server Component.

Expand Down Expand Up @@ -275,8 +280,6 @@ In particular, page and search params are often a great option because they offe

### Option 3: Providing individual messages

To reduce bundle size, `next-intl` doesn't automatically provide [messages](/docs/usage/configuration#messages) or [formats](/docs/usage/configuration#formats) to Client Components.

If you need to incorporate dynamic state into components that can not be moved to the server side, you can wrap these components with `NextIntlClientProvider` and provide the relevant messages.

```tsx filename="Counter.tsx"
Expand Down Expand Up @@ -312,22 +315,16 @@ An automatic, compiler-driven approach is being evaluated in [`next-intl#1`](htt

### Option 4: Providing all messages

If you're building a highly dynamic app where most components use React's interactive features, you may prefer to make all messages available to Client Components.
If you're building a highly dynamic app where most components use React's interactive features, you may prefer to make all messages available to Client Components—this is the default behavior of `next-intl`.

```tsx filename="layout.tsx" /NextIntlClientProvider/
import {NextIntlClientProvider} from 'next-intl';
import {getMessages} from 'next-intl/server';

export default async function RootLayout(/* ... */) {
// Receive messages provided in `i18n/request.ts`
const messages = await getMessages();

return (
<html lang={locale}>
<body>
<NextIntlClientProvider messages={messages}>
{children}
</NextIntlClientProvider>
<NextIntlClientProvider>{children}</NextIntlClientProvider>
</body>
</html>
);
Expand Down Expand Up @@ -366,7 +363,6 @@ The component accepts the following props that are not serializable:

1. [`onError`](/docs/usage/configuration#error-handling)
2. [`getMessageFallback`](/docs/usage/configuration#error-handling)
3. Rich text elements for [`defaultTranslationValues`](/docs/usage/configuration#default-translation-values)

To configure these, you can wrap `NextIntlClientProvider` with another component that is marked with `'use client'` and defines the relevant props.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down Expand Up @@ -186,8 +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 {getMessages} from 'next-intl/server';
import {NextIntlClientProvider, Locale, hasLocale} from 'next-intl';
import {notFound} from 'next/navigation';
import {routing} from '@/i18n/routing';

Expand All @@ -196,31 +194,22 @@ 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();
}

// Providing all messages to the client
// side is the easiest way to get started
const messages = await getMessages();

return (
<html lang={locale}>
<body>
<NextIntlClientProvider messages={messages}>
{children}
</NextIntlClientProvider>
<NextIntlClientProvider>{children}</NextIntlClientProvider>
</body>
</html>
);
}
```

Note that `NextIntlClientProvider` automatically inherits configuration from `i18n/request.ts` here, but `messages` need to be passed explicitly.

### `src/app/[locale]/page.tsx` [#page]

And that's it!
Expand Down Expand Up @@ -297,12 +286,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();
}

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -129,7 +129,7 @@ The `locale` that was provided in `i18n/request.ts` is available via `getLocale`

```tsx filename="app/layout.tsx"
import {NextIntlClientProvider} from 'next-intl';
import {getLocale, getMessages} from 'next-intl/server';
import {getLocale} from 'next-intl/server';

export default async function RootLayout({
children
Expand All @@ -138,24 +138,16 @@ export default async function RootLayout({
}) {
const locale = await getLocale();

// Providing all messages to the client
// side is the easiest way to get started
const messages = await getMessages();

return (
<html lang={locale}>
<body>
<NextIntlClientProvider messages={messages}>
{children}
</NextIntlClientProvider>
<NextIntlClientProvider>{children}</NextIntlClientProvider>
</body>
</html>
);
}
```

Note that `NextIntlClientProvider` automatically inherits configuration from `i18n/request.ts` here, but `messages` need to be passed explicitly.

### `app/page.tsx` [#page]

Use translations in your page components or anywhere else!
Expand Down
6 changes: 0 additions & 6 deletions docs/src/pages/docs/getting-started/pages-router.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -109,9 +109,3 @@ export async function getStaticProps() {
</ul>

</Callout>

## Support for legacy Next.js versions

Next.js version 10, 11 and 12 are still supported. Note however that instead of installing `next-intl`, you'll have to import functionality like `useTranslations` from [`use-intl`](/docs/environments/core-library#react-apps).

See the [legacy example](https://github.com/amannn/next-intl/tree/main/examples/example-pages-router-legacy).
Loading