How iloader Handles Localization and Adding New Languages

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.

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, 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) inside src/locales/. The file must mirror the key hierarchy found in existing translation files like en.json to ensure all UI strings have corresponding translations.

2. Register the language code. Open 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.

// 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:

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: 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, es.json), with each file representing a complete set of UI strings for that locale.
• 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: 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 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 and initialized in 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 for German or pt_br.json for Brazilian Portuguese) and ensure it contains the same key structure as the existing 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 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 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. 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}