Roblox Slang

Type-safe internationalization (i18n) code generator for Roblox experiences. Write translations in JSON/YAML, generate type-safe Luau code with autocomplete support.

Why Roblox Slang?

Roblox's native localization system uses string literals for translation keys, leading to runtime errors from typos and no IDE support. Roblox Slang solves this by generating type-safe Luau code at build time.

Before (Roblox native):

local translator = LocalizationService:GetTranslatorForPlayerAsync(player)
local text = translator:FormatByKey("UI_Buttons_Confirm") -- Typo-prone, no autocomplete

-- Typo = runtime error
local text = translator:FormatByKey("UI_Buttns_Confirm") -- ERROR at runtime!

After (Roblox Slang):

local t = Translations.new("en")
local text = t.ui.buttons.confirm() -- Autocomplete works, type-safe

-- Typo = build-time error
local text = t.ui.buttns.confirm() -- ERROR: Property doesn't exist (caught at build time)

Features

• Type-safe translation access - Autocomplete and type checking in your IDE
• String interpolation - {name}, {count:int} with parameter validation
• Pluralization - CLDR rules (zero/one/two/few/many/other)
• Nested namespaces - Clean syntax: t.ui.buttons.buy()
• Watch mode - Auto-rebuild on file changes
• CSV generation - Export to Roblox Cloud Localization format
• Zero runtime dependencies - Generated code is pure Luau
• Multiple input formats - JSON, YAML, or CSV
• Translation overrides - A/B testing and seasonal events support

Installation

Roblox Slang is a CLI tool that generates code. Choose your preferred installation method:

Via Rokit (Recommended)

Rokit is the fastest and most modern toolchain manager for Roblox projects.

# Add to your project
rokit add mathtechstudio/roblox-slang

# Or install globally
rokit add --global mathtechstudio/roblox-slang

rokit.toml:

[tools]
roblox-slang = "mathtechstudio/roblox-slang@1.0.0"

Via Aftman

Note: Aftman is no longer actively maintained. We recommend using Rokit or Foreman for new projects.

Aftman provides exact version dependencies and a trust-based security model.

# Add to your project
aftman add mathtechstudio/roblox-slang

# Or install globally
aftman add --global mathtechstudio/roblox-slang

aftman.toml:

[tools]
roblox-slang = "mathtechstudio/roblox-slang@1.0.0"

Via Foreman

Foreman is the original Roblox toolchain manager, battle-tested in production.

foreman.toml:

[tools]
roblox-slang = { github = "mathtechstudio/roblox-slang", version = "1.0.0" }

foreman install

From GitHub Releases (Manual)

Download pre-built binaries for your platform:

• roblox-slang-1.0.0-linux-x86_64.zip
• roblox-slang-1.0.0-linux-aarch64.zip
• roblox-slang-1.0.0-windows-x86_64.zip
• roblox-slang-1.0.0-windows-aarch64.zip
• roblox-slang-1.0.0-macos-x86_64.zip
• roblox-slang-1.0.0-macos-aarch64.zip

Extract and add to your PATH, or use a tool manager for automatic updates.

From Source (Cargo)

# Install from crates.io
cargo install roblox-slang

# Or build from source
git clone https://github.com/mathtechstudio/roblox-slang.git
cd roblox-slang
cargo install --locked --path .

Verify Installation

roblox-slang --version
# Output: roblox-slang 1.0.0

Quick Start

1. Initialize Project

roblox-slang init

Creates:

• slang-roblox.yaml - Configuration file
• translations/ - Translation files directory

2. Create Translations

translations/en.json:

{
  "ui": {
    "buttons": {
      "buy": "Buy",
      "sell": "Sell"
    },
    "messages": {
      "greeting": "Hello, {name}!",
      "items": {
        "zero": "No items",
        "one": "1 item",
        "other": "{count} items"
      }
    }
  }
}

translations/es.json:

{
  "ui": {
    "buttons": {
      "buy": "Comprar",
      "sell": "Vender"
    },
    "messages": {
      "greeting": "¡Hola, {name}!",
      "items": {
        "zero": "Sin artículos",
        "one": "1 artículo",
        "other": "{count} artículos"
      }
    }
  }
}

3. Build

# One-time build
roblox-slang build

# Watch mode (auto-rebuild on changes)
roblox-slang build --watch

Generates:

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

4. Add to Your Game

Option A: Manual (Roblox Studio)

1. Copy output/Translations.lua to ReplicatedStorage in Roblox Studio
2. Rename to Translations (ModuleScript)
3. Optionally copy output/types/Translations.d.luau for LSP autocomplete

Option B: Rojo (Automatic Sync)

Set output directory to match your Rojo project structure:

slang-roblox.yaml:

output_directory: src/ReplicatedStorage/Translations

default.project.json:

