Skip to content

cli-reference.md

Latest commit

 

History

History
344 lines (227 loc) · 5.92 KB

cli-reference.md

File metadata and controls

344 lines (227 loc) · 5.92 KB

CLI Reference

Complete reference for all Roblox Slang CLI commands.

Global Options

Available for all commands:

roblox-slang [OPTIONS] <COMMAND>

Options:

  • -h, --help - Show help information
  • -V, --version - Show version information

Examples:

roblox-slang --version
roblox-slang --help
roblox-slang build --help

Commands

init

Initialize a new Roblox Slang project.

Usage:

roblox-slang init [OPTIONS]

Options:

  • --with-overrides - Create overrides.yaml template

Examples:

# Basic initialization
roblox-slang init

# With overrides template
roblox-slang init --with-overrides

Creates:

  • slang-roblox.yaml - Configuration file
  • translations/ - Empty directory for translation files
  • overrides.yaml - (if --with-overrides) Override template

build

Build translations and generate Luau code.

Usage:

roblox-slang build [OPTIONS]

Options:

  • -w, --watch - Watch mode (auto-rebuild on changes)

Examples:

# One-time build
roblox-slang build

# Watch mode
roblox-slang build --watch

Generates:

  • output/Translations.lua - Main module
  • output/types/Translations.d.luau - Type definitions
  • output/roblox_upload.csv - CSV for Roblox Cloud

Exit Codes:

  • 0 - Success
  • 1 - Build error

import

Import translations from a Roblox CSV file.

Usage:

roblox-slang import <CSV_FILE>

Arguments:

  • <CSV_FILE> - Path to the CSV file to import

Examples:

# Import from Roblox CSV
roblox-slang import existing_table.csv

# Import downloaded translations
roblox-slang import downloaded_translations.csv

Output:

Converts CSV to JSON format in translations/ directory.

validate

Validate translations for errors and inconsistencies.

Usage:

roblox-slang validate [OPTIONS]

Options:

  • --missing - Check for missing translations
  • --unused - Check for unused keys
  • --conflicts - Check for conflicts
  • --coverage - Show coverage report
  • --source <DIR> - Source directory to scan for unused keys
  • --all - Run all checks

Examples:

# Check for missing translations
roblox-slang validate --missing

# Check for unused keys
roblox-slang validate --unused --source src/

# Run all checks
roblox-slang validate --all

# Multiple checks
roblox-slang validate --missing --conflicts --coverage

Checks:

  • Missing translations - Keys in base locale but not in others
  • Unused keys - Defined but never used in source code
  • Conflicts - Duplicate keys or conflicting definitions
  • Coverage - Translation coverage percentage per locale

Exit Codes:

  • 0 - No issues found
  • 1 - Issues found

migrate

Migrate translations from another format.

Usage:

roblox-slang migrate --from <FORMAT> --input <FILE> --output <FILE> [OPTIONS]

Options:

  • --from <FORMAT> - Format to migrate from (custom-json, gettext)
  • --input <FILE> - Input file path
  • --output <FILE> - Output file path
  • --transform <TRANSFORM> - Key transformation strategy (snake-to-camel, upper-to-lower, dot-to-nested, none)

Examples:

# Migrate from custom JSON
roblox-slang migrate --from custom-json --input old.json --output translations/en.json

# Migrate from gettext
roblox-slang migrate --from gettext --input translations.po --output translations/en.json

# With key transformation
roblox-slang migrate --from custom-json --input old.json --output new.json --transform snake-to-camel

Supported Formats:

  • custom-json - Custom JSON format
  • gettext - GNU gettext (.po files)

Key Transformation Strategies:

  • none - Keep keys as-is
  • snake-to-camel - Convert ui_button_buy → uiButtonBuy
  • upper-to-lower - Convert UI_BUTTON_BUY → ui_button_buy
  • dot-to-nested - Convert flat keys to nested structure

Configuration File

All commands use slang-roblox.yaml in the current directory.

Example:

base_locale: en
supported_locales:
  - en
  - es
  - id
input_directory: translations
output_directory: output

See Configuration Guide for complete reference.

Exit Codes

All commands use standard exit codes:

Code Meaning
0 Success
1 Error

Examples

Basic Workflow

# 1. Initialize project
roblox-slang init

# 2. Create translations
# (edit translations/en.json, translations/es.json, etc.)

# 3. Validate
roblox-slang validate --all

# 4. Build
roblox-slang build

# 5. Use in game
# (copy output/Translations.lua to your project)

Development Workflow

# Start watch mode
roblox-slang build --watch

# In another terminal, edit translations
# Watch mode auto-rebuilds on save

Import Workflow

# 1. Export from Roblox Cloud
# (download CSV from Creator Dashboard)

# 2. Import to Roblox Slang
roblox-slang import roblox_export.csv

# 3. Build
roblox-slang build

Validation Workflow

# Check for missing translations
roblox-slang validate --missing

# Check for unused keys in source code
roblox-slang validate --unused --source src/

# Full validation
roblox-slang validate --all --source src/

Troubleshooting

Command Not Found

# Check installation
which roblox-slang

# Reinstall
rokit install  # or aftman install, foreman install

Build Fails

# Validate first
roblox-slang validate --all

# Check config
cat slang-roblox.yaml

# Check translation files
ls -la translations/

Import Fails

# Check CSV format
head roblox_export.csv

# Verify file exists
ls -la roblox_export.csv

See Also