i18n

MkSaaS uses next-intl for internationalization, allowing you to create multi-language applications with ease. With the built-in i18n support, you can create localized UI components, email templates, and more to provide a better experience for users worldwide.

Setup

Configuration

MkSaaS supports multiple languages through its i18n system.

Here's how to configure internationalization in website.tsx configuration file:

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

Internationalization System Structure

The internationalization system in MkSaaS is designed with the following components:

This structure makes it easy to manage translations and integrate them into your application.

Core Features

• Multi-language support with next-intl integration
• Internationalized routing with prefixed locales
• Localized UI components for consistent user experience
• Localized email templates for communication
• URL generation with proper locale handling
• Automatic language detection based on user preferences
• 2 built-in locale switcher components: LocaleSelector and LocaleSwitcher

Translation Files

MkSaaS uses JSON files for translations, located in the messages directory. Each language has its own file, following the naming convention [locale].json.

The structure of these files is hierarchical, allowing you to organize translations by feature or component:

{
  "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"
    }
  }
}

Usage

Using Translations in React Components

MkSaaS provides an easy way to use translations in your React components with the useTranslations hook:

import { useTranslations } from 'next-intl';

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

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

For translations with parameters:

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

Using Translations in Server Components

For server components, use the getTranslations function:

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

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

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

Localized Links and Navigation

To create links that respect the current locale, use the LocaleLink component:

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

<LocaleLink href="/about">About Us</LocaleLink>

For programmatic navigation:

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

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

Localized Email Templates

MkSaaS includes support for sending localized emails using the same translation system:

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

To send a localized email:

await sendEmail({
  to: 'user@example.com',
  template: 'verifyEmail',
  context: {
    name: 'John Doe',
    url: 'https://example.com/verify?token=abc123',
  },
  locale: 'zh', // Specify the locale for this email
});

Locale Components

MkSaaS provides two different locale switching components to give you flexibility in how you offer language selection to your users:

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

Both components provide a dropdown selection interface using the Select component from the UI library. You can use either component depending on your needs.

Customization

Adding a New Language

1. Create a new translation file:

   Create a new JSON file in the messages directory with the name of your locale (e.g., fr.json).

   You can copy the structure from en.json and translate all values:

   {
     "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"
     },
     // ... rest of translations
   }

2. Update the website configuration:

   Add the new locale to your website.tsx configuration:

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

3. Handle incomplete translations:

   The system automatically merges translations with the default language, so any missing translations will fall back to the default language (usually English).

Supporting Only One Language

If you only want to support one language in your application:

1. Keep only the language you want to support in the config file:

   i18n: {
     defaultLocale: 'en',
     locales: {
       en: {
         flag: '🇺🇸',
         name: 'English',
       },
       // Remove or comment out other languages
     },
   },

2. Keep only the corresponding language file in the messages directory (e.g., en.json).

3. Both LocaleSelector and LocaleSwitcher components will automatically detect that only one language is configured and will not render in the UI. This ensures your UI remains clean without unnecessary language selection controls when they aren't needed.

Special Language Considerations

MkSaaS uses Fumadocs for documentation search functionality with proper internationalization support. For languages with special requirements (like Arabic), you may need to configure additional settings:

const searchAPI = createI18nSearchAPI('advanced', {
  // ...
  localeMap: {
    // Chinese configuration with Mandarin tokenizer
    zh: {
      components: {
        tokenizer: createTokenizer(),
      },
      search: {
        threshold: 0,
        tolerance: 0,
      },
    },
    // Use default tokenizers for other languages
    en: 'english',
    // Add more language-specific configurations as needed
  },
  // ...
});

For languages like Chinese, the search system uses the Mandarin tokenizer to properly index and search content. This requires special configuration as shown above, with adjusted threshold and tolerance settings for optimal search results.

Development Tools

i18n-ally VSCode Extension

For a smoother development experience when working with internationalization, we highly recommend installing the i18n-ally extension for your IDE (Visual Studio Code, Cursor, etc.).

This powerful extension provides several benefits for multilingual application development:

• Inline Translation Preview: See translations directly in your code
• Missing Translation Detection: Highlights keys that are missing translations in certain languages
• Quick Translation Creation: Add new translations quickly with keyboard shortcuts
• Translation Management: Sort, rename, and refactor translation keys with ease
• Multiple Framework Support: Works with many i18n frameworks including next-intl
• Auto-completion: Suggests translation keys as you type
• Hover Information: View translations for all languages when hovering over a key

The extension integrates seamlessly with MkSaaS's internationalization structure and can significantly improve your workflow when managing translations across multiple languages.

Best Practices

1. Use namespace-based keys: Organize translations using namespaces to make them more maintainable.
2. Use parameters for dynamic content: Use parameters instead of string concatenation for dynamic content.
3. Keep translations concise: Avoid lengthy translations that may break your UI layout.
4. Consider context: Provide context in your keys to help translators understand how the text is used.
5. Test all languages: Always test your application in all supported languages to ensure a good experience.

Next Steps

Now that you understand how to work with internationalization in MkSaaS, you might want to explore these related features: