Translation Fallback Handler

A utility for managing missing translations in an internationalization system. The handler should track missing translation keys, provide fallback values, and allow custom handling strategies.

Capabilities

Tracks missing translation keys

The system should maintain a record of all translation keys that were requested but not found.

• When requesting a missing key "user.greeting", it is added to the missing keys list @test
• When requesting the same missing key multiple times, it only appears once in the missing keys list @test
• The missing keys list contains only unique entries across multiple lookups @test

Provides fallback values for missing translations

When a translation is not found, the system should have a configurable fallback strategy.

• When a translation key "app.title" is missing and no fallback is configured, return the key itself @test
• When a translation key "nav.home" is missing and a custom fallback function is configured, return the result of calling that function with the key @test
• When multiple fallback languages are configured ["en-US", "en", "de"] and the key exists in "en", return the value from "en" @test

Notifies when translations are missing

The system should allow registering listeners that are called when translations are not found.

• When a missing key event handler is registered and a key "error.404" is missing, the handler is called with the missing key information @test
• When multiple handlers are registered, all handlers are called when a key is missing @test

Retrieves missing keys for reporting

The system should provide access to the list of missing translation keys.

• Call a method to retrieve all missing keys that have been tracked @test
• After retrieving missing keys, the system can optionally clear the list for a fresh start @test

Implementation

@generates

API

/**
 * Creates a translation fallback handler instance.
 *
 * @param {Object} options - Configuration options
 * @param {Array<string>} options.fallbackLanguages - Array of language codes to try in order when a translation is missing
 * @param {Function} options.missingKeyHandler - Custom function to generate fallback values: (key, language) => string
 * @returns {Object} Handler instance with methods for managing missing translations
 */
function createFallbackHandler(options = {}) {
  // IMPLEMENTATION HERE
}

/**
 * Initialize the i18next instance with resources and configure missing translation handling.
 *
 * @param {Object} i18next - The i18next instance to configure
 * @param {Object} resources - Translation resources organized by language and namespace
 * @param {Object} fallbackHandler - The fallback handler created by createFallbackHandler
 */
function initializeI18next(i18next, resources, fallbackHandler) {
  // IMPLEMENTATION HERE
}

module.exports = {
  createFallbackHandler,
  initializeI18next
};

Dependencies { .dependencies }

i18next { .dependency }

Provides internationalization framework with translation, missing key events, and fallback configuration.

@satisfied-by