Verwendung von Next.js

Der Next-Adapter ist unterteilt in:

  • eine lokale 18ways.config.ts-Datei
  • Next-Integration zur Build-Zeit in next.config.js
  • Server-Helpers aus @18ways/next/server
  • Client-Helper in @18ways/next/client

Geteilte Konfiguration

Erstelle 18ways.config.ts im Stammverzeichnis deiner App.

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;

Dann in deiner next.config.js:

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

App-Router-Pfadrouting

Für den App Router wird das Locale-Routing durch den Routentree selbst definiert:

  • öffentliche lokalisierte Routen liegen unter app/[lang]/...
  • nicht lokalisierte Routen bleiben außerhalb von [lang]

Pfad-Router-Pfadrouting

Wenn du eine pfadbasierte Locale-Routing verwenden möchtest, setze router: 'path' und gib acceptedLocales an. withWays() konfiguriert dann das native Next-i18n-Pfadrouting für dich, wobei die automatische Locale-Erkennung von Next deaktiviert ist, sodass 18ways weiterhin die Locale-Auflösung übernimmt.

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;

Verwenden Sie router: 'none', wenn eine vorhandene Routing-Schicht bereits für Gebietsschema-abhängige URLs zuständig ist und Sie 18ways nur zur Verwaltung des Gebietsschema-Status verwenden möchten.

Wurzel-Layout

Importieren von @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

Im App Router verwenden Sie proxy.ts, um die Weiterleitung für das Root-Locale und jede Domain-Kanonisierung zu handhaben:

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

Wenn deine App bereits eine eigene proxy.ts oder middleware.ts hat, rufe getWaysProxyResponse() auf und gib sie vor dem restlichen app-spezifischen Code zurück:

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
}

Änderungen der Client-seitigen Locale

Verwenden Sie useLocale() von @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} />;
}

Wenn die aktuelle Route lokalisiert ist, behält setLocale() die Route bei und aktualisiert das Locale-Segment. Wenn die aktuelle Route nicht lokalisiert ist, bleibt die Route nicht lokalisiert und der Locale-Status wird aktualisiert.

Importieren aus @18ways/next/client:

tsx
import { Link, useRouter, useUnlocalizedPathname } from '@18ways/next/client';
  • Link lokalisiert interne hrefs automatisch
  • useRouter() wendet die gleichen Regeln auf push() und replace() an
  • useUnlocalizedPathname() ermöglicht es dir, den Routenzustand ohne den Locale-Präfix zu vergleichen

Verwenden Sie die Überschreibung von locale nur dann, wenn Sie eine Auswahl erzwingen müssen:

  • locale="fr-FR" erzwingt ein lokalisiertes Ziel
  • locale={false} erzwingt ein nicht lokalisiertes Ziel

Übersetzte Metadaten

generateWaysMetadata() kann für Sie String-Metadatenfelder übersetzen.

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