feat(scripts): add translation generator

- Added a translations generator Python script.

- Moved `Class.lua` from /modules to /lib since it's not a module.

- Fixed `Vehicle:MaxPerformance()`: Only check Gen9-exclusive mods in Legacy.

- Translator: Move the locales field into its own file then require it.

Author: xesdoog

.github/workflows/doc_gen.yml

@@ -8,7 +8,7 @@ on:
   workflow_dispatch:
 
 jobs:
-  generate:
+  Generate_Docs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout

.github/workflows/translations.yml

@@ -0,0 +1,33 @@
+name: Generate Docs
+
+on:
+  push:
+    paths:
+      - "SmallBase/includes/lib/translations/en-US.lua"
+      - "SmallBase/includes/lib/translations/locales.lua"
+  workflow_dispatch:
+
+jobs:
+  Generate_Translations:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12.x"
+
+      - name: Run Translations Generator
+        run: |
+          cd scripts
+          python generate_translations.py
+
+      - name: Commit changes
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add SmallBase/includes/lib/translations/
+          git diff --cached --quiet || git commit -m "feat(Translations): update translations"
+          git push

CONTRIBUTING.md

@@ -185,12 +185,34 @@ You are free to use any style you want, except in these cases:
         DoSomething()
         ```
 
-## What To Avoid
+## Translations
+
+- The primary language for all labels is English (US) (`/lib/translations/en-US.lua`).
+- To add a new language, add its name and ISO code to `/lib/translations/locales.lua`.
+- To add a new label, update `/lib/translations/en-US.lua`.
+- All other language files will be automatically generated via GitHub Actions (you can also manually run `/scripts/generate_translations.py`).
+
+**Example usage:**
+Suppose you want to draw some text that gets automatically translated:
 
-Avoid adding end-user features directly to the project (example: A drift minigame, a business manager, animations, etc.).
+1. Open `/lib/translations/en-US.lua`.
+2. Add a key-value pair for your new label:
+
+    ```lua
+    return {
+      ...
+      ["MY_LABEL"] = "My label's text in English."
+    }
+    ```
 
-SmallBase is, as the name suggests, a base. It provides the tools and the foundations to create new scripts.
+3. Use the `key` with the `_T` wrapper for the [`Translator:Translate(...)`](docs/services/Translator.md) method:
+
+    ```lua
+    ImGui.Text(_T("MY_LABEL"))
+    ```
+
+## What To Avoid
 
-Two scripts can both use this project as a template and offer completely different sets of features.
+- Manually editing any language file except `en-US.lua`. They are auto-generated.
 
-If you want to share a feature, make it a standalone module that uses SmallBase.
+- Adding end-user features directly to the project *(ex: A drift minigame, a business manager, animations, etc.)*.

SmallBase/includes/gui/settings_ui.lua

@@ -48,7 +48,7 @@ local selected_l_type_idx = 1
 local selected_entity_type = 1
 local TVehList = {}
 local g_offsets = {}
-local l_Offsets = {}
+local l_offsets = {}
 local state_colors <const> = {
     [eThreadState.UNK] = GREY,
     [eThreadState.DEAD] = RED,
@@ -243,7 +243,7 @@ local function DrawGlobalsAndLocals()
 
     ImGui.SameLine()
 
-    if GUI:Button(("Clear##%s"):format("globals")) then
+    if GUI:Button("Clear##globals") then
         init_g_addr = 0
         g_offset_count = 0
         g_offsets = {}
@@ -298,11 +298,11 @@ local function DrawGlobalsAndLocals()
 
     ImGui.BeginDisabled(string.isempty(l_scr_name) or init_l_addr == 0)
     ImGui.SameLine()
-    if GUI:Button(("Clear##%s"):format("locals")) then
+    if GUI:Button("Clear##locals") then
         l_scr_name = ""
         init_l_addr = 0
         l_offset_count = 0
-        l_Offsets = {}
+        l_offsets = {}
         selected_l_type_idx = 1
     end
 
@@ -315,8 +315,8 @@ local function DrawGlobalsAndLocals()
     ImGui.BeginDisabled(l_offset_count == 0)
     if GUI:Button("Remove Offset##locals") then
         l_offset_count = math.max(0, l_offset_count - 1)
-        if (#l_Offsets > 0) then
-            l_Offsets[#l_Offsets] = nil
+        if (#l_offsets > 0) then
+            l_offsets[#l_offsets] = nil
         end
     end
     ImGui.EndDisabled()
@@ -326,8 +326,8 @@ local function DrawGlobalsAndLocals()
         for i = 1, l_offset_count do
             ImGui.Text(".f_")
             ImGui.SameLine()
-            l_Offsets[i], _ = ImGui.InputInt("##test_local_offset" .. i, l_Offsets[i] or 0)
-            l_Offsets[i] = math.max(0, l_Offsets[i])
+            l_offsets[i], _ = ImGui.InputInt("##test_local_offset" .. i, l_offsets[i] or 0)
+            l_offsets[i] = math.max(0, l_offsets[i])
         end
     end
     ImGui.PopItemWidth()
@@ -345,9 +345,9 @@ local function DrawGlobalsAndLocals()
     if GUI:Button(("Read %s##locals"):format(selected_L_type or "")) then
         local method_name = selected_L_type == "Pointer" and "GetPointer" or "Read" .. selected_L_type
         local l = ScriptLocal(init_l_addr, l_scr_name)
-        if (#l_Offsets > 0) then
-            for i = 1, #l_Offsets do
-                l = l:At(l_Offsets[i])
+        if (#l_offsets > 0) then
+            for i = 1, #l_offsets do
+                l = l:At(l_offsets[i])
             end
         end
 
@@ -357,7 +357,7 @@ local function DrawGlobalsAndLocals()
 end
 
 local function DrawSerializerDebug()
-    local eState =  ThreadManager:GetThreadState("SB_SERIALIZER")
+    local eState = ThreadManager:GetThreadState("SB_SERIALIZER")
 
     ImGui.BulletText("Thread State:")
     ImGui.SameLine()
@@ -404,14 +404,12 @@ local function PopulateVehlistOnce()
 end
 
 local function DrawDummyVehSpawnMenu()
+    ImGui.Text("Lightweight Vehicle Preview Test")
     PopulateVehlistOnce()
 
     if ImGui.BeginListBox("##dummyvehlist", -1, 0) then
         for _, veh in ipairs(TVehList) do
-            local is_selected = false
-
-            ImGui.Selectable(veh.displayname, is_selected)
-
+            ImGui.Selectable(veh.displayname, false)
             if ImGui.IsItemHovered() then
                 local item_min = vec2:new(ImGui.GetItemRectMin())
                 hovered_y = item_min.y
@@ -420,7 +418,6 @@ local function DrawDummyVehSpawnMenu()
                 hovered_y = nil
             end
         end
-
         ImGui.EndListBox()
     end
 
@@ -482,7 +479,6 @@ debug_tab:RegisterGUI(function()
     end
 
     if ImGui.BeginTabItem("Preview Test") then
-        ImGui.Text("Lightweight Vehicle Preview Test")
         DrawDummyVehSpawnMenu()
         ImGui.EndTabItem()
     end

SmallBase/includes/init.lua

@@ -22,7 +22,7 @@ local DEFAULT_CONFIG <const> = {
 }
 
 require("includes.lib.utils")
-require("includes.modules.Class")
+require("includes.lib.class")
 require("includes.backend")
 require("includes.modules.Memory")
 

SmallBase/includes/modules/Class.lua renamed to SmallBase/includes/lib/class.lua

@@ -0,0 +1,19 @@
+-- Only add locales if you have matching files for them under /lib/translations/ otherwise you'll get an error when trying
+--
+-- to select a new language because `require` falls back to `package.searcher` which is disabled in V1's sandbox (don't know about V2 yet).
+--
+-- The error is actually just a warning from the API but just to keep things clean and running smoothly, don't add non-existing locales.
+return {
+    { name = "English", iso = "en-US" },
+    { name = "Français", iso = "fr-FR" },
+    { name = "Deütsch", iso = "de-DE" },
+    { name = "Español", iso = "es-ES" },
+    { name = "Italiano", iso = "it-IT" },
+    { name = "Português", iso = "pt-BR" },
+    { name = "Русский", iso = "ru-RU" },
+    { name = "中國人", iso = "zh-TW" },
+    { name = "中国人", iso = "zh-CN" },
+    { name = "日本語", iso = "ja-JP" },
+    { name = "Polski", iso = "pl-PL" },
+    { name = "한국인", iso = "ko-KR" },
+}

SmallBase/includes/lib/translations/locales.lua

@@ -129,9 +129,9 @@ function Memory.GetVehicleInfo(vehicle)
 end
 
 -- Checks if a vehicle's handling flag is set.
----@param vehicle number
----@param flag number
----@return boolean | nil
+---@param vehicle integer
+---@param flag eVehicleHandlingFlags
+---@return boolean|nil
 function Memory.GetVehicleHandlingFlag(vehicle, flag)
     if not (ENTITY.DOES_ENTITY_EXIST(vehicle) or ENTITY.IS_ENTITY_A_VEHICLE(vehicle)) then
         return
@@ -144,7 +144,7 @@ function Memory.GetVehicleHandlingFlag(vehicle, flag)
 end
 
 ---@param vehicle integer
----@param flag integer
+---@param flag eVehicleModelFlags
 ---@return boolean
 function Memory.GetVehicleModelFlag(vehicle, flag)
     local CVehicle = Memory.GetVehicleInfo(vehicle)
@@ -191,7 +191,7 @@ function Memory.GetEntityType(entity)
 end
 
 ---@param ped integer A Ped ID, not a Player ID.
----@return CPed | nil
+---@return CPed|nil
 function Memory.GetPedInfo(ped)
     if not ENTITY.DOES_ENTITY_EXIST(ped) or not ENTITY.IS_ENTITY_A_PED(ped) then
         return
@@ -256,7 +256,8 @@ function Memory.GetPedInfo(ped)
 end
 
 --[[
----@deprecated
+---@ignore
+---@unused
 ---@param dword integer
 function Memory.SetWeaponEffectGroup(dword)
     local pedPtr = memory.handle_to_ptr(self.get_ped())