Internationalization (i18n) Library

The i18n library provides comprehensive internationalization support for your RedM framework, allowing you to manage multiple languages and translations across your resources.

Overview

The i18n system supports:

Multi-language translation management
Server and client-side operation
Automatic language detection
KVP (Key-Value Pair) storage for persistence
Dynamic language switching
Parameterized translations

Global Variables

lang: Current active language (default: 'en')
languageCache: Cached translation data
avalLangs: Array of available languages
IS_SERVER: Boolean indicating server context
RESOURCE_NAME: Current resource name

Core Functions

`i18n.getCurrentLanguage`

Returns the currently active language code.

Returns: String representing the current language

Example:

local currentLang = i18n.getCurrentLanguage()
print("Current language: " .. currentLang)  -- Output: "Current language: en"

`i18n.setLang`

Changes the active language.

Parameters:

language (string): Language code to switch to

Example:

i18n.setLang('es')  -- Switch to Spanish

`i18n.importData`

Imports translation data for a specific language.

Parameters:

language (string): Language code
translationData (table): Translation data structure

Translation Data Structure:

-- Method 1: Simple flat structure
local translations = {
    greeting = "Hello",
    farewell = "Goodbye"
}

-- Method 2: Prefixed structure  
local translations = {
    ui = {
        button_save = "Save",
        button_cancel = "Cancel"
    },
    messages = {
        success = "Operation completed successfully",
        error = "An error occurred"
    }
}

Example:

-- Import English translations
i18n.importData('en', {
    ui = {
        welcome = "Welcome to the server!",
        goodbye = "Thank you for playing!"
    },
    info = {
        language_changed = "Language changed successfully"
    }
})

-- Import Spanish translations
i18n.importData('es', {
    ui = {
        welcome = "¡Bienvenido al servidor!",
        goodbye = "¡Gracias por jugar!"
    },
    info = {
        language_changed = "Idioma cambiado exitosamente"
    }
})

`i18n.exportData`

Exports all cached translation data.

Returns: Table containing all language data

Example:

local allTranslations = i18n.exportData()
-- Use this for debugging or data migration

`i18n.translate`

Translates a key to the current language with optional parameter formatting.

Parameters:

key (string): Translation key in dot notation (prefix.label)
... (variable): Parameters for string formatting

Returns: Translated string

Key Formats:

"prefix.label" - Nested key access
"simple_key" - Direct key access
If no key provided, returns all translations for current language

Parameter Formatting: Supports both individual parameters and table parameters for string formatting.

Examples:

-- Basic translation
local welcome = i18n.translate('ui.welcome')
print(welcome)  -- Output: "Welcome to the server!"

-- Translation with parameters
i18n.importData('en', {
    messages = {
        player_joined = "Player %s joined the server with ID %d"
    }
})

local message = i18n.translate('messages.player_joined', 'John', 123)
print(message)  -- Output: "Player John joined the server with ID 123"

-- Translation with table parameters
local params = {"Alice", 456}
local message2 = i18n.translate('messages.player_joined', params)

Automatic Features

Language Persistence

On the client-side, the library automatically:

Saves language preferences to KVP storage
Loads saved language on resource start
Syncs language changes across resources

FiveM Integration

The library integrates with FiveM's resource system:

Automatic resource detection
Cross-resource language synchronization
Event-driven language updates

Events

`FRP:SetLanguage`

Triggered when the language is changed.

Parameters:

language (string): New language code

Example:

-- Manually trigger language change
TriggerEvent('FRP:SetLanguage', 'fr')

-- Listen for language changes
AddEventHandler('FRP:SetLanguage', function(newLanguage)
    print("Language changed to: " .. newLanguage)
end)

Error Handling

The library includes robust error handling:

Returns "Error 502 : no translation available !" when language cache is unavailable
Falls back to the original key when translation is not found
Handles missing translation gracefully

Example:

-- If translation doesn't exist
local missing = i18n.translate('nonexistent.key')
print(missing)  -- Output: "nonexistent.key"

Utility Functions

`mysplit(inputstr, separator)`

Internal utility function for splitting strings (used for parsing dot notation keys).

Parameters:

inputstr (string): String to split
separator (string, optional): Separator character (default: whitespace)

Returns: Table array of split strings

Usage Patterns

Setting Up Translations

-- 1. Initialize the system
i18n.setup('en')

-- 2. Import translations for multiple languages
local englishTranslations = {
    ui = {
        title = "Game Interface",
        buttons = {
            save = "Save",
            load = "Load",
            exit = "Exit"
        }
    },
    notifications = {
        saved = "Game saved successfully!",
        loaded = "Game loaded successfully!",
        error = "An error occurred: %s"
    }
}

local spanishTranslations = {
    ui = {
        title = "Interfaz del Juego", 
        buttons = {
            save = "Guardar",
            load = "Cargar", 
            exit = "Salir"
        }
    },
    notifications = {
        saved = "¡Juego guardado exitosamente!",
        loaded = "¡Juego cargado exitosamente!",
        error = "Ocurrió un error: %s"
    }
}

i18n.importData('en', englishTranslations)
i18n.importData('es', spanishTranslations)

Using Translations in Code

-- Basic usage
local title = i18n.translate('ui.title')
local saveButton = i18n.translate('ui.buttons.save')

-- With parameters
local errorMsg = i18n.translate('notifications.error', 'File not found')

-- Dynamic language switching
function changeLanguage(newLang)
    i18n.setLang(newLang)
    TriggerEvent('FRP:SetLanguage', newLang)
    
    -- Update UI elements
    updateInterfaceTexts()
end

function updateInterfaceTexts()
    local title = i18n.translate('ui.title')
    -- Update your UI with the new translations
end

Client-Server Language Sync

-- Client-side: Request language change
function requestLanguageChange(language)
    TriggerServerEvent('server:changeLanguage', language)
end

-- Server-side: Handle language change
RegisterServerEvent('server:changeLanguage')
AddEventHandler('server:changeLanguage', function(language)
    local src = source
    -- Validate language
    if isValidLanguage(language) then
        TriggerClientEvent('FRP:SetLanguage', src, language)
    end
end)

Best Practices

Consistent Key Naming: Use consistent prefixes and naming conventions

-- Good
ui.buttons.save
ui.buttons.cancel
messages.errors.file_not_found

-- Avoid
SaveButton
cancel_btn
FileError

Parameterized Strings: Use parameters for dynamic content

-- Good
welcome_message = "Welcome %s! You have %d coins."

-- Avoid hardcoding values
welcome_john = "Welcome John! You have 100 coins."

Fallback Handling: Always check for translation availability
```
local text = i18n.translate('some.key') or 'Default Text'
```

Resource Organization: Keep translations organized by resource

-- each resource should import its own translations
i18n.importData('en', {
    inventory = { ... },
    shops = { ... },
    vehicles = { ... }
})

PreviousRandom Generation NextTable Extensions

Last updated 2 months ago