PcoWSkbVqDnWTu_dm2ix
We use cookies on this site to enhance your user experience

Utilizing Localization APIs

Utilizing Localization APIs

Jul 11 2019, 10:29 AM PST 5 min

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().

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

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
 

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.

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:

  1. From the Manage Translations page in the portal, click the Add New Entry button.
  1. Specify Text to Translate (this will become Source in the spreadsheet) along with a Key value.
  2. 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 his/her 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:

  1. Create a new ModuleScript within ReplicatedStorage.
  2. Rename the new script TranslationHelper.
  3. 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

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")
Tags:
  • localization
  • language
  • translation
  • international
  • format