How To Translate Scripts Using AI (FiveM Guide)

my_resource/
├─ fxmanifest.lua
├─ locales/
│  ├─ en.json        # source language (single source of truth)
│  ├─ de.json        # translated (generated/edited)
│  ├─ es.json        # translated (generated/edited)
│  └─ qa.rules.json  # optional: placeholder whitelist & checks
├─ client/
│  └─ main.lua
├─ server/
│  └─ main.lua
└─ shared/
   └─ i18n.lua       # translation helper

fx_version 'cerulean'
game 'gta5'
lua54 'yes'

shared_scripts {
  'shared/i18n.lua',
}

files {
  'locales/*.json'
}

local LOCALE = GetConvar('my_locale', 'en')
local CACHE = {}

local function loadJSON(path)
    local file = io.open(path, 'r')
    if not file then return {} end
    local content = file:read('*a')
    file:close()
    local ok, data = pcall(function() return json.decode(content) end)
    return ok and data or {}
end

local function readLocale(lang)
    if CACHE[lang] then return CACHE[lang] end
    local file = ('locales/%s.json'):format(lang)
    local dict = loadJSON(file)
    CACHE[lang] = dict
    return dict
end

local function interpolate(str, vars)
    if not vars then return str end
    for k, v in pairs(vars) do
        str = str:gsub('%%{'..k..'}', tostring(v)) -- %{name}
    end
    return str
end

function _U(key, vars)
    local dict = readLocale(LOCALE)
    local src  = dict[key]
    if not src then
        -- fallback to English if missing
        src = readLocale('en')[key] or key
    end
    return interpolate(src, vars)
end

exports('Translate', _U)

-- Client
lib.notify({
  title = _U('notify_title'),
  description = _U('welcome_player', { name = GetPlayerName(PlayerId()) }),
})

-- Server
print(('[MyRes] %s'):format(_U('server_started')))

{
  "notify_title": "Server Message",
  "welcome_player": "Welcome, %{name}!",
  "server_started": "Server module is ready.",
  "no_permission": "You do not have permission.",
  "items_remaining": "%{count} items remaining"
}

source,target
EMS,Rettungsdienst
PD,Polizei
Mechanic,Mechaniker

Task: Translate JSON values from English to <TARGET_LANGUAGE> for a FiveM/GTA RP context.
Rules:
- KEEP KEYS UNCHANGED.
- PRESERVE all placeholders exactly: %{var}, %s, %d, {0}, ~r~, ~g~, ^1, ^2, etc.
- Keep capitalization and code-style tokens (commands, /slash commands) unchanged.
- Do not add quotes, extra punctuation, or change meaning.
- Return ONLY valid JSON with the same structure.

JSON to translate:
<PASTE en.json CONTENT HERE>

{
  "type": "module",
  "scripts": {
    "i18n:translate:de": "node tools/translate-deepl.js en de",
    "i18n:check": "node tools/i18n-check.js"
  }
}

import fs from 'fs';
import path from 'path';
import assert from 'assert';
import fetch from 'node-fetch';

const [,, srcLang, dstLang] = process.argv;
const apiKey = process.env.DEEPL_API_KEY; // set in CI/ENV
assert(apiKey, 'DEEPL_API_KEY is required');

const src = JSON.parse(fs.readFileSync('locales/en.json', 'utf8'));
const out = {};

const GLOSSARY = {
  'EMS': 'Rettungsdienst',
  'PD': 'Polizei',
};

function protect(str){
  // Replace placeholders with tokens DeepL won't alter
  return str
    .replace(/%\{([^}]+)\}/g, '⟦$1⟧')
    .replace(/%s/g, '⟪S⟫')
    .replace(/%d/g, '⟪D⟫');
}
function restore(str){
  return str
    .replace(/⟦([^⟧]+)⟧/g, '%{$1}')
    .replace(/⟪S⟫/g, '%s')
    .replace(/⟪D⟫/g, '%d');
}

async function translate(text){
  const res = await fetch('https://api.deepl.com/v2/translate', {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({
      auth_key: apiKey,
      text: text,
      source_lang: srcLang.toUpperCase(),
      target_lang: dstLang.toUpperCase(),
      formality: 'prefer_more'
    })
  });
  const json = await res.json();
  if (!json.translations) throw new Error(JSON.stringify(json));
  return json.translations[0].text;
}

for (const [k, v] of Object.entries(src)) {
  const protectedText = protect(v);
  // Glossary pre-pass (simple):
  let glossed = protectedText;
  for (const [from, to] of Object.entries(GLOSSARY)) {
    glossed = glossed.replace(new RegExp(`\\b${from}\\b`, 'g'), to);
  }
  // Translate
  // eslint-disable-next-line no-await-in-loop
  const tr = await translate(glossed);
  out[k] = restore(tr);
}

fs.writeFileSync(`locales/${dstLang}.json`, JSON.stringify(out, null, 2));
console.log(`Wrote locales/${dstLang}.json`);

import fs from 'fs';

const src = JSON.parse(fs.readFileSync('locales/en.json', 'utf8'));
const dst = JSON.parse(fs.readFileSync('locales/de.json', 'utf8'));

const reVar = /%\{[^}]+\}/g;
const reS   = /%s/g;
const reD   = /%d/g;

let ok = true;
for (const k of Object.keys(src)) {
  const a = (src[k].match(reVar)||[]).length === (dst[k]?.match(reVar)||[]).length;
  const b = (src[k].match(reS)||[]).length   === (dst[k]?.match(reS)||[]).length;
  const c = (src[k].match(reD)||[]).length   === (dst[k]?.match(reD)||[]).length;
  if (!(a && b && c)) {
    console.error('Placeholder mismatch for key:', k);
    ok = false;
  }
}
process.exit(ok ? 0 : 1);

System: You translate FiveM game UI strings for <TARGET_LANGUAGE>.
- Keep keys unchanged, preserve placeholders, keep tone concise.

User examples:
EN: "You have %{count} fines."
DE: "Du hast %{count} Strafzettel."

EN: "~r~Error:~s~ You lack permission."
DE: "~r~Fehler:~s~ Dir fehlt die Berechtigung."

Now translate the following JSON values from English to <TARGET_LANGUAGE>. Return valid JSON only:
<PASTE JSON HERE>

const dict = await (await fetch(`/locales/${lang}.json`)).json();
export function t(key, vars){
  let s = dict[key] || key;
  for (const [k,v] of Object.entries(vars||{})) s = s.replace(`%{${k}}`, v);
  return s;
}

Locales = Locales or {}
Locales['en'] = {
  no_permission = 'You do not have permission.',
  welcome_player = 'Welcome, %{name}!'
}
Locales['de'] = {
  no_permission = 'Du hast keine Berechtigung.',
  welcome_player = 'Willkommen, %{name}!'
}