Internationalization (i18n)

​

Current Language Support

• English (en) - Default language
• Chinese Simplified (zh) - Full translation available

​

Project Structure

apps/frontend/
├── app/
│   └── [locale]/                  # Locale-based routing
│       ├── layout.tsx            # Locale layout
│       ├── (sidebar)/            # Sidebar layout group
│       └── ...
├── public/locales/
│   ├── en/                       # English translations
│   │   ├── common.json
│   │   ├── auth.json
│   │   ├── navigation.json
│   │   ├── mcp-servers.json
│   │   ├── namespaces.json
│   │   ├── endpoints.json
│   │   ├── api-keys.json
│   │   ├── settings.json
│   │   ├── search.json
│   │   ├── inspector.json
│   │   ├── logs.json
│   │   └── validation.json
│   └── zh/                       # Chinese translations
│       └── (same structure)
├── lib/
│   └── i18n.ts                  # Client-side i18n utilities
├── hooks/
│   ├── useLocale.ts             # Hook to get current locale
│   └── useTranslations.ts       # Hook for client-side translations
├── components/
│   └── language-switcher.tsx    # Language switching component
└── middleware.ts                # Locale detection and routing

​

How It Works

​

URL Structure

• English (default): /mcp-servers, /settings, /namespaces
• Chinese: /zh/mcp-servers, /zh/settings, /zh/namespaces

​

Middleware

• Locale detection from URL, cookies, and Accept-Language header
• Automatic redirects to appropriate locale
• Authentication checks

import { NextRequest } from 'next/server';
import { getLocale, getLocalizedPath } from '@/lib/i18n';

export function middleware(request: NextRequest) {
  // Detect locale from URL, cookie, or headers
  const locale = getLocale(request);
  
  // Redirect if needed
  if (!request.nextUrl.pathname.startsWith(`/${locale}`)) {
    const localizedPath = getLocalizedPath(request.nextUrl.pathname, locale);
    return Response.redirect(new URL(localizedPath, request.url));
  }
}

​

Using Translations

​

Client Components

"use client";

import { useTranslations } from "@/hooks/useTranslations";

function ClientComponent() {
  const { t, isLoading, locale } = useTranslations();
  
  if (isLoading) return <div>Loading...</div>;
  
  return (
    <div>
      <h1>{t('common:title')}</h1>
      <button>{t('auth:signIn')}</button>
    </div>
  );
}

​

Translation Key Format

{
  "server": {
    "create": "Create Server",
    "edit": "Edit Server",
    "delete": "Delete Server",
    "status": {
      "online": "Online",
      "offline": "Offline",
      "error": "Error"
    },
    "validation": {
      "nameRequired": "Server name is required",
      "commandRequired": "Command is required"
    }
  }
}

​

Translation File Organization

​

Namespace Structure

​

Best Practices for Translation Keys

​

Adding New Languages

​

Step 1: Create Translation Files

1. Create language directory in public/locales/:
   Copy

   mkdir -p public/locales/es  # For Spanish
   

2. Copy English files as templates:
   Copy

   cp -r public/locales/en/* public/locales/es/
   

3. Translate the content in each JSON file:
   Copy

   // public/locales/es/common.json
   {
     "actions": {
       "save": "Guardar",
       "cancel": "Cancelar",
       "delete": "Eliminar",
       "edit": "Editar",
       "create": "Crear"
     }
   }
   

​

Step 2: Update Configuration

export const SUPPORTED_LOCALES = ['en', 'zh', 'es'] as const;
export type Locale = typeof SUPPORTED_LOCALES[number];

export const LOCALE_NAMES: Record<Locale, string> = {
  en: 'English',
  zh: '中文',
  es: 'Español'
};

​

Step 3: Update Language Switcher

// components/language-switcher.tsx
import { LOCALE_NAMES, SUPPORTED_LOCALES } from '@/lib/i18n';

export function LanguageSwitcher() {
  return (
    <select>
      {SUPPORTED_LOCALES.map(locale => (
        <option key={locale} value={locale}>
          {LOCALE_NAMES[locale]}
        </option>
      ))}
    </select>
  );
}

​

Step 4: Test the Implementation

1. Add test content in the new language
2. Navigate to /{locale}/ URLs (e.g., /es/mcp-servers)
3. Verify translations appear correctly
4. Test language switching functionality
5. Check fallbacks work for missing translations

​

Translation Workflow

​

For New Features

1. Add English translations first in appropriate namespace
2. Use descriptive keys that make sense in context
3. Test with English to ensure keys work correctly
4. Add other languages (or mark for translation)
5. Test all languages before deployment

​

For Contributors

​

Troubleshooting

​

Common Issues

​

Debugging Tools

# Check for missing translation keys
grep -r "t('" apps/frontend/app --include="*.tsx" | \
  grep -v "useTranslations"

# Validate JSON files
for file in public/locales/*/*.json; do
  echo "Checking $file"
  cat "$file" | jq . > /dev/null
done

​

Future Enhancements

​

Planned Features

• RTL language support for Arabic, Hebrew
• Date/time localization with proper formatting
• Number formatting based on locale
• Currency formatting for pricing features
• Pluralization rules for complex language requirements

​

Contributing Guidelines

​

Next Steps