LibreChat/client/src/locales/README.md

LibreChat Localization Guide

This guide explains how to add new languages to LibreChat's localization system.

Adding a New Language

To add a new language to LibreChat, follow these steps:

1. Add the Language to Locize Project

• Navigate to the LibreChat locize project,
• Click the "ADD LANGUAGE" button, typically found within the "..." menu of the "Start to translate" card on the project overview page.

2. Update the Language Selector Component

Edit client/src/components/Nav/SettingsTabs/General/General.tsx and add your new language option to the languageOptions array:

{ value: 'language-code', label: localize('com_nav_lang_language_name') },

Example:

{ value: 'bo', label: localize('com_nav_lang_tibetan') },
{ value: 'uk-UA', label: localize('com_nav_lang_ukrainian') },

Note: Use the appropriate language code format:

• Use simple codes (e.g., bo) for languages without regional variants
• Use region-specific codes (e.g., uk-UA) when needed

3. Add Localization Keys

In client/src/locales/en/translation.json, add the corresponding localization key for your language label:

"com_nav_lang_language_name": "Native Language Name",

Example:

"com_nav_lang_tibetan": "བོད་སྐད་",
"com_nav_lang_ukrainian": "Українська",

Best Practice: Use the native language name as the value.

4. Create the Translation File

Create a new directory and translation file:

mkdir -p client/src/locales/[language-code]

Create client/src/locales/[language-code]/translation.json with an empty JSON object:

{
}

Example:

• client/src/locales/bo/translation.json
• client/src/locales/uk/translation.json

5. Configure i18n

Update client/src/locales/i18n.ts:

1. Import the new translation file:

import translationLanguageCode from './language-code/translation.json';

2. Add it to the resources object:

export const resources = {
  // ... existing languages
  'language-code': { translation: translationLanguageCode },
} as const;

Example:

import translationBo from './bo/translation.json';
import translationUk from './uk/translation.json';

export const resources = {
  // ... existing languages
  bo: { translation: translationBo },
  uk: { translation: translationUk },
} as const;

6. Handle Fallback Languages (Optional)

If your language should fall back to a specific language when translations are missing, update the fallbackLng configuration in i18n.ts:

fallbackLng: {
  'language-variant': ['fallback-language', 'en'],
  // ... existing fallbacks
},

Translation Process

After adding a new language:

1. The empty translation file will be populated through LibreChat's automated translation platform
2. Only the English (en) translation file should be manually updated
3. Other language translations are managed externally

Language Code Standards

• Use ISO 639-1 codes for most languages (e.g., en, fr, de)
• Use ISO 639-1 with region codes when needed (e.g., pt-BR, zh-Hans)
• Tibetan uses bo (Bodic)
• Ukrainian uses uk or uk-UA with region

Testing

After adding a new language:

1. Restart the development server
2. Navigate to Settings > General
3. Verify your language appears in the dropdown
4. Select it to ensure it changes the UI language code

Notes

• Keep language options alphabetically sorted in the dropdown for better UX
• Always use native script for language names in the dropdown
• The system will use English as fallback for any missing translations