# How iloader Handles Localization and Adding New Languages

> Discover how iloader manages localization and adds new languages using i18next and react-i18next. Learn about dynamic imports and centralized language registry for seamless multilingual support.

- Repository: [Nicholas Sharp/iloader](https://github.com/nab138/iloader)
- Tags: how-to-guide
- Published: 2026-09-12

---

**iloader leverages the i18next and react-i18next libraries to deliver runtime translations, dynamically importing JSON locale files through Vite's `import.meta.glob` and managing supported languages through a centralized registry in [`src/i18next.ts`](https://github.com/nab138/iloader/blob/main/src/i18next.ts).**

The open-source project **nab138/iloader** implements a data-driven localization system that separates translation content from application logic. By utilizing the i18next ecosystem alongside Vite's module loading capabilities, iloader enables seamless language switching without requiring changes to the core React components. This architecture allows contributors to add new languages by simply dropping JSON files into the locales directory and updating a single configuration array.

## Core Localization Architecture in iloader

### Language Registry and Supported Codes

In [`src/i18next.ts`](https://github.com/nab138/iloader/blob/main/src/i18next.ts), the application defines its supported languages through a static `languages` constant spanning lines 5-33. This array contains tuples mapping language codes to human-readable names, establishing the canonical list of available locales that the application recognizes.

### Dynamic Resource Loading with Vite

Rather than manually importing each translation file, iloader utilizes Vite's `import.meta.glob` with `eager: true` on lines 41-46 to automatically discover and load all JSON files within `src/locales/*.json`. This glob import executes at build time, importing every translation module into the bundle without requiring explicit import statements for each language.

### i18next Initialization and Configuration

The imported JSON modules are transformed into the `resources` object that i18next expects, structured as `{ [lang]: { translation: <json> } }` (lines 48-55). The initialization occurs on lines 57-66 where i18next is configured with these generated resources, a browser language detector, and English set as the fallback language.

## How to Add a New Language to iloader

Adding support for a new language follows a straightforward, three-step process that requires no modifications to the runtime logic:

1. **Create the translation file.** Add a new JSON file named after the language code (e.g., [`fr_ca.json`](https://github.com/nab138/iloader/blob/main/fr_ca.json)) inside `src/locales/`. The file must mirror the key hierarchy found in existing translation files like [`en.json`](https://github.com/nab138/iloader/blob/main/en.json) to ensure all UI strings have corresponding translations.

2. **Register the language code.** Open [`src/i18next.ts`](https://github.com/nab138/iloader/blob/main/src/i18next.ts) and add an entry to the `languages` array, such as `["fr_ca", "Français (Canada)"]`. Because `import.meta.glob` automatically captures all `*.json` files in the directory, no additional import statements or loader modifications are necessary.

3. **Rebuild and deploy.** Restart the development server or trigger a production build. The glob import will include the new module in the bundle, the `resources` object will populate with the new translations, and the language selector UI will automatically display the new option via the `sortedLanguages` array reference.

## Implementing Translations in React Components

Components access the localization system through the `useTranslation` hook provided by react-i18next. The hook returns a `t` function that accepts dot-notation key paths to retrieve translated strings from the currently active locale.

```typescript
// src/pages/Settings.tsx example implementation
import { useTranslation } from 'react-i18next';
import i18n from '../i18next';

function LanguageSelector() {
  const { t } = useTranslation();

  const changeLang = (code: string) => {
    i18n.changeLanguage(code);
  };

  return (
    <select onChange={e => changeLang(e.target.value)} defaultValue={i18n.language}>
      {sortedLanguages.map(([code, name]) => (
        <option key={code} value={code}>
          {name}
        </option>
      ))}
    </select>
  );
}

```

To display translated content in any component, import `useTranslation` and invoke the translation function with the appropriate key:

```typescript
import { useTranslation } from 'react-i18next';

export function Header() {
  const { t } = useTranslation();

  return <h1>{t('app.language')}</h1>;
}

```

The `t('app.language')` call returns the localized string based on the currently active language, automatically falling back to English if the key is missing in the selected locale.

## Key Files in the Localization System

Understanding the iloader localization architecture requires familiarity with these specific files:

- **[`src/i18next.ts`](https://github.com/nab138/iloader/blob/main/src/i18next.ts)**: Contains the central i18next configuration, the dynamic loading logic for locale JSON files via `import.meta.glob`, and the `languages` array definition that controls available options.
- **`src/locales/*.json`**: Houses the translation dictionaries for each supported language (e.g., [`en.json`](https://github.com/nab138/iloader/blob/main/en.json), [`es.json`](https://github.com/nab138/iloader/blob/main/es.json)), with each file representing a complete set of UI strings for that locale.
- **[`src/pages/Settings.tsx`](https://github.com/nab138/iloader/blob/main/src/pages/Settings.tsx)**: Implements the language selector UI that calls `i18n.changeLanguage()` to switch locales at runtime and reflects the current selection.
- **[`package.json`](https://github.com/nab138/iloader/blob/main/package.json)**: Declares the localization dependencies including `i18next`, `react-i18next`, and `i18next-browser-languagedetector` which power the entire translation stack.

## Summary

- iloader uses **i18next** and **react-i18next** to manage runtime translations across the React application.
- Translation files are stored as JSON in `src/locales/` and loaded automatically using **Vite's `import.meta.glob`** with eager loading enabled.
- The `languages` array in [`src/i18next.ts`](https://github.com/nab138/iloader/blob/main/src/i18next.ts) serves as the single source of truth for supported language codes and their display names.
- Adding a new language requires only creating a JSON file and registering the code in the configuration array—no runtime code changes are necessary.
- Components consume translations via the **`useTranslation`** hook and switch languages programmatically using **`i18n.changeLanguage()`**.

## Frequently Asked Questions

### What localization libraries does iloader use?

iloader relies on the **i18next** ecosystem, specifically combining the core `i18next` library with `react-i18next` for React integration and `i18next-browser-languagedetector` to automatically identify the user's preferred language from browser settings. These dependencies are declared in [`package.json`](https://github.com/nab138/iloader/blob/main/package.json) and initialized in [`src/i18next.ts`](https://github.com/nab138/iloader/blob/main/src/i18next.ts).

### Where should I place new translation files in the iloader repository?

Place new translation files inside the `src/locales/` directory. Name the file using the language code (e.g., [`de.json`](https://github.com/nab138/iloader/blob/main/de.json) for German or [`pt_br.json`](https://github.com/nab138/iloader/blob/main/pt_br.json) for Brazilian Portuguese) and ensure it contains the same key structure as the existing [`en.json`](https://github.com/nab138/iloader/blob/main/en.json) file to maintain translation coverage across all UI elements.

### Do I need to modify import statements when adding a new language to iloader?

No. The system uses **`import.meta.glob`** in [`src/i18next.ts`](https://github.com/nab138/iloader/blob/main/src/i18next.ts) to automatically discover and import all JSON files in the locales directory at build time. You only need to add the language code and display name to the `languages` array in [`src/i18next.ts`](https://github.com/nab138/iloader/blob/main/src/i18next.ts) to register it for use in the application.

### How does iloader handle missing translations?

iloader initializes i18next with English (`en`) as the fallback language according to the configuration in [`src/i18next.ts`](https://github.com/nab138/iloader/blob/main/src/i18next.ts). If a translation key is missing in the active locale, i18next automatically returns the English equivalent. If the key is also missing in English, the system returns the key path itself as the fallback string.