FiveM script locales: script traducibili con en.lua, ox_lib e ESX

Il tuo script ha 'You have no money' hard-codificato in quaranta posti. Un proprietario di server a Madrid o Berlino lo vuole nella sua lingua, e l'unico modo è modificare il codice. La soluzione è un livello di locale: le stringhe vivono in file per lingua, il codice chiede chiavi. Questa guida mostra una versione semplice in Lua semplice, quindi il sistema di ox_lib e ESX.

#L'idea

Invece di:

ESX.ShowNotification('You have no money')

il codice scrive:

ESX.ShowNotification(L('no_money'))

e un file di lingua fornisce il testo per no_money. I traduttori quindi modificano i file, mai il codice, e i file di locale aperti possono essere spediti non crittografati (vedi escrow_ignore).

#Una semplice funzione di locale in Lua

Layout della cartella:

my_script/
  fxmanifest.lua
  config.lua
  locales/
    en.lua
    es.lua
  shared/locale.lua

locales/en.lua:

Locales = Locales or {}

Locales['en'] = {
    no_money = 'You have no money',
    bought   = 'You bought %s for $%s',
}

locales/es.lua:

Locales = Locales or {}

Locales['es'] = {
    no_money = 'No tienes dinero',
    bought   = 'Compraste %s por $%s',
}

shared/locale.lua, la funzione che cerca una chiave:

function L(key, ...)
    local lang = Locales[Config.Locale] or Locales['en']
    local text = lang[key] or Locales['en'][key] or key
    if select('#', ...) > 0 then
        return text:format(...)
    end
    return text
end

Manifest, con i locales per primi e il config prima della funzione:

fx_version 'cerulean'
game 'gta5'

shared_scripts {
    'config.lua',
    'locales/*.lua',
    'shared/locale.lua',
}
client_script 'client/main.lua'
server_script 'server/main.lua'

E in config.lua:

Config = {}
Config.Locale = 'en'

Utilizzo, con i placeholder %s riempiti da string.format:

print(L('bought', 'bread', 5))   -- You bought bread for $5

I fallback contano: una chiave mancante in es ritorna a en, e una chiave mancante ovunque restituisce la chiave stessa, quindi vedi no_money sullo schermo invece di un errore. Un buco in una traduzione poi si mostra come una chiave visibile, non un crash.

Suggerimento: mantieni le stesse chiavi in ogni file di lingua. Un piccolo script che confronta le chiavi di en con ogni altro file cattura le traduzioni mancanti prima del rilascio.

#Il sistema locale di ox_lib

Se il tuo script dipende già da ox_lib, puoi usare i suoi locales integrati invece di scrivere L(). La forma è: carica ox_lib nel manifest, metti le tue traduzioni in una cartella locales/ (ox_lib usa file .json nominati per lingua, come locales/en.json), includili con files, e chiama lib.locale() una volta:

-- fxmanifest.lua
shared_script '@ox_lib/init.lua'
files { 'locales/*.json' }

{
  "no_money": "You have no money",
  "bought": "You bought %s for $%s"
}

lib.locale()   -- load the language

lib.notify({ description = locale('no_money'), type = 'error' })
print(locale('bought', 'bread', 5))

Controlla i documenti di ox_lib per il formato attuale e come la lingua è scelta (una convar del server), perché il layout del file e i nomi delle opzioni sono cambiati tra le versioni. Se vedi ox_lib/init.lua non trovato, correggilo prima: ox_lib init.lua non trovato.

#ESX e TranslateCap

Gli script ESX hanno il loro pattern di locale. I file di locale riempiono una tabella Locales e il framework fornisce una funzione di traduzione:

-- fxmanifest.lua
shared_scripts {
    '@es_extended/imports.lua',
    '@es_extended/locale.lua',
    'locales/*.lua',
    'config.lua',
}

-- locales/en.lua
Locales['en'] = {
    ['no_money'] = 'You have no money',
}

TriggerEvent('esx:showNotification', TranslateCap('no_money'))

Gli script più vecchi usano _U('no_money') per la stessa cosa. TranslateCap è il nome attuale in ESX Legacy recente, e la lingua è selezionata da Config.Locale o dall'impostazione propria del framework. Come con ox_lib, controlla i documenti della versione ESX che esegui per i nomi di file esatti e quale delle due funzioni si aspetta.

QBCore ha un modulo simile Lang (locales/en.lua usando Lang:t('key')) che funziona allo stesso modo: una tabella per lingua e una funzione che risolve le chiavi.

#Scelta della lingua

Offri una riga di config, vicino all'inizio di config.lua:

Config.Locale = 'en'   -- 'en', 'es', 'fr'...

Se il tuo script è un mix di client, server e NUI, ricorda che il testo NUI ha bisogno delle sue traduzioni: invia le stringhe alla pagina una volta quando si apre, invece di scrivere inglese nell'HTML. Vedi FiveM NUI con React e Vite per passare dati alla pagina.

#Elenco di controllo