> ## Documentation Index > Fetch the complete documentation index at: https://docs.zopio.dev/llms.txt > Use this file to discover all available pages before exploring further. # Adding Languages > How to add support for new languages # 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`: ```json theme={"system"} { "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`: ```typescript theme={"system"} 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: ```bash theme={"system"} # Example for French touch dictionaries/fr.json ``` Then, copy the structure from the English dictionary file and translate the content: ```json theme={"system"} { "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: ```bash theme={"system"} # Example for French touch locales/fr.json ``` Then, add the basic translations: ```json theme={"system"} { "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: ```bash theme={"system"} 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: ```bash theme={"system"} 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: ```typescript theme={"system"} // Make sure your HTML has the correct charset {/* Other head elements */} {/* Content */} ``` ### 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: ```typescript theme={"system"} // utils/language.ts export function isRTL(locale: string): boolean { const rtlLocales = ['ar', 'he', 'fa', 'ur']; return rtlLocales.includes(locale); } ``` 2. Update your layout to apply RTL direction when needed: ```tsx theme={"system"} // 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 ( {/* Layout content */} {children} ); } ``` 3. Add CSS to handle RTL styling: ```css theme={"system"} /* 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: ```json theme={"system"} // 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: ```json theme={"system"} { "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`: ```json theme={"system"} { "locale": { "source": "en", "targets": ["es", "de", "tr", "fr"] }, "files": { "json": { "include": ["dictionaries/[locale].json"] } } } ``` 2. Update `i18nConfig.ts`: ```typescript theme={"system"} export const i18nConfig = { defaultLocale: 'en', locales: ['en', 'tr', 'es', 'de', 'fr'], localePrefix: 'as-needed' } ``` 3. Create `dictionaries/fr.json` with translated content: ```json theme={"system"} { "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 } } ``` 4. Create `locales/fr.json`: ```json theme={"system"} { "greeting": "Bonjour", "today": "Aujourd'hui est {date}" } ``` 5. Update your language switcher to include French: ```tsx theme={"system"} const localeNames: Record = { en: 'English', tr: 'Türkçe', es: 'Español', de: 'Deutsch', fr: 'Français' }; ``` ## Next Steps Advanced internationalization techniques Common issues and solutions