Next.js 使用

Next 适配器分为：

  • 一个本地 18ways.config.ts 文件
  • 在 next.config.js 中进行构建时 Next 集成
  • 来自 @18ways/next/server 的服务器辅助工具
  • @18ways/next/client 中的客户端辅助程序

共享配置

在你的应用根目录中创建 18ways.config.ts。

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;

然后，在你的 next.config.js 中：

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

App Router 路径路由

对于 App Router，语言路由由路由树本身定义：

  • 公开的本地化路由位于 app/[lang]/... 下
  • 未本地化的路由保留在 [lang] 之外

路径路由器路径路由

如果你想要基于路径的语言环境路由，请设置 router: 'path' 并提供 acceptedLocales。 withWays() 随后会为你配置原生 Next i18n 路径路由，同时禁用 Next 的自动语言环境 检测，使 18ways 继续负责语言环境解析。

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;

当现有的路由层已经负责带区域设置感知的 URL，而你只想让 18ways 管理区域设置状态时，请使用 router: 'none'。

根布局

从 @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>
  );
}

代理

在 App Router 中，使用 proxy.ts 来处理根语言环境重定向以及任何域名规范化：

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

如果你的应用已经有自己的 proxy.ts 或 middleware.ts，请组合 getWaysProxyResponse() ，并在你应用的其余特定逻辑之前返回它：

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
}

客户端区域设置更改

使用 useLocale() 来自 @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} />;
}

当当前路由已本地化时，setLocale() 会保留该路由并更新 locale 分段。当当前路由未本地化时，它会保持该路由未本地化并更新 locale 状态。

从 @18ways/next/client 导入：

tsx
import { Link, useRouter, useUnlocalizedPathname } from '@18ways/next/client';
  • Link 会自动本地化内部 href 链接
  • useRouter() 对 push() 和 replace() 适用相同的规则
  • useUnlocalizedPathname() 让你在不带语言前缀的情况下比较路由状态

仅在需要强制选择时才使用 locale 覆盖项：

  • locale="fr-FR" 会强制使用本地化目标
  • locale={false} 会强制使用未本地化的目标

翻译后的元数据

generateWaysMetadata() 可以为您翻译字符串元数据字段。

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