Adding New Languages

This guide explains how to add support for new languages to your application using the internationalization package.

Overview

The internationalization package currently supports English (en), Turkish (tr), Spanish (es), and German (de). You can add support for additional languages by following these steps:

Update configuration files
Create translation files
Test the new language

Step 1: Update Configuration Files

First, you need to update the configuration files to include the new language:

Update languine.json

Add the new language code to the targets array in languine.json:

{
  "locale": {
    "source": "en",
    "targets": ["es", "de", "tr", "fr"] // Added "fr" for French
  },
  "files": {
    "json": {
      "include": ["dictionaries/[locale].json"]
    }
  }
}

Update i18nConfig.ts

Add the new language code to the locales array in i18nConfig.ts:

export const i18nConfig = {
  defaultLocale: 'en',
  locales: ['en', 'tr', 'es', 'de', 'fr'], // Added "fr" for French
  localePrefix: 'as-needed'
}

Step 2: Create Translation Files

You need to create translation files for the new language in both the dictionaries and locales directories:

Create Dictionary File

Create a new file in the dictionaries directory with the name of your language code:

# Example for French
touch dictionaries/fr.json

Then, copy the structure from the English dictionary file and translate the content:

{
  "web": {
    "global": {
      "primaryCta": "Réserver un appel",
      "secondaryCta": "S'inscrire"
    },
    "header": {
      "home": "Accueil",
      "product": {
        "title": "Produit",
        "description": "Gérer une petite entreprise aujourd'hui est déjà difficile.",
        "pricing": "Tarification"
      },
      "blog": "Blog",
      "docs": "Documentation",
      "contact": "Contact",
      "signIn": "Se connecter",
      "signUp": "Commencer"
    },
    // ... translate all other entries
  }
}

Start by translating the most important sections first, such as navigation, common buttons, and main page content. You can gradually translate the rest of the content over time.

Create Locale File

Create a new file in the locales directory with the name of your language code:

# Example for French
touch locales/fr.json

Then, add the basic translations:

{
  "greeting": "Bonjour",
  "today": "Aujourd'hui est {date}"
}

Step 3: Generate Translations (Optional)

If you have a large number of translations, you can use the built-in translation script to generate translations automatically:

npm run translate

This will use the Languine tool to generate translations for all target languages based on the source language (English).

Automatically generated translations may not be perfect. Always review and edit them for accuracy and cultural appropriateness.

Step 4: Test the New Language

After adding the new language, test it to make sure everything works correctly:

Start your development server:
npm run dev
Visit your application with the new locale path:
http://localhost:3000/fr
Check that the content is displayed in the new language.
Test navigation, forms, and other interactive elements to ensure translations are applied correctly.

Handling Special Characters and RTL Languages

Special Characters

Some languages use special characters that may require specific handling:

// Make sure your HTML has the correct charset
<html lang={locale} dir={isRTL(locale) ? 'rtl' : 'ltr'}>
  <head>
    <meta charSet="UTF-8" />
    {/* Other head elements */}
  </head>
  <body>
    {/* Content */}
  </body>
</html>

Right-to-Left (RTL) Languages

For languages that are read from right to left (like Arabic or Hebrew), you need to add additional support:

Create a helper function to identify RTL languages:

// utils/language.ts
export function isRTL(locale: string): boolean {
  const rtlLocales = ['ar', 'he', 'fa', 'ur'];
  return rtlLocales.includes(locale);
}

Update your layout to apply RTL direction when needed:

// app/[locale]/layout.tsx
import { getDictionary } from '@repo/internationalization';
import { isRTL } from '@/utils/language';

export default async function RootLayout({ 
  children, 
  params 
}: { 
  children: React.ReactNode;
  params: { locale: string };
}) {
  const dictionary = await getDictionary(params.locale);
  
  return (
    <html lang={params.locale} dir={isRTL(params.locale) ? 'rtl' : 'ltr'}>
      <body>
        {/* Layout content */}
        {children}
      </body>
    </html>
  );
}

Add CSS to handle RTL styling:

/* For RTL languages */
[dir="rtl"] {
  text-align: right;
}

