roblox-localization

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Roblox Localization

Roblox 本地化

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.

当需要实现多语言支持、翻译系统、特定区域设置内容或地区检测时加载。涵盖LocalizationService、LocalizationTable、自动翻译以及国家/地区检测功能。

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
```
— 玩家为其Roblox账户设置的区域设置（例如
```
en-us
```
、
```
pt-br
```
、
```
ja-jp
```
）
```
LocalizationService.RobloxLocaleId
```
— 核心/内部功能使用的区域设置
```
LocalizationService.SystemLocaleId
```
— 玩家操作系统的区域设置

LocalizationService:GetCountryRegionForPlayerAsync(player)

— 通过IP地理定位获取的国家代码（例如

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

```
LocalizationTable
```
— 存储翻译条目（键 → 各区域设置对应的翻译内容）
将
```
LocalizationTable
```
作为
```
LocalizationService
```
的子对象，以启用自动翻译
在GUI对象上设置
```
GuiBase2d.RootLocalizationTable
```
，为元素指定专属翻译表
可通过Studio中的Localization Tools插件自动提取字符串到翻译表中

Auto-Translation

自动翻译

Roblox auto-translates GUI text if
```
RootLocalizationTable
```
is set and entries exist
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

如果设置了
```
RootLocalizationTable
```
且存在对应条目，Roblox会自动翻译GUI文本
正常设置
```
TextLabel.Text
```
即可，引擎会将其替换为符合玩家区域设置的翻译文本
缺失的翻译内容会回退到源文本

Manual Translation

手动翻译

luau

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

luau

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

Country/Region Detection

国家/地区检测

luau

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

luau

local country = LocalizationService:GetCountryRegionForPlayerAsync(player)
if country == "US" then -- USD定价
elseif country == "GB" then -- GBP定价 end

Key Rules

关键规则

```
GetCountryRegionForPlayerAsync
```
is async — wrap in pcall, may fail
```
GetTranslatorForPlayerAsync
```
is async — cache the translator
Auto-translation only works on GUI elements with
```
RootLocalizationTable
```
set
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

```
GetCountryRegionForPlayerAsync
```
是异步方法 — 需用pcall包裹，可能调用失败
```
GetTranslatorForPlayerAsync
```
是异步方法 — 建议缓存翻译器
自动翻译仅对设置了
```
RootLocalizationTable
```
的GUI元素生效
翻译条目需包含
```
SourceText
```
、
```
SourceLocaleId
```
，以及
```
en-us
```
、
```
pt-br
```
等区域设置列
可从Studio中导出/导入CSV格式的翻译表，以便批量编辑
使用Studio的区域设置模拟器测试不同区域设置下的效果

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
Missing entries fall back to source text silently

Need more detail? Load

references/full.md

并非所有区域设置都受支持 — 需检查
```
player.LocaleId
```
自动翻译对非GUI文本无效 — 请使用手动方法
```
Translator:Translate
```
```
GetCountryRegionForPlayerAsync
```
基于IP地理定位 — VPN会导致结果不准确
缺失的翻译条目会自动回退到源文本，无提示

需要更多细节？ 加载

references/full.md

。