Utilizing Localization APIs
Utilizing Localization APIs
When necessary, you can use scripts to fetch and format translations that were added to the articles/Introduction to Localization on Roblox|localization portal
.
Loading a Translator
When you’re ready to translate using APIs, you should first fetch a Translator
instance.
Player Locale
The LocalizationService/GetTranslatorForPlayerAsync|GetTranslatorForPlayerAsync()
API, when called on the Players/LocalPlayer|LocalPlayer
property, will fetch a Translator
for whichever language the player’s Roblox account is set to.
Specific Locale
If you’ve implemented a custom game option which lets players choose their preferred language, you may fetch a Translator
for a Roblox-supported language code via LocalizationService/GetTranslatorForLocaleAsync|GetTranslatorForLocaleAsync()
.
Language Code Reference »
The following table outlines the languages currently supported in the localization portal. Those highlighted in yellow are fully supported by the Roblox platform/applications.
Language Code | Language | |
---|---|---|
de | German | Deutsch |
en | English | English |
es | Spanish | Español |
fr | French | Français |
jp | Japanese | 日本語 |
ko | Korean | 한국어 |
pt | Portuguese | Português |
zh-hans | Chinese (Simplified) | 中文(简体) |
zh-hant | Chinese (Traditional) | 中文(繁體) |
bg | Bulgarian | български |
bn | Bengali | বাংলা |
bs | Bosnian | босански |
cs | Czech | Čeština |
da | Danish | Dansk |
el | Greek | ελληνικά |
et | Estonian | Eesti |
fi | Finnish | Suomi |
hi | Hindi | हिन्दी |
hr | Croatian | Hrvatski |
hu | Hungarian | Magyar |
id | Indonesian | Bahasa Indonesia |
it | Italian | Italiano |
ka | Georgian | ქართული |
kk | Kazakh | қазақ тілі |
km | Khmer | ភាសាខ្មែរ |
lt | Lithuanian | Lietuvių |
lv | Latvian | Latviešu |
ms | Malay | Bahasa Melayu |
my | Burmese | ဗမာစာ |
nb | Bokmal | Bokmål |
nl | Dutch | Nederlands |
fil | Filipino | Filipino |
pl | Polish | Polski |
ro | Romanian | Română |
ru | Russian | русский |
si | Sinhala | සිංහල |
sk | Slovak | Slovenčina |
sl | Slovenian | Slovenski |
sq | Albanian | Shqipe |
sr | Serbian | српски |
sv | Swedish | Svenska |
th | Thai | ภาษาไทย |
tr | Turkish | Türkçe |
uk | Ukrainian | україньска |
vi | Vietnamese | Tiểng Việt |
LocalizationService/GetTranslatorForPlayerAsync|GetTranslatorForPlayerAsync()
and LocalizationService/GetTranslatorForLocaleAsync|GetTranslatorForLocaleAsync()
are asynchronous and may occasionally fail due to poor connectivity or other issues, so it's important to wrap them with pcall
and implement error handling as outlined below.
Translate()
Once a valid Translator
is loaded, the Translator/Translate|Translate()
function can fetch a translation from the localization portal based on its Source string and an in-game Instance
. Note that the Instance
argument can be arbitrary unless you require context overrides.
A | B | C | D | E |
Key | Context | Source | Example | es |
Screen | Pantalla | |||
Translator/Translate|Translate()
with a source text string that does not exist in the localization portal, that string will be automatically added to the portal (and the downloadable .csv spreadsheet) so that human translators can locate it and provide translations.
FormatByKey()
When called on a valid Translator
, Translator/FormatByKey|FormatByKey()
fetches a translation from the localization portal based on an identifier key for the source item. Identifier keys can only be entered in the Key column of the downloaded spreadsheet or through direct entry in the portal — they cannot be detected and added through automatic text capture in the Roblox application.
Entering Keys »
If you prefer to manage translations with a .csv articles/localization portal additional features#localizing-with-csv-files|spreadsheet
, identifier keys can be entered in the Key column:
A | B | C | D | E |
Key | Context | Source | Example | es |
Key_StartButton | Start | Iniciar | ||
Key_OptionsButton | Options | Opciones | ||
Alternatively, you can input key-based entries directly in the localization portal as follows:
- From the Manage Translations page in the portal, click the Add New Entry button.

- Specify Text to Translate (this will become Source in the spreadsheet) along with a Key value.
- Click the Save button to add the entry to the portal.
To use Translator/FormatByKey|FormatByKey()
in a script, call the API with a valid key name from the localization portal. For instance, the print()
statement on line 9 of the following code sample will output the Spanish translation “joyas” for the “Key_Prize” key when you articles/game testing#player-emulator|playtest
in Spanish.
A | B | C | D | E |
Key | Context | Source | Example | es |
Key_Prize | jewels | joyas | ||
Using Format Strings
Localization APIs can also be used with /articles/localization format strings|format strings
to return translations with variable data. The approach simply depends on whether the format strings are numbered or named.
Numbered Format Strings
Consider the following translation data which contains numbered format strings like {1:int}:
A | B | C | D | E |
Key | Context | Source | Example | es |
Key_Prize_1 | {1:int} jewels | {1:int} joyas | ||
Key_Prize_2 | ${1:fixed} cash and {2:int} jewels | ${1:fixed} dinero y {2:int} joyas | ||
To format these for a variable amount of cash and/or jewels, pass the amount(s) in a comma-delimited Lua array as the second argument to Translator/FormatByKey|FormatByKey()
. With these additions, the print()
statements will output correct translations when you articles/game testing#player-emulator|playtest
in Spanish.
Named Format Strings
When handling named format strings like {NumJewels:int}, pass a table of key-value pairs as the second argument to Translator/FormatByKey|FormatByKey()
, where each pair consists of a format string’s name and the value to substitute.
A | B | C | D | E |
Key | Context | Source | Example | es |
Key_Prize_1 | {NumJewels:int} jewels | {NumJewels:int} joyas | ||
Key_Prize_2 | {AmountCash:fixed} cash and {NumJewels:int} jewels | {AmountCash:fixed} dinero y {NumJewels:int} joyas | ||
Best Practices
Disable AutoLocalize
When using localization APIs, it’s usually best practice to disable GuiBase2d/AutoLocalize|AutoLocalize
on the object where the translations will be used. For example:
Scenario | Reason to Disable AutoLocalize |
---|---|
Displaying an NPC's proper name on a BillboardGui above its head. |
The NPC’s name won’t change across languages, so Studio's automatic text capture feature should never grab it. |
Fetching a translation from the portal and displaying it letter-by-letter in a "typewriter" effect. | To prevent Studio's automatic text capture feature from grabbing and adding incomplete words to the portal. |
To disable auto-localization on a specific GUI object, un-check its GuiBase2d/AutoLocalize|AutoLocalize
property in Studio or set it to false
within a script.
Error Handling
The following helper module catches issues which may exist in your localization entries and handles potential errors caused by the web-based functions that fetch a Translator
. To use it in your game:
- Create a new
ModuleScript
withinReplicatedStorage
. - Rename the new script TranslationHelper.
- Copy the following code into the script.
sourceLanguageCode
on line 9 to a fully-supported language code which matches the game's source language setting in the localization portal. Please refer to the language code reference table above for acceptable options.
Once the module is placed into ReplicatedStorage
, require()
it from a LocalScript
as shown on line 5 below. Then, whenever needed, call the module’s translate()
function as an equivalent to Translator/Translate|Translate()
or translateByKey()
as an equivalent to Translator/FormatByKey|FormatByKey()
.