Utilisation de Next.js

L’adaptateur Next est divisé en :

  • un fichier local 18ways.config.ts
  • Intégration Next au moment de la compilation dans next.config.js
  • assistants serveur de @18ways/next/server
  • assistants client dans @18ways/next/client

Configuration partagée

Créez 18ways.config.ts à la racine de votre application.

ts
// 18ways.config.ts
import type { WaysConfig } from '@18ways/next/config';
 
export default {
  apiKey: process.env.NEXT_PUBLIC_18WAYS_PUBLIC_API_KEY,
  baseLocale: 'en-GB',
  router: 'app', // 'app', 'path', or 'none' depending on if you use app router, path router, or if you don't want the router to sync with locale at all
} satisfies WaysConfig;

Ensuite, dans votre next.config.js :

ts
// next.config.js
const { withWays } = require('@18ways/next/config');
 
module.exports = withWays({
  // your normal next config here
});

Routage des chemins du routeur d’application

Pour App Router, le routage par langue est défini par l’arborescence des routes elle-même :

  • les routes localisées publiques se trouvent sous app/[lang]/...
  • les routes non localisées restent en dehors de [lang]

Routage du chemin Path Router

Si vous souhaitez un routage des locales basé sur le chemin, définissez router: 'path' et fournissez acceptedLocales. withWays() configure alors pour vous le routage natif des chemins i18n de Next, avec la détection automatique des locales de Next désactivée afin qu’18ways reste maître de la résolution des locales.

ts
// 18ways.config.ts
import type { WaysConfig } from '@18ways/next/config';
 
export default {
  apiKey: process.env.NEXT_PUBLIC_18WAYS_PUBLIC_API_KEY,
  baseLocale: 'en-GB',
  router: 'path', // 'app', 'path', or 'none' depending on if you use app router, path router, or if you don't want the router to sync with locale at all
  acceptedLocales: ['en-GB', 'fr-FR'], // keep this in sync with the languages enabled in your 18ways dashboard
} satisfies WaysConfig;

Utilisez router: 'none' lorsqu’une couche de routage existante gère déjà des URL sensibles à la langue et que vous souhaitez seulement qu’18ways gère l’état de la langue.

Disposition racine

Importer depuis @18ways/next/server.

tsx
import { WaysRoot, htmlAttrs } from '@18ways/next/server';
 
export default async function RootLayout({ children, params }) {
  const attrs = await htmlAttrs({ params });
 
  return (
    <html {...attrs}>
      <body>
        <WaysRoot params={params}>{children}</WaysRoot>
      </body>
    </html>
  );
}

Proxy

Dans App Router, utilisez proxy.ts pour gérer la redirection vers la locale racine et toute canonicalisation de domaine :

ts
export { default, config } from '@18ways/next/proxy';

Si votre application dispose déjà de son propre proxy.ts ou middleware.ts, composez getWaysProxyResponse() et renvoyez-le avant le reste de votre logique spécifique à l’application :

ts
import type { NextFetchEvent, NextRequest } from 'next/server';
import { getWaysProxyResponse } from '@18ways/next/proxy';
 
export default async function middleware(request: NextRequest, event: NextFetchEvent) {
  const waysResponse = await getWaysProxyResponse(request);
  if (waysResponse) {
    return waysResponse;
  }
 
  // your existing middleware logic
}

Modifications de la locale côté client

Utilisez useLocale() de @18ways/next/client.

tsx
'use client';
 
import { LanguageSwitcher } from '@18ways/react';
import { useLocale } from '@18ways/next/client';
 
export function LocaleControls() {
  const { locale, setLocale } = useLocale();
 
  return <LanguageSwitcher currentLocale={locale} onLocaleChange={setLocale} />;
}

Lorsque la route actuelle est localisée, setLocale() préserve la route et met à jour le segment de locale. Lorsque la route actuelle n’est pas localisée, elle conserve la route non localisée et met à jour l’état de la locale.

Importer depuis @18ways/next/client :

tsx
import { Link, useRouter, useUnlocalizedPathname } from '@18ways/next/client';
  • Link localise automatiquement les href internes
  • useRouter() applique les mêmes règles à push() et replace()
  • useUnlocalizedPathname() permet de comparer l’état de la route sans le préfixe de langue

Utilisez la surcharge locale uniquement lorsque vous devez imposer un choix :

  • locale="fr-FR" force une cible localisée
  • locale={false} force une cible non localisée

Métadonnées traduites

generateWaysMetadata() peut traduire les champs de métadonnées de chaîne pour vous.

tsx
export async function generateMetadata({ params }) {
  return generateWaysMetadata(
    (t) => ({
      title: t('Pricing'),
      description: t('Simple pricing for runtime translation'),
    }),
    { params, pathname: '/pricing' }
  );
}
Utilisation de Next.js