Tài liệu tham khảo Next.js

`18ways.config.*`

Tạo 18ways.config.ts, 18ways.config.js, hoặc 18ways.config.cjs trong thư mục gốc ứng dụng của bạn và xuất cấu hình 18ways của bạn ở đó.

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;

`withWays()`

Nhập từ @18ways/next/config và gọi nó từ next.config.js.

import { withWays } from '@18ways/next/config';

Khi 18ways.config.* tồn tại, withWays() sẽ tự động tải nó. Với router: 'path', nó trả về cấu hình i18n gốc của Next, với tính năng phát hiện locale bị tắt. Với router: 'app' và router: 'none', nó chèn alias cần thiết cho các lệnh nhập trực tiếp từ @18ways/next/server.

Các tùy chọn chung:

Tùy chọn	Kiểu	Ghi chú
`apiKey`	`chuỗi`	Bắt buộc.
`baseLocale`	`chuỗi`	Ngôn ngữ nguồn và ngôn ngữ mặc định cho định tuyến.
`router`	`'app' \| 'path' \| 'none'`	Chế độ định tuyến locale. Dùng `none` khi một router khác đã quản lý các URL locale.
`acceptedLocales`	`chuỗi[]`	Danh sách locale tường minh. Bắt buộc với `path`, còn lại là tùy chọn. Hãy giữ chế độ `path` đồng bộ với các ngôn ngữ đã bật trong bảng điều khiển 18ways của bạn.
`domains`	`Array<{domain, defaultLocale}>`	Bản đồ định tuyến miền tùy chọn.
`localeParamName`	`chuỗi`	Tham số phân đoạn ngôn ngữ của App Router. Mặc định là `lang`.
`persistLocaleCookie`	`boolean \| ((request) => boolean)`	Chính sách duy trì cookie locale cho các thay đổi locale ở phía server và client.
`thời gian sống của bộ nhớ đệm`	`số`	TTL bộ nhớ đệm cho các yêu cầu adapter.
`fetcher`	`kiểu của fetch`	Triển khai fetch tùy chỉnh.

`init(config)`

Nhập từ @18ways/next/server.

Dùng nó khi bạn muốn ràng buộc một đối tượng cấu hình một cách tường minh.

`WaysRoot`

Nhập trực tiếp WaysRoot từ @18ways/next/server trong các layout của bạn sau khi bọc next.config.js bằng withWays(...).

Dùng WaysRoot trong layout của bạn để adapter có thể khởi tạo trạng thái runtime cho yêu cầu hiện tại. Với App Router locale routing, điều này thường có nghĩa là app/[lang]/layout.tsx.

`getLocale()`

Phân giải locale hiện tại ở phía server. Đây là helper nên dùng khi bạn cần trạng thái locale ở ngoài WaysRoot, ví dụ trong các helper SEO chỉ chạy server hoặc mã server khác gắn với request.

`htmlAttrs()`

htmlAttrs() sẽ phân giải các giá trị lang và dir hiện tại cho phần tử tài liệu.

`generateWaysMetadata()`

Dùng generateWaysMetadata() bên trong generateMetadata() khi bạn muốn các tiêu đề, mô tả và các URL canonical hoặc alternate phù hợp với ngôn ngữ được dịch.

`proxy.ts`

Với router: 'app', proxy.ts là điểm vào được khuyến nghị cho các chuyển hướng locale tại thời điểm yêu cầu. Xuất lại từ @18ways/next/proxy để xử lý / -> /{locale} và chuẩn hoá miền.

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

Nếu bạn đã có sẵn proxy.ts hoặc middleware.ts của dự án, hãy dùng getWaysProxyResponse(request) và trả về nó trước phần logic còn lại.

Trợ giúp khách hàng

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

`useLocale()`

Đọc và thay đổi ngôn ngữ hiện tại. Đây là hook mà bạn dùng cùng với LanguageSwitcher hoặc giao diện bộ chọn tùy chỉnh của riêng bạn.

`useRouter()`

Bộ bọc có nhận biết locale quanh Next navigation. Truyền locale="fr-FR" để ép đích đến đã được bản địa hoá, hoặc locale={false} để ép một đích đến không bản địa hoá.

`Link`

Bộ bọc có nhận biết locale quanh next/link với cùng mô hình ghi đè như useRouter().

`useUnlocalizedPathname()`

Đọc pathname hiện tại mà không có tiền tố ngôn ngữ.

`useLocalizedHref()`

Helper mức thấp hơn để chuyển một href nội bộ thành href hiện tại có nhận biết locale.

Path routing config

Ở chế độ router: 'app', bộ chuyển đổi sẽ đi theo cây tuyến đường của bạn:

các tuyến dưới app/[lang]/... được bản địa hoá
các tuyến ngoài segment đó sẽ không được bản địa hoá

Link, useRouter(), và setLocale() mặc định coi các tuyến nội bộ là đã bản địa hoá. Chỉ dùng locale={false} khi bạn cần trỏ tường minh tới một tuyến không bản địa hoá.