git:20260727.58fdb8e to git:20260823.ea762f2

11 added, 11 removed. Audit A to A.

---

name: roblox-localization

description: "Use when implementing Roblox multi-language support, translation tables, auto-translation, locale-specific content, or region detection."

last_reviewed: 2026-07-26

sources:

- https://create.roblox.com/docs/reference/engine/classes/LocalizationService

- https://create.roblox.com/docs/reference/engine/classes/LocalizationTable

- https://create.roblox.com/docs/reference/engine/classes/Player

---

# 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`)

+ - `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)

+ - `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

+ - 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

```luau

local translator = LocalizationService:GetTranslatorForPlayerAsync(player)

local translated = translator:Translate(game, "Welcome!")

local formatted = translator:FormatByKey("coins_count", {count})

```

### Country/Region Detection

```luau

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

+ - `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 — VPNs give wrong results

+ - 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`.