FiveM скрипт locales: переводимые скрипты с en.lua, ox_lib и ESX

Ваш скрипт имеет 'You have no money' жёстко кодированный в сорока местах. Владелец сервера в Мадриде или Берлине хочет его на его языке, и единственный способ это редактировать код. Исправление это слой locale: строки живут в файлах на язык, код просит ключи. Это руководство показывает простую версию обычного Lua, затем ox_lib систему и ESX.

#Идея

Вместо:

ESX.ShowNotification('You have no money')

код пишет:

ESX.ShowNotification(L('no_money'))

и файл языка поставляет текст для no_money. Переводчики затем меняют файлы, никогда не код, и открытые файлы locale могут отправляться без шифрования (смотрите escrow_ignore).

#Функция обычного Lua locale

Макет папки:

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, функция которая выглядит ключ вверх:

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

Манифест, с locales сначала и конфигом перед функцией:

fx_version 'cerulean'
game 'gta5'

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

И в config.lua:

Config = {}
Config.Locale = 'en'

Использование, с %s заполнителями заполненными string.format:

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

Fallbacks важны: отсутствующий ключ в es откатывает к en, и отсутствующий ключ везде возвращает ключ сам, поэтому вы видите no_money на экране вместо ошибки. Дыра в переводе затем показывает вверх как видимый ключ, не краш.

Совет: держите одинаковые ключи в каждом файле языка. Маленький скрипт который сравнивает ключи en с каждым другим файлом ловит отсутствующие переводы перед выпуском.

#Система locale ox_lib

Если ваш скрипт уже зависит от ox_lib, вы можете использовать его встроенные locales вместо написания L(). Форма это: загрузите ox_lib в манифест, поместите ваши переводы в папку locales/ (ox_lib использует .json файлы названные по языку, как locales/en.json), включите их с files, и вызовите lib.locale() один раз:

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

Проверьте документацию ox_lib для текущего формата и для того как язык выбирается (сервер convar), потому что макет файла и имена опций изменились между версиями. Если вы видите ox_lib/init.lua не найдено, исправьте это сначала: ox_lib init.lua не найдено.

#ESX и TranslateCap

ESX скрипты имеют свой собственный паттерн locale. Файлы Locale заполняют таблицу Locales и фреймворк предоставляет функцию перевода:

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

Более старые скрипты используют _U('no_money') для одинакового. TranslateCap это текущее имя в недавних ESX Legacy, и язык выбирается по Config.Locale или собственной настройке фреймворка. Как с ox_lib, проверьте документацию версии ESX которую вы запускаете для точных имён файлов и которая из двух функций это ожидает.

QBCore имеет подобный модуль Lang (locales/en.lua используя Lang:t('key')) которые работают так же: таблица на язык и функция которая разрешает ключи.

#Выбор языка

Предложите одну строку конфига, рядом с вершиной config.lua:

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

Если ваш скрипт это смесь клиента, сервера и NUI, помните что NUI текст нуждается его собственные переводы: отправьте строки на страницу один раз когда она открывается, вместо написания английского в HTML. Смотрите FiveM NUI с React и Vite для передачи данных на страницу.

#Контрольный список