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.

Expand

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

Copy Code Light Theme

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	Češ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	Lietuvių
lv	Latvian	Latviešu
ms	Malay	Bahasa Melayu
my	Burmese	ဗမာစာ
nb	Bokmal	Bokmål
nl	Dutch	Nederlands
fil	Filipino	Filipino
pl	Polish	Polski
ro	Romanian	Română
ru	Russian	русский
si	Sinhala	සිංහල
sk	Slovak	Slovenčina
sl	Slovenian	Slovenski
sq	Albanian	Shqipe
sr	Serbian	српски
sv	Swedish	Svenska
th	Thai	ภาษาไทย
tr	Turkish	Türkçe
uk	Ukrainian	україньска
vi	Vietnamese	Tiểng Việt

Expand

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

Copy Code Light Theme

Note that both 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

			
				Code Sample
			
				Expected Output
			
				Expand
				
			if success then
	local translation = translator:Translate(game, "Screen")
	print(translation)
else
	warn("Cannot load translator for player!")
end
		
			Pantalla
		
			Copy Code
		
			Light Theme

If you call 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

			
				Code Sample
			
				Expected Output
			
				Expand
				
			if success then
	local keyTranslation = translator:FormatByKey("Key_Prize")
	print(keyTranslation)
else
	warn("Cannot load translator for player!")
end
		
			joyas
		
			Copy Code
		
			Light Theme

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.

			
				Code Sample
			
				Expected Output
			
				Expand
				
			if success then
	local keyTranslation1 = translator:FormatByKey("Key_Prize_1", {100})
	print(keyTranslation1)
	local keyTranslation2 = translator:FormatByKey("Key_Prize_2", {500, 100})
	print(keyTranslation2)
else
		
			100 joyas
$500.00 dinero y 100 joyas
		
			Copy Code
		
			Light Theme

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

			
				Code Sample
			
				Expected Output
			
				Expand
				
			if success then
	local keyTranslation1 = translator:FormatByKey("Key_Prize_1", {NumJewels=100})
	print(keyTranslation1)
	local keyTranslation2 = translator:FormatByKey("Key_Prize_2", {AmountCash=500, NumJewels=100})
	print(keyTranslation2)
else
		
			100 joyas
$500.00 dinero y 100 joyas
		
			Copy Code
		
			Light Theme

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:

Create a new ModuleScript within ReplicatedStorage.
Rename the new script TranslationHelper.
Copy the following code into the script.

Expand

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

Copy Code Light Theme

If your game's source language is not English, change the value of 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().

Expand

-- 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")

Copy Code Light Theme

Tags:

localization
language
translation
international
format

Utilizing Localization APIs

Utilizing Localization APIs

Loading a Translator

Player Locale

Specific Locale

Language Code Reference »

Translate()

FormatByKey()

Entering Keys »

Using Format Strings

Numbered Format Strings

Named Format Strings

Best Practices

Disable AutoLocalize

Error Handling

RELATED ARTICLES

Localization Portal – Additional Features

Localizing Non-Text Instances

Localization Format Strings

Animating Text

Localization FAQ and Troubleshooting