Skip to main content

​
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:
  1. Update configuration files
  2. Create translation files
  3. 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:
  1. Start your development server: 
    npm run dev
  2. Visit your application with the new locale path: 
    http://localhost:3000/fr
  3. Check that the content is displayed in the new language.
  4. 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:
  1. 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);
}
  1. 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>
  );
}
  1. 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

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.
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.
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
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:
  1. Update languine.json:
{
  "locale": {
    "source": "en",
    "targets": ["es", "de", "tr", "fr"]
  },
  "files": {
    "json": {
      "include": ["dictionaries/[locale].json"]
    }
  }
}
  1. Update i18nConfig.ts:
export const i18nConfig = {
  defaultLocale: 'en',
  locales: ['en', 'tr', 'es', 'de', 'fr'],
  localePrefix: 'as-needed'
}
  1. 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
  }
}
  1. Create locales/fr.json:
{
  "greeting": "Bonjour",
  "today": "Aujourd'hui est {date}"
}
  1. 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'
};

​
Next Steps

Advanced Usage

Advanced internationalization techniques

Troubleshooting

Common issues and solutions