{
  "name": "MyGame",
  "tree": {
    "$className": "DataModel",
    "ReplicatedStorage": {
      "$className": "ReplicatedStorage",
      "$path": "src/ReplicatedStorage"
    }
  }
}

Run roblox-slang build and Rojo will automatically sync to Studio!

5. Use in Game

local Translations = require(ReplicatedStorage.Translations)

-- Create instance for locale
local t = Translations.new("en")

-- Simple translations
print(t.ui.buttons.buy())  -- "Buy"

-- With parameters
print(t.ui.messages.greeting({ name = "Player123" }))  -- "Hello, Player123!"

-- Pluralization
print(t.ui.messages.items(0))  -- "No items"
print(t.ui.messages.items(1))  -- "1 item"
print(t.ui.messages.items(5))  -- "5 items"

-- Switch locale at runtime
t:setLocale("es")
print(t.ui.buttons.buy())  -- "Comprar"

-- Auto-detect player locale
local function onPlayerAdded(player)
    local t = Translations.newForPlayer(player)
    print(t.ui.messages.greeting({ name = player.DisplayName }))
end

Configuration

slang-roblox.yaml:

# Base locale (fallback when translation missing)
base_locale: en

# Supported locales
supported_locales:
  - en
  - es
  - id

# Input directory for translation files
input_directory: translations

# Output directory for generated code
# For Rojo users: Set to your Rojo-tracked folder (e.g., src/ReplicatedStorage/Translations)
# For manual users: Keep as "output" and copy to Studio manually
output_directory: output

# Optional: Translation overrides (for A/B testing, seasonal events)
overrides:
  enabled: true
  file: overrides.yaml

# Optional: Analytics tracking
analytics:
  enabled: true
  track_missing: true
  track_usage: true

Main Features

String Interpolation

{
  "welcome": "Welcome, {name}!",
  "score": "Score: {points:int}",
  "price": "Price: ${amount:fixed}"
}

print(t.welcome({ name = "Player" }))  -- "Welcome, Player!"
print(t.score({ points = 1234 }))      -- "Score: 1234"
print(t.price({ amount = 99.99 }))     -- "Price: $99.99"

Pluralization (CLDR Rules)

{
  "items": {
    "zero": "No items",
    "one": "1 item",
    "other": "{count} items"
  }
}

print(t.items(0))  -- "No items"
print(t.items(1))  -- "1 item"
print(t.items(5))  -- "5 items"

Locale Switching

local t = Translations.new("en")
print(t.ui.buttons.buy())  -- "Buy"

t:setLocale("es")
print(t.ui.buttons.buy())  -- "Comprar"

Auto-Detect Player Locale

-- Automatically uses player's country/locale
local t = Translations.newForPlayer(player)

Translation Overrides

For A/B testing or seasonal events:

overrides.yaml:

en:
  ui.buttons.buy: "Purchase Now!"  # Override for A/B test
  
es:
  ui.buttons.buy: "¡Comprar Ahora!"

Priority: overrides.yaml > translations/*.json

Documentation

📚 Complete Documentation

Quick links:

• Getting Started - Installation and first project
• Configuration - Config file reference
• String Interpolation - Parameter usage
• Pluralization - CLDR plural rules
• Roblox Cloud Integration - Upload to Roblox Cloud
• Rojo Integration - Use with Rojo for automatic syncing
• CLI Reference - Complete command reference

Commands

Command	Description
roblox-slang init	Initialize new project
roblox-slang init --with-overrides	Initialize with overrides template
roblox-slang build	Build translations once
roblox-slang build --watch	Watch mode (auto-rebuild)
roblox-slang import <CSV_FILE>	Import from Roblox CSV file
roblox-slang validate --all	Check for missing/unused keys and conflicts
roblox-slang migrate --from <format>	Migrate from other formats

See CLI Reference for complete command documentation.

Roblox Cloud Integration

Export to Roblox Cloud Localization format:

roblox-slang build
# Generates: output/roblox_upload.csv

Upload roblox_upload.csv to your game's Localization Table via:

• Roblox Creator Dashboard
• Open Cloud API

Benefits of uploading to Roblox Cloud:

• Automatic Text Capture (ATC) - Roblox captures UI strings automatically
• Automatic translation - Roblox AI translates to supported languages
• Translator Portal - Collaborate with translators via Roblox
• Analytics - Track translation coverage via Roblox Dashboard
• Multi-game synchronization

Examples

See tests/basic/ for a complete example with 173 translation keys across 3 locales.

Development

For contributors:

# Clone repository
git clone https://github.com/mathtechstudio/roblox-slang.git
cd roblox-slang

# Install Rust (1.88+)
rustup override set 1.88.0

# Build
cargo build

# Run tests (103 tests)
cargo test

# Run CLI
cargo run -- --help

Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.

License

MIT License - see LICENSE

References

• Roblox Localization Documentation
• Unicode CLDR Plural Rules
• Luau Language Reference