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

Utilizing Localization APIs

Utilizing Localization APIs

Mar 15 2019, 8:38 PM 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.

Use of localization APIs requires identifier keys for all of your source items. 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

Spreadsheet Entry

  1. Download the .csv spreadsheet from the portal as outlined articles/localization portal additional features#localizing-with-csv-files|here.
  2. Specify a Key value for the desired rows:
A B C D E
Key Context Source Example es
Key_StartButton Start Iniciar
Key_OptionsButton Options Opciones
 
  1. Save the spreadsheet in .csv format and articles/localization portal additional features#upload-csv-file|upload it to the portal.

Direct Entry

  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.

Getting a Translator Instance

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 locale code via LocalizationService/GetTranslatorForLocaleAsync|GetTranslatorForLocaleAsync().

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

Formatting By Key

Once the Translator is successfully loaded, you can use Translator/FormatByKey|FormatByKey() to fetch translations from the localization portal. For instance, the print() statement on line 9 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

Translator/FormatByKey|FormatByKey() 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 Spanish translation which contains a numbered format string, {1:int}:

A B C D E
Key Context Source Example es
Key_Prize {1:int} jewels {1:int} joyas
 

To format this for an amount of 100 jewels, pass a Lua array containing the amount ({100}) as the second argument to Translator/FormatByKey|FormatByKey(). With this addition, the print() statement will output “100 joyas” when you playtest in Spanish.

The same principle applies if translations contain multiple numbered format strings, for instance {1:fixed} and {2:int}:

A B C D E
Key Context Source Example es
Key_Prize ${1:fixed} cash and {2:int} jewels ${1:fixed} dinero y {2:int} joyas
 

To format this for an amount of 500 cash and 100 jewels, pass a Lua array containing both amounts ({500, 100}) to Translator/FormatByKey|FormatByKey():

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 {NumJewels:int} jewels {NumJewels:int} joyas
 

If translations contain multiple named format strings, for instance {AmountCash:fixed} and {NumJewels:int}, simply include both key-value pairs in the array:

A B C D E
Key Context Source Example es
Key_Prize {AmountCash:fixed} cash and {NumJewels:int} jewels {AmountCash:fixed} dinero y {NumJewels:int} joyas
 
Caution – Avoid Mixed Format Strings

When specifying multiple format strings in a single translation, remember that you cannot mix numbered and named types.

${1:fixed} cash and {2:int} jewels
${AmountCash:fixed} cash and {NumJewels:int} jewels
${1:fixed} cash and {NumJewels:int} jewels

Disabling 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.

Tags:
  • localization
  • language
  • translation
  • international
  • format