[dir="rtl"] .some-component {
  margin-left: 0;
  margin-right: 1rem;
}

Best Practices for Multilingual Content

Use Variables for Dynamic Content

Instead of hardcoding values in your translations, use variables:

// Good
"welcome": "Welcome to {appName}"

// Not good
"welcome": "Welcome to MyApp"

This makes it easier to maintain consistent branding across all languages.

Consider Cultural Differences

Be aware that some phrases or concepts may not translate directly between cultures:

Date formats (MM/DD/YYYY vs. DD/MM/YYYY)
Number formats (1,000.00 vs. 1.000,00)
Currency symbols and positions
Cultural references and idioms

Always have native speakers review your translations.

Plan for Text Expansion

Some languages require more space than English. German words can be 30% longer, while some Asian languages may be more compact.Design your UI to accommodate text of varying lengths:

Avoid fixed-width containers for text
Test your UI with the longest translations
Use ellipsis or truncation for very long text

Keep Translation Keys Organized

Organize your translation keys logically by feature or page:

{
  "auth": {
    "login": { ... },
    "register": { ... }
  },
  "dashboard": {
    "overview": { ... },
    "stats": { ... }
  }
}

This makes it easier to find and update translations.

Examples

Adding French Language Support

Here’s a complete example of adding French language support:

Update languine.json:

{
  "locale": {
    "source": "en",
    "targets": ["es", "de", "tr", "fr"]
  },
  "files": {
    "json": {
      "include": ["dictionaries/[locale].json"]
    }
  }
}

Update i18nConfig.ts:

export const i18nConfig = {
  defaultLocale: 'en',
  locales: ['en', 'tr', 'es', 'de', 'fr'],
  localePrefix: 'as-needed'
}

Create dictionaries/fr.json with translated content:

{
  "web": {
    "global": {
      "primaryCta": "Réserver un appel",
      "secondaryCta": "S'inscrire"
    },
    "header": {
      "home": "Accueil",
      "product": {
        "title": "Produit",
        "description": "Gérer une petite entreprise aujourd'hui est déjà difficile.",
        "pricing": "Tarification"
      },
      "blog": "Blog",
      "docs": "Documentation",
      "contact": "Contact",
      "signIn": "Se connecter",
      "signUp": "Commencer"
    }
    // ... more translations
  }
}

Create locales/fr.json:

{
  "greeting": "Bonjour",
  "today": "Aujourd'hui est {date}"
}

Update your language switcher to include French:

const localeNames: Record<string, string> = {
  en: 'English',
  tr: 'Türkçe',
  es: 'Español',
  de: 'Deutsch',
  fr: 'Français'
};

Introduction

Setup

CLI

Internationalization

Deployment

Adding Languages

Adding New Languages

Overview

Step 1: Update Configuration Files

Update languine.json

Update i18nConfig.ts

Step 2: Create Translation Files

Create Dictionary File

Create Locale File

Step 3: Generate Translations (Optional)

Step 4: Test the New Language

Handling Special Characters and RTL Languages

Special Characters

Right-to-Left (RTL) Languages

Best Practices for Multilingual Content

Examples

Adding French Language Support

Next Steps

Advanced Usage

Troubleshooting

​Adding New Languages

​Overview

​Step 1: Update Configuration Files

​Update languine.json

​Update i18nConfig.ts

​Step 2: Create Translation Files

​Create Dictionary File

​Create Locale File

​Step 3: Generate Translations (Optional)

​Step 4: Test the New Language

​Handling Special Characters and RTL Languages

​Special Characters

​Right-to-Left (RTL) Languages

​Best Practices for Multilingual Content

​Examples

​Adding French Language Support

​Next Steps

Advanced Usage

Troubleshooting

Adding New Languages

Overview

Step 1: Update Configuration Files

Update languine.json

Update i18nConfig.ts

Step 2: Create Translation Files

Create Dictionary File

Create Locale File

Step 3: Generate Translations (Optional)

Step 4: Test the New Language

Handling Special Characters and RTL Languages

Special Characters

Right-to-Left (RTL) Languages

Best Practices for Multilingual Content

Examples

Adding French Language Support

Next Steps