GitHub - mathtechstudio/roblox-slang: A Type-safe internationalization (i18n) code generator for Roblox experiences

Roblox Slang is a 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
Three localization modes - Embedded (default), Cloud, or Hybrid for flexibility
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
Cloud sync - Bidirectional sync with Roblox Cloud Localization Tables
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@2.0.2"

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@2.0.2"

Via Foreman

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

foreman.toml:

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

foreman install

From GitHub Releases (Manual)

Download pre-built binaries for your platform:

roblox-slang-2.0.2-linux-x86_64.zip
roblox-slang-2.0.2-linux-aarch64.zip
roblox-slang-2.0.2-windows-x86_64.zip
roblox-slang-2.0.2-windows-aarch64.zip
roblox-slang-2.0.2-macos-x86_64.zip
roblox-slang-2.0.2-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 2.0.2

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)

Copy output/Translations.lua to ReplicatedStorage in Roblox Studio
Rename to Translations (ModuleScript)
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: Namespace for generated module (null = no namespace)
namespace: null

# Localization mode (NEW in v2.0.2)
# Controls how translations are loaded at runtime
localization:
  # Mode: embedded (default) - Translations embedded in generated code, no cloud dependency
  # Other options:
  #   - cloud: Use Roblox Cloud LocalizationService only (requires cloud upload)
  #   - hybrid: Try cloud first, fallback to embedded (best of both worlds)
  mode: embedded

# 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

Localization Modes

NEW in v2.0.2: Choose how translations are loaded at runtime.

Embedded Mode (Default)

Translations are embedded directly in the generated Luau code. No cloud dependency required.

localization:
  mode: embedded

Benefits:

Works offline (no LocalizationService dependency)
Fastest performance (direct table lookup)
No cloud setup required
Perfect for single-player or offline games

Usage:

local t = Translations.new("en")
print(t.ui.buttons:buy())  -- Direct lookup from embedded data

Cloud Mode

Uses Roblox Cloud LocalizationService exclusively. Requires uploading translations to Roblox Cloud.

localization:
  mode: cloud

Benefits:

Automatic Text Capture (ATC) integration
Automatic translation via Roblox AI
Translator Portal collaboration
Analytics via Roblox Dashboard

Usage:

local t = Translations.new("en")
print(t.ui.buttons:buy())  -- Fetches from LocalizationService

Requirements:

Must run roblox-slang upload to sync translations to cloud
Requires cloud configuration in slang-roblox.yaml

Hybrid Mode

Best of both worlds: tries cloud first, falls back to embedded on error.

localization:
  mode: hybrid

Benefits:

Cloud features when available (ATC, auto-translation)
Embedded fallback for reliability
Graceful degradation on cloud errors
Works in Studio and production

Usage:

local t = Translations.new("en")
print(t.ui.buttons:buy())  -- Tries cloud, falls back to embedded

Use Cases:

Games transitioning from embedded to cloud
Games that need offline support with cloud benefits
Development (Studio) vs production (cloud) workflows

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 upload`	Upload translations to Roblox Cloud
`roblox-slang download`	Download translations from Roblox Cloud
`roblox-slang sync`	Bidirectional sync with merge strategies
`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

Roblox Slang provides seamless integration with Roblox Cloud Localization Tables through bidirectional sync commands.

Quick Start

Get your API key from Creator Dashboard, go to the API Keys page.

Set environment variable:

export ROBLOX_CLOUD_API_KEY=your_api_key_here

Upload translations:

roblox-slang upload --table-id YOUR_TABLE_ID

Download translations:

roblox-slang download --table-id YOUR_TABLE_ID

Bidirectional sync:

roblox-slang sync --table-id YOUR_TABLE_ID --strategy merge

Cloud Sync Commands

Command	Description
`roblox-slang upload`	Upload local translations to Roblox Cloud
`roblox-slang download`	Download translations from Roblox Cloud
`roblox-slang sync`	Bidirectional sync with merge strategies

Merge Strategies

overwrite - Upload all local translations (cloud is overwritten)
merge - Upload local-only, download cloud-only, prefer cloud for conflicts
skip-conflicts - Upload local-only, download cloud-only, skip conflicts

Configuration

Add cloud settings to slang-roblox.yaml:

cloud:
  table_id: YOUR_TABLE_ID
  game_id: YOUR_GAME_ID
  api_key: ${ROBLOX_CLOUD_API_KEY}  # Or set directly (not recommended)
  strategy: merge

Benefits of Cloud Sync

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 - Share translations across games
Version control - Keep local and cloud in sync

See Roblox Cloud Integration Guide for complete documentation.

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

Name		Name	Last commit message	Last commit date
Latest commit History 120 Commits
.github		.github
benches		benches
docs		docs
src		src
tests		tests
.editorconfig		.editorconfig
.gitattributes		.gitattributes
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
LICENSE		LICENSE
README.md		README.md
aftman.toml		aftman.toml
foreman.toml		foreman.toml
rokit.toml		rokit.toml
selene.toml		selene.toml

Uh oh!

License

mathtechstudio/roblox-slang

Folders and files

Latest commit

History

Repository files navigation

Why Roblox Slang?

Features

Installation

Via Rokit (Recommended)

Via Aftman

Via Foreman

From GitHub Releases (Manual)

From Source (Cargo)

Verify Installation

Quick Start

1. Initialize Project

2. Create Translations

3. Build

4. Add to Your Game

Option A: Manual (Roblox Studio)

Option B: Rojo (Automatic Sync)

5. Use in Game

Configuration

Main Features

Localization Modes

Embedded Mode (Default)

Cloud Mode

Hybrid Mode

String Interpolation

Pluralization (CLDR Rules)

Locale Switching

Auto-Detect Player Locale

Translation Overrides

Documentation

Commands

Roblox Cloud Integration

Quick Start

Cloud Sync Commands

Merge Strategies

Configuration

Benefits of Cloud Sync

Examples

Development

Contributing

License

References

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 8

Sponsor this project

Uh oh!

Packages 0

Contributors 2

Uh oh!

Languages

Packages