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.
local LocalizationService = game:GetService("LocalizationService")
local success, translator = pcall(function()
return LocalizationService:GetTranslatorForPlayerAsync(game.Players.LocalPlayer)
end)
if success then
else
warn("Cannot load translator for player!")
end
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 |
local LocalizationService = game:GetService("LocalizationService")
local success, translator = pcall(function()
return LocalizationService:GetTranslatorForLocaleAsync("es")
end)
if success then
else
warn("Cannot load translator for player!")
end
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/localization portal additional features#test-localization|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 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
ModuleScriptwithinReplicatedStorage. - Rename the new script TranslationHelper.
- Copy the following code into the script.
local TranslationHelper = {}
-- Roblox services
local LocalizationService = game:GetService("LocalizationService")
local Players = game:GetService("Players")
-- Local variables
local player = Players.LocalPlayer
local sourceLanguageCode = "en"
-- Get translators
local playerTranslator, fallbackTranslator
local foundPlayerTranslator = pcall(function()
playerTranslator = LocalizationService:GetTranslatorForPlayerAsync(player)
end)
local foundFallbackTranslator = pcall(function()
fallbackTranslator = LocalizationService:GetTranslatorForLocaleAsync(sourceLanguageCode)
end)
TranslationHelper.setSourceLanguage = function(languageCode)
if sourceLanguageCode ~= languageCode then
foundFallbackTranslator = pcall(function()
fallbackTranslator = LocalizationService:GetTranslatorForLocaleAsync(sourceLanguageCode)
sourceLanguageCode = languageCode
return true
end)
end
return false
end
-- Translate function
TranslationHelper.translate = function(text, object)
if not object then
object = game
end
local translation = ""
local foundTranslation = false
if foundPlayerTranslator then
return playerTranslator:Translate(object, text)
end
if foundFallbackTranslator then
return fallbackTranslator:Translate(object, text)
end
return false
end
-- Translate by key function
TranslationHelper.translateByKey = function(key, arguments)
local translation = ""
local foundTranslation = false
-- First tries to translate for the player's language (if a translator was found)
if foundPlayerTranslator then
foundTranslation = pcall(function()
translation = playerTranslator:FormatByKey(key, arguments)
end)
end
if foundFallbackTranslator and not foundTranslation then
foundTranslation = pcall(function()
translation = fallbackTranslator:FormatByKey(key, arguments)
end)
end
if foundTranslation then
return translation
else
return false
end
end
return TranslationHelper
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().
-- Roblox services
local ReplicatedStorage = game:GetService("ReplicatedStorage")
-- Require translation module
local TranslationHelper = require(ReplicatedStorage:WaitForChild("TranslationHelper"))
local sourceTranslation = TranslationHelper.translate("Source_String")
local keyTranslation = TranslationHelper.translateByKey("Key_Name")