Internationalization (i18n)
Relevant source files
The following files were used as context for generating this wiki page:
The internationalization (i18n) system in medical-calculators is designed to provide multi-language support for the user interface. It is built using React's Context API to manage the current language and provide translation functions to components throughout the application. The system is self-contained within the src/i18n directory and is integrated at the application's root level.
Currently, the application supports three languages: English (en), Russian (ru), and Ukrainian (uk). The architecture is straightforward, consisting of a central translation object, a React context provider, a custom hook for consuming the context, and a UI component for language selection.
Sources: src/i18n/translations.ts:1, src/i18n/LanguageContext.tsx
Architecture
The i18n architecture is based on a provider-consumer pattern using React Context. The LanguageProvider wraps the entire application, holding the state for the currently selected language. Components that need to display translated text use the useLanguage hook to access the translation function (t), which retrieves the appropriate string from a central translations object based on the current language.
The following diagram illustrates the data flow and component relationships within the i18n system.
This diagram shows that LanguageProvider wraps the application, getting data from translations.ts. Components like LanguageSelector and other pages use the useLanguage hook to interact with the LanguageContext to get or set the language.
Sources: src/app/layout.tsx:32-34, src/i18n/LanguageContext.tsx:10-33, src/components/LanguageSelector.tsx:5, src/app/page.tsx:11
Core Components
LanguageContext and LanguageProvider
The core of the i18n system is the LanguageContext. The LanguageProvider component manages the language state and provides the context to its children.
- State Management: It uses
useStateto manage thelanguagestate, which defaults to'en'. - Translation Function (
t): It provides a functiontthat takes a key of typekeyof Translationsand returns the corresponding string for the current language from thetranslationsobject. - Context Value: The context provides an object containing the current
language, thesetLanguagefunction to update it, and thetfunction for translations.
The context value has the following structure:
| Property | Type | Description |
|---|---|---|
language | Language ('en' | 'ru' | 'uk') | The currently active language code. |
setLanguage | Dispatch<SetStateAction<Language>> | A function to update the current language. |
t | (key: keyof Translations) => string | The translation function that returns a string for a given translation key. |
Sources: src/i18n/LanguageContext.tsx:6-33
The LanguageProvider is implemented in the root layout, ensuring that the entire application has access to the i18n context.
// src/app/layout.tsx:30-36
export default function RootLayout({
children,
}: Readonly<{
children: React.ReactNode;
}>) {
return (
<html lang="en" className="h-full">
<body
className={`${geistSans.variable} ${geistMono.variable} antialiased h-full`}
>
<div className="flex flex-col min-h-full">
<LanguageProvider>
{children}
</LanguageProvider>
</div>
</body>
</html>
);
}
Sources: src/app/layout.tsx:32-34
translations.ts
This file is the single source of truth for all translated strings in the application.
LanguageType: Defines the supported language codes:'en','ru', and'uk'.TranslationsInterface: Defines the shape of the translation object, ensuring that all languages have the same set of keys. This provides type safety when accessing translations.translationsObject: ARecord<Language, Translations>that maps each language code to its corresponding object of translated strings.
Example structure of the translations object:
// src/i18n/translations.ts:1, 290, 683
export type Language = 'en' | 'ru' | 'uk';
export interface Translations {
// ...
home: string;
welcome: string;
calculate: string;
// ...
}
export const translations: Record<Language, Translations> = {
en: {
home: 'Home',
welcome: 'Welcome to MDcalc',
calculate: 'Calculate',
// ... all other English translations
},
ru: {
home: 'Главная',
welcome: 'Добро пожаловать в MDcalc',
calculate: 'Рассчитать',
// ... all other Russian translations
},
uk: {
// ... all Ukrainian translations
},
};
Sources: src/i18n/translations.ts:1-1103
LanguageSelector.tsx
This is a UI component that allows the user to switch the application's language.
- It uses the
useLanguagehook to get the currentlanguageand thesetLanguagefunction. - It maintains an internal
isOpenstate to toggle the visibility of the language dropdown menu. - It renders a button displaying the current language's flag and name.
- When a new language is selected from the dropdown, it calls
setLanguagewith the new language code, which updates the context and causes the application to re-render with the new translations.
The following sequence diagram shows the process of a user changing the language.
Sources: src/components/LanguageSelector.tsx
Usage
Components that require translated text use the useLanguage custom hook to access the translation function t.
useLanguage Hook
This hook is a simple wrapper around React.useContext that provides a convenient way to access the LanguageContextValue. It throws an error if used outside of a LanguageProvider, ensuring it is always used correctly within the application structure.
// src/i18n/LanguageContext.tsx:35-41
export const useLanguage = () => {
const context = useContext(LanguageContext);
if (context === undefined) {
throw new Error('useLanguage must be used within a LanguageProvider');
}
return context;
};
Sources: src/i18n/LanguageContext.tsx:35-41
Example Implementation
Components like page.tsx and PediatricDoseCalculator.tsx demonstrate how to consume the context.
- Import the hook:
import { useLanguage } from '@/i18n/LanguageContext'; - Call the hook:
const { t } = useLanguage(); - Use the
tfunction:<h3>{t.electrolyteCorrection}</h3>
// src/app/page.tsx:11, 153
'use client';
// ... imports
import { useLanguage } from '@/i18n/LanguageContext';
export default function Home() {
// ...
const { t } = useLanguage();
return (
// ... JSX
<h3 className="text-xl font-semibold text-primary group-hover:text-primary/80 transition-colors">
{t.electrolyteCorrection}
</h3>
// ...
);
}
This pattern is repeated across all components that need to display dynamic, translated text, such as titles, labels, and buttons.
Sources: src/app/page.tsx:11, 153, src/calculators/PediatricDoseCalculator.tsx:10, 313