We use cookies on this site to enhance your user experience

Localizing Non-Text Instances

Localizing Non-Text Instances

Aug 29 2019, 9:16 AM PST 5 min

In special cases, it may be necessary to localize a non-text instance such as an image used for a shop sign or a spoken audio clip. In this case, unique assets for each supported language can be used.

Translation Module

The following module fetches any translation from the localization portal and uses error handling to catch potential failures from the web-based Translator APIs. 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)
local foundFallbackTranslator = pcall(function()
	fallbackTranslator = LocalizationService:GetTranslatorForLocaleAsync(sourceLanguageCode)

TranslationHelper.setSourceLanguage = function(languageCode)
	if sourceLanguageCode ~= languageCode then
		foundFallbackTranslator = pcall(function()
			fallbackTranslator = LocalizationService:GetTranslatorForLocaleAsync(sourceLanguageCode)
			sourceLanguageCode = languageCode
			return true
	return false

-- Translate function
TranslationHelper.translate = function(text, object)
	if not object then
		object = game
	local translation = ""
	local foundTranslation = false
	if foundPlayerTranslator then
		return playerTranslator:Translate(object, text)
	if foundFallbackTranslator then
		return fallbackTranslator:Translate(object, text)
	return false

-- 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)
	if foundFallbackTranslator and not foundTranslation then
		foundTranslation = pcall(function()
			translation = fallbackTranslator:FormatByKey(key, arguments)
	if foundTranslation then
		return translation
		return false

return TranslationHelper

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

Gathering Asset IDs

To implement localized assets, you should first gather the asset ID of each version, for instance:

English (Source) Spanish (es) Portuguese (pt)
rbxassetid://2957093606 rbxassetid://2957093671 rbxassetid://2957093727

Key and Translations

Instead of supplying string translations within the .csv spreadsheet or localization portal, enter the asset ID of the corresponding asset. Remember to also supply a Key value for lookup within the LocalScript outlined in the next section.

Key Context Source Example es pt
Key_JewelsImage 2957093606 2957093671 2957093727

Script Implementation

Before proceeding, confirm that:

  • The TranslationHelper script is located within ReplicatedStorage.
  • A .csv spreadsheet is uploaded to the localization portal containing a “Key_JewelsImage” key and a valid asset ID associated with each localized image.

Now copy the following code into a new LocalScript. Since this tutorial deals with GUI images, the script can be placed within StarterGui.

-- Static variables
local FALLBACK_IMAGE_ID = "924320031"

-- Roblox services
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local Players = game:GetService("Players")

-- Require translation module
local TranslationHelper = require(ReplicatedStorage:WaitForChild("TranslationHelper"))

-- Create new screen GUI
local player = Players.LocalPlayer
local playerGUI = player:WaitForChild("PlayerGui")
local screenGUI ="ScreenGui")
screenGUI.Parent = playerGUI

-- Create new image label
local localizedImage ="ImageLabel")
localizedImage.Size =, 185, 0, 170)
localizedImage.Position =, 40, 0, 40)
localizedImage.BackgroundTransparency = 1
localizedImage.Parent = screenGUI

-- Get asset ID from translation module
local localizedImageID = TranslationHelper.translateByKey("Key_JewelsImage")

-- Apply asset ID (or fallback ID) to image label
local success, errorMessage = pcall(function()
	localizedImage.Image = "rbxassetid://" .. localizedImageID
if not success then
	localizedImage.Image = "rbxassetid://" .. FALLBACK_IMAGE_ID

Playtest your game in Studio as outlined articles/localization portal additional features#test-localization|here and the correct image should appear for the configured languages/images.

  • localization
  • language
  • translation
  • international