Building a Dynamic Multilanguage System Without Rebuilds

The Problem

During a recent project, I needed to build a multilanguage system for a talent hiring platform. The challenge wasn't just supporting multiple languages—it was allowing content updates without rebuilding and redeploying the application. Traditional i18n solutions require code changes and rebuilds, but the client needed non-technical team members to update translations in real-time.

Requirements

Support multiple languages (English, Spanish, French, etc.)
Allow content updates without code deployments
Maintain type safety with TypeScript
Fast performance with minimal database queries
Support for nested translation keys
Admin panel for managing translations

Architecture Overview

The solution involved storing translations in a MySQL database, caching them in memory, and providing a REST API for the frontend. The admin panel uses Redux for state management, while the public-facing Next.js app fetches translations dynamically.

Database Schema

First, I designed a flexible database schema to store translations:

Translation Entity

// Translation Entity
@Entity('translations')
export class Translation {
@PrimaryGeneratedColumn()
id: number;

@Column({ type: 'varchar', length: 10 })
language: string; // 'en', 'es', 'fr', etc.

@Column({ type: 'varchar', length: 255 })
key: string; // 'home.title', 'button.submit', etc.

@Column({ type: 'text' })
value: string; // The actual translated text

@Column({ type: 'varchar', length: 50, nullable: true })
namespace: string; // Optional grouping: 'common', 'auth', 'dashboard'

@CreateDateColumn()
createdAt: Date;

@UpdateDateColumn()
updatedAt: Date;

@Index(['language', 'key', 'namespace'])
uniqueTranslation: string;
}

Backend Service Layer

The core service loads all translations into memory on startup and provides methods to retrieve them:

Translation Service

@Injectable()
export class TranslationService {
private translationsCache: Map<string, Map<string, string>> = new Map();
private cacheTimestamp: Date;

constructor(
  @InjectRepository(Translation)
  private translationRepository: Repository<Translation>,
) {}

async onModuleInit() {
  await this.loadTranslations();
  // Reload every 5 minutes to pick up changes
  setInterval(() => this.loadTranslations(), 5 * 60 * 1000);
}

private async loadTranslations() {
  const allTranslations = await this.translationRepository.find();
  const newCache = new Map<string, Map<string, string>>();

  for (const translation of allTranslations) {
    const langKey = translation.language;
    if (!newCache.has(langKey)) {
      newCache.set(langKey, new Map());
    }

    const key = translation.namespace 
      ? `${translation.namespace}.${translation.key}`
      : translation.key;
    
    newCache.get(langKey)!.set(key, translation.value);
  }

  this.translationsCache = newCache;
  this.cacheTimestamp = new Date();
}

getTranslation(language: string, key: string, namespace?: string): string {
  const langMap = this.translationsCache.get(language);
  if (!langMap) {
    return key; // Fallback to key if language not found
  }

  const fullKey = namespace ? `${namespace}.${key}` : key;
  return langMap.get(fullKey) || key;
}

getAllTranslations(language: string): Record<string, string> {
  const langMap = this.translationsCache.get(language);
  if (!langMap) {
    return {};
  }

  const result: Record<string, string> = {};
  langMap.forEach((value, key) => {
    result[key] = value;
  });
  return result;
}
}

API Controller

The controller exposes endpoints for fetching translations:

Translation Controller

@Controller('api/translations')
export class TranslationController {
constructor(private translationService: TranslationService) {}

@Get(':language')
@ApiOperation({ summary: 'Get all translations for a language' })
@ApiResponse({ status: 200, description: 'Translations retrieved successfully' })
async getTranslations(
  @Param('language') language: string,
): Promise<Record<string, string>> {
  return this.translationService.getAllTranslations(language);
}

@Get(':language/:key')
@ApiOperation({ summary: 'Get a specific translation' })
async getTranslation(
  @Param('language') language: string,
  @Param('key') key: string,
  @Query('namespace') namespace?: string,
): Promise<{ value: string }> {
  const value = this.translationService.getTranslation(
    language,
    key,
    namespace,
  );
  return { value };
}

@Post()
@UseGuards(JwtAuthGuard)
@ApiOperation({ summary: 'Create or update a translation' })
async createOrUpdateTranslation(
  @Body() dto: CreateTranslationDto,
): Promise<Translation> {
  const existing = await this.translationService.translationRepository.findOne({
    where: {
      language: dto.language,
      key: dto.key,
      namespace: dto.namespace || null,
    },
  });

  if (existing) {
    existing.value = dto.value;
    await this.translationService.translationRepository.save(existing);
    await this.translationService.loadTranslations(); // Refresh cache
    return existing;
  }

  const translation = this.translationService.translationRepository.create(dto);
  await this.translationService.translationRepository.save(translation);
  await this.translationService.loadTranslations(); // Refresh cache
  return translation;
}
}

Frontend Hook (Next.js)

On the frontend, I created a custom React hook to fetch and use translations:

useTranslation Hook

import { useState, useEffect, useCallback } from 'react';

interface UseTranslationOptions {
language: string;
namespace?: string;
}

