国际化 | MkSaaS - 快速构建 AI SaaS 产品

MkSaaS 使用 next-intl 进行国际化，让您可以轻松创建多语言应用程序。通过内置的 i18n 支持，您可以创建本地化的 UI 组件、邮件模板等，为全球用户提供更好的体验。

设置

配置

MkSaaS 模板支持国际化，让您可以轻松创建多语言的网站。

Property	Type	Description
`defaultLocale`	`string`	Default language locale (e.g., 'en')
`locales`	`Record<string, { flag?: string; name: string }>`	Available languages with flag emoji and display name

以下是如何在 website.tsx 配置文件中配置国际化：

src/config/website.tsx

export const websiteConfig = {
  // ...其他配置
  i18n: {
    defaultLocale: 'en',
    locales: {
      en: {
        flag: '🇺🇸',
        name: 'English',
      },
      zh: {
        flag: '🇨🇳',
        name: '中文',
      },
    },
  },
  // ...其他配置
};

如果您正在设置环境，现在可以回到环境配置文档并继续。本文档的其余部分可以稍后阅读。

环境配置

设置环境变量

国际化系统架构

MkSaaS 中的国际化系统设计包含以下组件：

messages.ts

navigation.ts

request.ts

routing.ts

en.json

zh.json

这种结构使得管理翻译并将其集成到您的应用程序中变得容易。

核心功能

与 next-intl 集成的多语言支持
带有语言前缀的国际化路由
支持不同语言的 UI 组件
支持不同语言的邮件模板
正确生成不同语言的 URL
基于用户偏好的自动语言检测
内置两种风格的多语言切换器组件：LocaleSelector 和 LocaleSwitcher

翻译文件

MkSaaS 使用 messages 目录下的 JSON 文件进行翻译，每种语言对应1个文件，遵循 [locale].json 的命名约定。

这些文件的结构是分层的，允许您按功能或组件组织各个模块的翻译：

messages/en.json

{
  "Metadata": {
    "name": "MkSaaS",
    "title": "MkSaaS - The Best AI SaaS Boilerplate",
    "description": "MkSaaS is the best AI SaaS boilerplate. Make AI SaaS in days, simply and effortlessly"
  },
  "Common": {
    "login": "Log in",
    "logout": "Log out",
    "signUp": "Sign up",
    "language": "Switch language"
  },
  "Mail": {
    "verifyEmail": {
      "title": "Hi, {name}.",
      "body": "Please click the link below to verify your email address.",
      "confirmEmail": "Confirm email",
      "subject": "Verify your email"
    }
  }
}

使用方法

在 React 组件中使用翻译

通过 useTranslations hook 可以在 React 组件中获取翻译内容：

import { useTranslations } from 'next-intl';

export function MyComponent() {
  const t = useTranslations();

  return (
    <div>
      <h1>{t('Common.login')}</h1>
      <p>{t('Common.signUp')}</p>
    </div>
  );
}

对于带参数的翻译：

<p>{t('Mail.verifyEmail.title', { name: 'John' })}</p>

在服务器组件中使用翻译

对于服务器组件，使用 getTranslations 函数获取翻译内容：

import { getTranslations } from 'next-intl/server';

export async function MyServerComponent() {
  const t = await getTranslations();

  return (
    <div>
      <h1>{t('Common.login')}</h1>
    </div>
  );
}

本地化链接和导航

使用 LocaleLink 组件创建符合当前语言设置的链接：

import { LocaleLink } from '@/i18n/navigation';

<LocaleLink href="/about">关于我们</LocaleLink>

对于程序化导航，使用 useLocaleRouter hook：

import { useLocaleRouter } from '@/i18n/navigation';

const router = useLocaleRouter();
router.push('/dashboard');

本地化邮件模板

MkSaaS 支持使用相同翻译系统发送本地化邮件：

src/mail/templates/verify-email.tsx

import type { BaseEmailProps } from '@/mail/types';
import { createTranslator } from 'use-intl/core';

interface VerifyEmailProps extends BaseEmailProps {
  url: string;
  name: string;
}

export function VerifyEmail({
  url,
  name,
  locale,
  messages,
}: VerifyEmailProps) {
  const t = createTranslator({
    locale,
    messages,
    namespace: 'Mail.verifyEmail',
  });

  return (
    <EmailLayout locale={locale} messages={messages}>
      <Text>{t('title', { name })}</Text>
      <Text>{t('body')}</Text>
      <EmailButton href={url}>{t('confirmEmail')}</EmailButton>
    </EmailLayout>
  );
}

发送本地化邮件：

await sendEmail({
  to: 'user@example.com',
  template: 'verifyEmail',
  context: {
    name: 'John Doe',
    url: 'https://example.com/verify?token=abc123',
  },
  locale: 'zh', // 为此邮件指定语言
});

语言组件

MkSaaS 内置两种不同的语言切换组件，为网站支持语言选择能力提供灵活性：

LocaleSelector (src/components/layout/locale-selector.tsx)
LocaleSwitcher (src/components/layout/locale-switcher.tsx)

两个组件都使用 UI 库中的 Select 组件提供下拉选择界面，您可以根据需要使用任一组件，或者自定义实现。

自定义

添加新语言

创建新的翻译文件：

在 messages 目录中创建一个新的 JSON 文件，文件名为您的语言代码（例如 fr.json）。

您可以从 en.json 复制结构并翻译所有值：

messages/fr.json

{
  "Metadata": {
    "name": "MkSaaS",
    "title": "MkSaaS - Le meilleur modèle SaaS AI",
    "description": "MkSaaS est le meilleur modèle SaaS AI. Créez un SaaS AI en quelques jours, simplement et sans effort"
  },
  // ... 其余翻译
}

更新网站配置：

在您的 website.tsx 配置中添加新语言：

src/config/website.tsx

i18n: {
  defaultLocale: 'en',
  locales: {
    en: {
      flag: '🇺🇸',
      name: 'English',
    },
    zh: {
      flag: '🇨🇳',
      name: '中文',
    },
    fr: {
      flag: '🇫🇷',
      name: 'Français',
    },
  },
},

处理不完整的翻译：

系统自动将翻译与默认语言合并，因此任何缺失的翻译都会回退到默认语言（通常是英语）。

仅支持一种语言

如果您只想在应用程序中支持一种语言：

在配置文件中仅保留您想要支持的语言：

src/config/website.tsx

i18n: {
  defaultLocale: 'en',
  locales: {
    en: {
      flag: '🇺🇸',
      name: 'English',
    },
    // 删除或注释掉其他语言
  },
},

在 messages 目录中仅保留相应的语言文件（例如 en.json）。
LocaleSelector 和 LocaleSwitcher 组件都会自动检测到只配置了一种语言，就不会在 UI 中渲染。这确保当不需要语言选择控件时，您的 UI 保持简洁，没有不必要的语言选择控件。

特殊语言考虑

MkSaaS 使用 Fumadocs 进行文档搜索功能，具有适当的国际化支持。对于有特殊要求的语言（如阿拉伯语），您可能需要配置其他设置：

src/app/api/search/route.ts

const searchAPI = createI18nSearchAPI('advanced', {
  // ...
  localeMap: {
    // 使用中文分词器的中文配置
    zh: {
      components: {
        tokenizer: createTokenizer(),
      },
      search: {
        threshold: 0,
        tolerance: 0,
      },
    },
    // 对其他语言使用默认分词器
    en: 'english',
    // 根据需要添加更多特定语言配置
  },
  // ...
});