Next.js usage

Adapter Next được tách thành:

một tệp 18ways.config.ts cục bộ
tích hợp Next ở thời điểm build trong next.config.js
các helper phía máy chủ từ @18ways/next/server
các helper phía client trong @18ways/next/client

Cấu hình dùng chung

Tạo 18ways.config.ts trong thư mục gốc của ứng dụng.

// 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;

Sau đó, trong next.config.js của bạn:

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

Định tuyến đường dẫn App Router

Với App Router, định tuyến ngôn ngữ được xác định bởi chính cây tuyến đường:

các tuyến công khai đã bản địa hoá nằm dưới app/[lang]/...
các tuyến không bản địa hoá nằm ngoài [lang]

Định tuyến đường dẫn Path Router

Nếu bạn muốn định tuyến ngôn ngữ theo đường dẫn, hãy đặt router: 'path' và cung cấp acceptedLocales. withWays() rồi sẽ cấu hình sẵn định tuyến đường i18n gốc của Next cho bạn, đồng thời tắt tính năng tự động phát hiện ngôn ngữ của Next để 18ways toàn quyền xử lý việc phân giải ngôn ngữ.

// 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;

Dùng router: 'none' khi một lớp định tuyến hiện có nào đó đã quản lý các URL có nhận biết ngôn ngữ, và bạn chỉ muốn 18ways quản lý trạng thái ngôn ngữ.

Bố cục gốc

Import from @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

Trong App Router, hãy dùng proxy.ts để xử lý chuyển hướng ngôn ngữ gốc và mọi chuẩn hoá miền:

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

Nếu ứng dụng của bạn đã có proxy.ts hoặc middleware.ts riêng, hãy ghép getWaysProxyResponse() và trả về nó trước phần logic riêng còn lại của ứng dụng:

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
}

Client-side locale changes

Use useLocale() from @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} />;
}

Khi tuyến hiện tại đã được bản địa hoá, setLocale() sẽ giữ nguyên tuyến và cập nhật phân đoạn ngôn ngữ. Khi tuyến hiện tại chưa được bản địa hoá, nó sẽ giữ tuyến đó không bản địa hoá và cập nhật trạng thái ngôn ngữ.

Nhập từ @18ways/next/client:

tsx

import { Link, useRouter, useUnlocalizedPathname } from '@18ways/next/client';

Link tự động bản địa hoá các href nội bộ
useRouter() áp dụng cùng các quy tắc đó cho push() và replace()
useUnlocalizedPathname() cho phép bạn so sánh trạng thái route mà không có tiền tố locale

Chỉ dùng ghi đè locale khi bạn cần ép chọn một phương án:

locale="fr-FR" buộc đích đến phải là bản địa hoá
locale={false} buộc đích đến không bản địa hoá

Translated metadata

generateWaysMetadata() can translate string metadata fields for you.

tsx

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