1.0.0

next-international 1.0.0 is the first production-ready release, with feature parity across App and Pages Router. We have a brand new documentation website, Static Rendering for the App Router, new options, and improved APIs!

Upgrade now by installing the latest version:

pnpm install next-international@latest

• 🎉 New features
  • New documentation and website (App & Pages Router)
  • Static Rendering / Static Export support (App Router)
  • New rewriteDefault strategy (App Router)
  • Fallback locale on the server (App Router)
  • Allow catching not found locale errors (App Router)
• ⚠️ Breaking changes
  • Improved Middleware API (App Router)
  • Improved config API (App Router)

New documentation and website (App & Pages Router)

We now have a proper documentation website that you can browse at https://next-international.vercel.app! The documentation itself has also been improved to make it easier to understand and highlight code changes:

Static Rendering / Static Export support (App Router)

next-international now supports Static Rendering, meaning your pages can be rendered at build time and then be served statically from CDNs, resulting in faster TTFB.

See setup

Export getStaticParams from createI18nServer:

// locales/server.ts
export const {
  getStaticParams,
  ...
} = createI18nServer({
  ...
})

Inside all pages that you want to be statically rendered, call this setStaticParamsLocale function by giving it the locale page param:

// app/[locale]/page.tsx and any other page
import { setStaticParamsLocale } from 'next-international/server'

export default function Page({ params: { locale } }: { params: { locale: string } }) {
  setStaticParamsLocale(locale)

  return (
    ...
  )
}

And export a new generateStaticParams function. If all your pages should be rendered statically, you can also move this to the root layout:

// app/[locale]/page.tsx and any other page, or in the root layout
import { getStaticParams } from '../../locales/server'

export function generateStaticParams() {
  return getStaticParams()
}

New rewriteDefault strategy (App Router)

You can now choose to only rewrite the URL for the default locale, and keep others locale in the URL (e.g use /products instead of /en/products, but keep /fr/products) using the new rewriteDefault strategy:

const I18nMiddleware = createI18nMiddleware({
  locales: ['en', 'fr'],
  defaultLocale: 'en',
  urlMappingStrategy: 'rewriteDefault'
})

Fallback locale on the server (App Router)

This release adds missing support for fallback locales on the server with the App Router, similar to the fallbackLocale prop of I18nProviderClient. Navigate to locales/server.ts and add a new fallbackLocale option:

// locales/server.ts
import en from './en'

export const {
  ...
} = createI18nServer({
  ...
}, {
  fallbackLocale: en
})

Allow catching not found locale errors (App Router)

When a locale can't be found, we now use notFound() instead of throwing an un-catchable error. This allows to render a not-found.ts file easily.

Improved Middleware API (App Router)

⚠️ BREAKING (App Router)

Improve the middleware API for the App Router by using a single object argument and removing the need for as const for the locales:

See changes

Before:

const I18nMiddleware = createI18nMiddleware(['en', 'fr'] as const, 'fr')

// With all options:
const I18nMiddleware = createI18nMiddleware(['en', 'fr'] as const, 'fr', {
  urlMappingStrategy: 'rewrite',
  resolveLocaleFromRequest: request => {
    // Do your logic here to resolve the locale
    return 'fr'
  }
})

After:

const I18nMiddleware = createI18nMiddleware({
  locales: ['en', 'fr'],
  defaultLocale: 'en'
})

// With all options:
const I18nMiddleware = createI18nMiddleware({
  locales: ['en', 'fr'],
  defaultLocale: 'en',
  urlMappingStrategy: 'rewrite',
  resolveLocaleFromRequest: request => {
    // Do your logic here to resolve the locale
    return 'fr'
  }
})

Improved config API (App Router)

⚠️ BREAKING (App Router)

Improve the API for configuring the App Router behaviors by moving all configurations from specific functions to createI18n* functions. This avoids duplicating multiple times the same configuration, and will allow for more configuration options in the future.

These changes are only affecting you if you were using these options.

See changes for basePath and segmentName

basePath config

Before:

// locales/client.ts
export const { useChangeLocale } = createI18nClient({
  en: () => import('./en'),
  fr: () => import('./fr')
})

// In a Client Component
const changeLocale = useChangeLocale({
  basePath: '/base'
})

After:

// locales/client.ts
export const { useChangeLocale } = createI18nClient({
  en: () => import('./en'),
  fr: () => import('./fr')
}, {
  basePath: '/base'
})

// In a Client Component
const changeLocale = useChangeLocale()

segmentName config

Before:

// locales/client.ts
export const { useCurrentLocale } = createI18nClient({
  en: () => import('./en'),
  fr: () => import('./fr')
})

// in a Client Component
const currentLocale = useCurrentLocale({
  segmentName: 'locale'
})

// locales/server.ts
export const { getStaticParams } = createI18nServer({
  en: () => import('./en'),
  fr: () => import('./fr')
})

// in a page
export function generateStaticParams() {
  return getStaticParams({
    segmentName: 'locale'
  })
}

After:

// locales/client.ts
export const { useCurrentLocale } = createI18nClient({
  en: () => import('./en'),
  fr: () => import('./fr')
}, {
  segmentName: 'locale'
})

// in a Client Component
const currentLocale = useCurrentLocale()

// locales/server.ts
export const { getStaticParams } = createI18nServer({
  en: () => import('./en'),
  fr: () => import('./fr')
}, {
  segmentName: 'locale'
})

// in a page
export function generateStaticParams() {
  return getStaticParams()
}

What's Changed

• chore: add issue templates by @QuiiBz in #157
• feat: 1.0.0 release by @QuiiBz in #126

Full Changelog: 0.9.5...1.0.0