Lokalizacje skryptów FiveM: tłumaczalne skrypty z en.lua, ox_lib i ESX

Twój skrypt ma 'You have no money' na stałe zakodowany w czterdzieści miejscach. Właściciel serwera w Madrycie lub Berlinie chce tego w jego języku, a jedynym sposobem jest edycja kodu. Rozwiązaniem jest warstwa locale: stringi żyją w plikach dla każdego języka, kod prosi o klucze. Ten przewodnik pokazuje prostą wersję czystego Lua, potem system ox_lib i ESX.

#Pomysł

Zamiast:

ESX.ShowNotification('You have no money')

kod pisze:

ESX.ShowNotification(L('no_money'))

i plik języka dostarcza tekst dla no_money. Tłumacze potem zmieniają pliki, nigdy kod, i otwórz pliki locale mogą być wysyłane nieszyfrowane (zobacz escrow_ignore).

#Prosta funkcja locale Lua

Układ foldera:

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, funkcja, która wygląda klucz:

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, z locales najpierw i konfigu przed funkcją:

fx_version 'cerulean'
game 'gta5'

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

I w config.lua:

Config = {}
Config.Locale = 'en'

Użycie, z %s placeholders wypełnionymi przez string.format:

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

Fallbacky ma znaczenie: brakujący klucz w es wraca do en, i brakujący klucz wszędzie zwraca klucz sam, więc widzisz no_money na ekranie zamiast błędu. Dziura w tłumaczeniu potem pokazuje się jako widoczny klucz, nie crash.

Wskazówka: utrzymuj te same klucze w każdym pliku języka. Mały skrypt, który porównuje klucze en z każdym innym plikiem, łapie brakujące tłumaczenia przed wydaniem.

#System locale ox_lib

Jeśli Twój skrypt już zależy od ox_lib, możesz użyć jego wbudowanej locales zamiast pisania L(). Kształt to: załaduj ox_lib w manifestcie, umieść swoje tłumaczenia w folderze locales/ (ox_lib używa plików .json nazwanych według języka, jak locales/en.json), dołącz je z files i wywołaj lib.locale() raz:

-- 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))

Sprawdzaj dokumenty ox_lib dla bieżącego formatu i dla tego, jak język jest wybierany (convar serwera), ponieważ układ pliku i nazwy opcji zmieniły się między wersjami. Jeśli widzisz ox_lib/init.lua nie znaleziony, napraw to najpierw: ox_lib init.lua not found.

#ESX i TranslateCap

Skrypty ESX mają swój własny wzór locale. Pliki locale wypełniają tabelę Locales i framework dostarcza funkcję tłumaczenia:

-- 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'))

Starsze skrypty używają _U('no_money') dla tej samej rzeczy. TranslateCap to bieżąca nazwa w ostatnim ESX Legacy, a język jest wybrany przez Config.Locale lub własne ustawienie frameworku. Jak w ox_lib, sprawdzaj dokumenty wersji ESX, którą uruchamiasz dla dokładnych nazw plików i który z dwóch funkcji to oczekuje.

QBCore ma podobny moduł Lang (locales/en.lua używając Lang:t('key')), który działa w ten sam sposób: tabela na język i funkcja, która rozwiązuje klucze.

#Wybieranie języka

Oferuj jedną linię konfigu, blisko szczytu config.lua:

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

Jeśli Twój skrypt jest mieszanką klienta, serwera i NUI, pamiętaj, że tekst NUI potrzebuje swoich własnych tłumaczeń: wyślij stringi na stronę raz, gdy się otwiera, zamiast pisać angielski w HTML. Zobacz FiveM NUI with React and Vite dla przekazywania danych do strony.

#Checklist