Better French Translate

A Lua mod script for dumping and applying game localization data as one JSON file per language.

What this mod does

This script has two jobs:

1. Dump localization data from the game into JSON files.
2. Load the French JSON and patch the game text at runtime.

The format is designed so that each language stays separate:

• localization/En_Us.json
• localization/Fr_Fr.json
• and so on for every language the game exposes

Each JSON file contains:

• the game version metadata
• the language code
• a map of id -> text

Example structure:

{
  "version": {
    "build": 1004637,
    "branch": "ea_update_08",
    "date": "2026-04-23",
  },
  "language": "Fr_Fr",
  "entries": {
    "122361": "...",
    "945922580": "..."
  }
}

Features

• One file per language
• Stable ordering of IDs in exported JSON
• Safe JSON escaping for:
  • quotes
  • backslashes
  • tabs
  • newlines
  • other control characters
• Version parsing for compatibility checks
• Built-in JSON loader for the translation file
• Runtime patching of the French localization

File layout

The script exports files into a localization/ folder relative to the mod export directory.

Expected export examples:

• localization/Fr_Fr.json
• localization/En_Us.json

How it works

1. Version parsing

The script reads game.version and extracts:

• build: numeric build number used for comparison
• branch: branch name
• date: build date

This is used to compare the translation file against the current game build.

2. Dumping localization

The dump function:

• gets all keen::LocaTagCollectionResource resources
• iterates over every language exposed by the game
• reads each language’s tags
• exports one JSON file per language

Only unique IDs are written.

3. Loading and applying French text

At runtime, the script:

• loads localization/Fr_Fr.json
• checks the version metadata
• warns if the saved build differs from the current game build
• replaces matching French localization entries by ID

How to use

Step 1: Install the script

Put the Lua file in your mod loader setup and enable it.

Step 2: Dump the localization files

Temporarily enable the dump function by uncommenting:

-- dump_localization()

and commenting out:

apply_translation()

Then run the game once to generate the JSON files.

Step 3: Translate the French file

Open localization/Fr_Fr.json and translate the values inside entries.

Keep the IDs unchanged.

Example:

"122361": "Notre nouvel allié forgera peut-être votre épée..."

Step 4: Re-enable translation

Once the French file is ready:

• comment out dump_localization()
• keep apply_translation() enabled

The mod will then load the French JSON and patch the game text.

Important rules when translating

Do not remove or break formatting placeholders, such as:

• %s
• %d
• <b>...</b>
• <i>...</i>
• line breaks represented by \n

These are often required by the game UI.

Compatibility behavior

The JSON file stores the build number from game.version.

When the mod loads a translation file, it compares:

• saved build number
• current game build number

If the build differs, the script prints a warning.

This helps detect when a game update may have changed localization IDs.

Notes

• The script currently applies the French translation from Fr_Fr.json.
• The export still supports every language the game exposes.
• The translation files stay separate by language on purpose.
• io.export() is used instead of io.open() because the mod environment blocks direct file writing.

Troubleshooting

No file is exported

Make sure export capability is enabled in the mod environment.

French text does not appear in game

Check that:

• localization/Fr_Fr.json exists
• the JSON is valid
• IDs in the JSON match the game IDs
• apply_translation() is enabled

JSON parse errors

This usually means one of the translation strings contains invalid JSON characters or the file was edited in a way that broke quoting.

Suggested workflow

1. Dump all languages
2. Translate Fr_Fr.json
3. Keep one file per language
4. Re-run the mod after game updates
5. Compare build numbers when a patch arrives

Future improvements

Possible upgrades for later:

• auto-diff new IDs after a patch
• validation for placeholders like %s
• optional export of only visible UI strings
• translation QA checks