gymkhana/scripts

Scripts

This folder contains utility scripts for the Gymkhana Godot project.

extract_dialog_keys.py

A Python script that extracts dialog keys from ESC files and analyzes translation coverage.

What it does

1. Scans all ESC files in the gymkhana folder
2. Extracts dialog keys from say() commands and dialog blocks
3. Compares with existing translations in turno_cocina.csv
4. Generates multiple output files for analysis

Usage

# Basic usage (outputs to project root)
python3 scripts/extract_dialog_keys.py

# Custom output directory
python3 scripts/extract_dialog_keys.py --output-dir ./reports

# Short form
python3 scripts/extract_dialog_keys.py -o ./translation_analysis

Output Files

The script generates three files:

1. missing_translations.csv

• Format: CSV with columns: keys, en, fr, es
• Content: Dialog keys missing from the translation file
• Use: Import into translation management systems

2. default_only_translations.md

• Format: Markdown
• Content: Dialog entries that only have default text (no translation key)
• Use: Identify where translation keys should be added

3. translation_report.md

• Format: Markdown
• Content: Comprehensive summary with statistics and recommendations
• Use: Overview of translation status

Example Output

Summary:
  Total dialog keys found: 273
  Existing translations: 342
  Missing translations: 25
  Keys with only default translations: 23
  Output directory: /path/to/output
  Files generated:
    - missing_translations.csv
    - default_only_translations.md
    - translation_report.md

Requirements

• Python 3.6+
• No external dependencies (uses only standard library)

ESC File Patterns Detected

The script recognizes these patterns in ESC files:

# Say commands with translation keys
say($player, "Spanish text", "dialog_key")

# Dialog options with translation keys
- "dialog_key:Spanish text"

# Say commands with only default text (flagged for review)
say($player, "Spanish text only")

# Dialog options with only default text (flagged for review)
- "Spanish text only"

Tips

• Run the script regularly to catch new dialog entries
• Use the markdown reports to prioritize translation work
• The CSV file can be imported into spreadsheet applications for bulk editing