export function useTranslation({ language, namespace }: UseTranslationOptions) {
const [translations, setTranslations] = useState<Record<string, string>>({});
const [loading, setLoading] = useState(true);

useEffect(() => {
  const fetchTranslations = async () => {
    try {
      const response = await fetch(
        `/api/translations/${language}${namespace ? `?namespace=${namespace}` : ''}`
      );
      const data = await response.json();
      setTranslations(data);
    } catch (error) {
      console.error('Failed to load translations:', error);
    } finally {
      setLoading(false);
    }
  };

  fetchTranslations();
}, [language, namespace]);

const t = useCallback(
  (key: string, params?: Record<string, string>): string => {
    const fullKey = namespace ? `${namespace}.${key}` : key;
    let translation = translations[fullKey] || key;

    // Simple parameter replacement: {{name}} -> value
    if (params) {
      Object.entries(params).forEach(([paramKey, value]) => {
        translation = translation.replace(
          new RegExp(`{{${paramKey}}}`, 'g'),
          value
        );
      });
    }

    return translation;
  },
  [translations, namespace]
);

return { t, loading, translations };
}

Usage in Components

Here's how you'd use it in a React component:

Component Usage

'use client';

import { useTranslation } from '@/hooks/useTranslation';
import { useLanguage } from '@/contexts/LanguageContext';

export function WelcomeBanner() {
const { language } = useLanguage();
const { t, loading } = useTranslation({ 
  language, 
  namespace: 'home' 
});

if (loading) {
  return <div>Loading...</div>;
}

return (
  <div>
    <h1>{t('title')}</h1>
    <p>{t('subtitle', { name: 'John' })}</p>
    <button>{t('button.cta')}</button>
  </div>
);
}

Language Context Provider

To manage the current language across the app:

Language Context

'use client';

import React, { createContext, useContext, useState, useEffect } from 'react';

interface LanguageContextType {
language: string;
setLanguage: (lang: string) => void;
availableLanguages: string[];
}

const LanguageContext = createContext<LanguageContextType | undefined>(undefined);

export function LanguageProvider({ children }: { children: React.ReactNode }) {
const [language, setLanguageState] = useState<string>('en');

useEffect(() => {
  // Load saved language from localStorage
  const saved = localStorage.getItem('preferred-language');
  if (saved) {
    setLanguageState(saved);
  }
}, []);

const setLanguage = (lang: string) => {
  setLanguageState(lang);
  localStorage.setItem('preferred-language', lang);
  // Optionally reload the page to fetch new translations
  window.location.reload();
};

const availableLanguages = ['en', 'es', 'fr', 'de'];

return (
  <LanguageContext.Provider value={{ language, setLanguage, availableLanguages }}>
    {children}
  </LanguageContext.Provider>
);
}

export function useLanguage() {
const context = useContext(LanguageContext);
if (!context) {
  throw new Error('useLanguage must be used within LanguageProvider');
}
return context;
}

Key Features

1. In-Memory Caching

Translations are loaded once on server startup and cached in memory. This eliminates database queries for every translation request, resulting in sub-millisecond response times.

2. Automatic Cache Refresh

The cache refreshes every 5 minutes, so updates appear within minutes without requiring a restart. For critical updates, the admin panel can trigger an immediate refresh.

3. Namespace Support

Translations can be organized into namespaces (like 'common', 'auth', 'dashboard'), making it easier to manage large applications and load only what's needed.

4. Type Safety

While the translations themselves are dynamic, the keys can be typed using TypeScript's template literal types for better IDE support and compile-time checking.

5. Fallback Mechanism

If a translation is missing, the system falls back to the translation key itself, ensuring the UI never breaks even if translations are incomplete.

Performance Optimizations

Bulk Loading: All translations for a language are fetched in a single API call
Client-Side Caching: Translations are cached in the browser's memory
Lazy Loading: Only load translations for the current language
CDN Caching: API responses can be cached at the CDN level for public endpoints

Admin Panel Integration

The admin panel built with Metronic and Redux allows non-technical users to:

View all translations in a table format
Edit translations inline
Add new languages
Search and filter translations
See which translations are missing for a language

When a translation is updated, the change is saved to the database, and the backend cache is refreshed automatically.

Results

This implementation provided:

Zero downtime for translation updates
Sub-second translation retrieval times
Easy content management for non-technical team members
Scalability to handle hundreds of languages and thousands of keys
Type safety with TypeScript support

Building a multilanguage system like this?

Let’s discuss architecture and edge cases.

Start a Conversation

Lessons Learned

Cache invalidation is crucial: The automatic refresh mechanism ensures updates propagate quickly without manual intervention.
Design for scale: Even if you start with 2 languages, design the system to handle 20+ languages from the beginning.
Provide fallbacks: Never let missing translations break the UI. Always have a fallback strategy.
Monitor translation coverage: Track which keys are missing translations for each language to ensure completeness.
Consider SEO: For public-facing pages, ensure URLs reflect the language (e.g., /en/about vs /es/about) for better SEO.

Conclusion

Building a dynamic multilanguage system without rebuilds requires careful architecture, but the benefits are significant. By storing translations in a database, caching them efficiently, and providing a clean API, we created a system that's both performant and flexible. The ability to update content without deployments has been a game-changer for the team, allowing faster iterations and better content management. This approach works well for applications that need frequent content updates, multiple languages, and non-technical content managers. For simpler use cases, traditional i18n libraries might be sufficient, but for enterprise applications, this database-driven approach provides the flexibility needed.