Roblox Localization

When to Load

Load when implementing multi-language support, translation systems, locale-specific content, or region detection. Covers LocalizationService, LocalizationTable, auto-translation, and country/region detection.

Quick Reference

Locale Detection

player.LocaleId: locale the player set for their Roblox account (e.g. en-us, pt-br, ja-jp)
LocalizationService.RobloxLocaleId: locale for core/internal features
LocalizationService.SystemLocaleId: player's OS locale
LocalizationService:GetCountryRegionForPlayerAsync(player): country code from IP geolocation (e.g. US, BR, JP)

Translation Tables

LocalizationTable: stores translation entries (key → translations per locale)
Parent LocalizationTable under LocalizationService for auto-translation
Set GuiBase2d.RootLocalizationTable on GUI objects for per-element tables
Studio can auto-extract strings into a table via the Localization Tools plugin

Auto-Translation

Auto-translation requires AutoLocalize = true on the GUI and its ancestors, plus a matching table entry
Set TextLabel.Text normally; the engine replaces it with the translated string for the player's locale
Missing translations fall back to the source text

Manual Translation

local translator = LocalizationService:GetTranslatorForPlayerAsync(player)
local translated = translator:Translate(game, "Welcome!")
local formatted = translator:FormatByKey("coins_count", {count})

Country/Region Detection

local country = LocalizationService:GetCountryRegionForPlayerAsync(player)
if country == "US" then -- USD pricing
    -- US offer
elseif country == "GB" then
    -- UK offer
end

Key Rules

GetCountryRegionForPlayerAsync is async; wrap in pcall, may fail
GetTranslatorForPlayerAsync is async; cache the translator
Set RootLocalizationTable to choose a table; keep AutoLocalize true through the ancestor chain
Translation entries: SourceText, SourceLocaleId, then en-us, pt-br, etc. columns
Export/import tables as CSV from Studio for bulk editing
Test with different locales using Studio's locale simulator

Pitfalls

Not all locales supported; check player.LocaleId
Auto-translation does NOT work on non-GUI text; use manual Translator:Translate
GetCountryRegionForPlayerAsync uses IP geolocation, so VPNs give wrong results
Missing entries fall back to source text silently

Need more detail? Load references/full.md.

roblox-localization