Vous pouvez utiliser les API de localisation pour des tâches de traduction spécialisées qui ne sont pas automatiquement gérées par l'ajout de traductions dans la table de localisation. Roblox fournit un LocalizationService pour gérer tous vos besoins de scripting de localisation. Utilisez le LocalizationService pour les tâches suivantes :
Si vous utilisez des API de localisation lors de la traduction de votre jeu, écoutez tout changement du LocaleID de l'utilisateur pour réagir aux changements de langue des utilisateurs pendant un jeu.
Lors de la réutilisation du code de traduction, vous devriez utiliser un ModuleScript TranslationHelper pour gérer les erreurs et les traductions manquantes.
Localiser des images et des sons
Ajoutez de la localisation au-delà du texte dans votre jeu en fournissant des images et des sons uniques en fonction du locale de l'utilisateur. Pour localiser des actifs, commencez par ajouter les ID de source et cible à la table de localisation de votre jeu, puis utilisez l'API de localisation pour récupérer les différents actifs.



Pour commencer à localiser des images et des sons, ajoutez vos ID de source et de cible à votre table de localisation. Les entrées des ID d'actifs dans la table de localisation doivent inclure une Clé en tant qu'identifiant à appeler par l'API.
Voici un exemple d'entrée dans une table de localisation utilisant des ID d'actifs :
| Clé | Source | es | pt |
|---|---|---|---|
| Key_JewelsImage | 2957093606 | 2957093671 | 2957093727 |
Le code suivant remplacera l'ID d'actif d'un ImageLabel par l'ID d'actif espagnol fourni dans la table de localisation :
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local LocalizationService = game:GetService("LocalizationService")
-- Variables locales
local localizedImageID
local localizedImage = Instance.new("ImageLabel")
-- Charger le traducteur pour "es". Enveloppez la fonction dans un pcall() pour protéger contre les échecs.
local res, translator = pcall(function()
return LocalizationService:GetTranslatorForLocaleAsync("es")
end)
if res then
-- Obtenir l'ID d'actif de la table de localisation en référant à la clé
localizedImageID = translator:FormatByKey("Key_JewelsImage")
-- Définir l'image
localizedImage.Image = "rbxassetid://" .. localizedImageID
else
print('GetTranslatorForPlayerAsync a échoué : ' .. translator)
end
Traduire des chaînes individuelles
Dans certaines circonstances, vous souhaitez peut-être cibler des chaînes individuelles pour traduction. Translator:Translate() peut récupérer des entrées individuelles dans la table de localisation en fonction de la chaîne source.
Dans l'exemple suivant, l'entrée de localisation suivante est utilisée :
| Source | es | es | pt |
|---|---|---|---|
| Écran | Pantalla | 295093671 | 2957093727 |
Le script suivant affichera la traduction espagnole de "Écran" dans la fenêtre Sortie :
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local LocalizationService = game:GetService("LocalizationService")
-- Charger le traducteur pour "es". Enveloppez la fonction dans un pcall() pour protéger contre les échecs.
local res, translator = pcall(function()
return LocalizationService:GetTranslatorForLocaleAsync("es")
end)
if res then
-- Utiliser la fonction Translate, en fournissant le contexte de l'objet et la chaîne
local sourceTranslation = translator:Translate(game, "Écran")
print(sourceTranslation) -- Sortie attendue : "Pantalla"
else
print('GetTranslatorForPlayerAsync a échoué : ' .. translator)
end
Utiliser des substitutions de contexte
Il existe des cas où la même chaîne peut avoir plusieurs significations. Par exemple, le mot "Écran" peut indiquer à la fois un écran d'ordinateur et un écran de fenêtre, mais les traductions espagnoles sont totalement différentes.
La colonne Contexte de la table de localisation est destinée à spécifier les traductions via des substitutions de contexte. Spécifiez l'objet de jeu dans votre table de localisation comme dans l'exemple suivant :
| Contexte | Source | es |
|---|---|---|
| workspace.WindowScreen.SurfaceGui.TextLabel | Écran | Mosquitero |
| Écran | Pantalla |
Le script suivant utilise une substitution de contexte pour prioriser une traduction spécifique :
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local LocalizationService = game:GetService("LocalizationService")
local Workspace = game:GetService("Workspace")
-- Charger le traducteur pour "es". Enveloppez la fonction dans un pcall() pour protéger contre les échecs.
local res, translator = pcall(function()
return LocalizationService:GetTranslatorForLocaleAsync("es")
end)
if res then
-- utiliser la fonction Translate, en fournissant le contexte de l'objet et la chaîne
local sourceTranslation = translator:Translate(Workspace.WindowScreen.SurfaceGui.TextLabel, "Écran")
print(sourceTranslation) -- Sortie attendue : Mosquitero
else
print('GetTranslatorForPlayerAsync a échoué : ' .. translator)
end
Contextes multiples
Dans le cas de contextes multiples, le service de localisation compare les relations d'objets dans le champ Contexte de droite à gauche, en utilisant la correspondance la plus proche.
Par exemple, une table de localisation dans votre jeu peut avoir les entrées de chaînes Source suivantes partagées :
| Contexte | Source | es |
|---|---|---|
| workspace.WindowScreen.SurfaceGui.TextLabel | Écran | Mosquitero |
| playerGui.ScreenGui.TextButton | Écran | Pantalla |
Si la chaîne "Écran" est ajoutée à un objet playerGui.ScreenGui.TextLabel dans votre jeu, le service de localisation affichera "Mosquitero" comme traduction espagnole étant la correspondance de contexte la plus proche.
Substituer des paramètres
Lors de l'utilisation de paramètres pour traduire du contenu dynamique, définissez les valeurs dans un tableau et passez le tableau en tant qu'argument via l'API.
Dans cet exemple, le jeu dispose d'une table de localisation avec les entrées suivantes :
| Clé | Source | es |
|---|---|---|
| Key_Prize_1 | {1:int} jewels | {1:int} joyas |
| Key_Prize_2 | ${AmountCash:fixed} cash and {NumJewels:int} jewels | ${AmountCash:fixed} dinero y {NumJewels:int} joyas |
Utilisez le code suivant pour traduire ces chaînes avec des valeurs de paramètres :
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local LocalizationService = game:GetService("LocalizationService")
-- Charger le traducteur pour "es". Enveloppez la fonction dans un pcall() pour protéger contre les échecs.
local res, translator = pcall(function()
return LocalizationService:GetTranslatorForLocaleAsync("es")
end)
if res then
-- Définir la valeur de paramètre dans "Key_Prize_1" à 100
local keyTranslation1 = translator:FormatByKey("Key_Prize_1", {100})
print(keyTranslation1) -- Sortie attendue : 100 joyas
-- Définir plusieurs paramètres à 500 et 100 par nom
local keyTranslation2 = translator:FormatByKey("Key_Prize_2", {AmountCash=500, NumJewels=100})
print(keyTranslation2) -- Sortie attendue : $500.00 dinero y 100 joyas
else
print('GetTranslatorForPlayerAsync a échoué : ' .. translator)
end
Changer de langues
Dans certains cas, vous souhaiterez peut-être afficher des traductions d'autres langues dans votre jeu. Vous pouvez définir un nouveau traducteur avec un code de pays différent en utilisant LocalizationService:GetTranslatorForLocaleAsync().
Le code suivant définit un traducteur avec un code de pays manuel et un traducteur supplémentaire basé sur les paramètres régionaux globaux de l'utilisateur :
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local LocalizationService = game:GetService("LocalizationService")
local Players = game:GetService("Players")
-- Variables locales
local player = Players.LocalPlayer
-- Charger le traducteur pour "pt". Enveloppez les fonctions du traducteur dans un pcall() pour protéger contre les échecs.
local res1, translator = pcall(function()
return LocalizationService:GetTranslatorForLocaleAsync("pt")
end)
-- Charger un deuxième traducteur avec les paramètres de l'utilisateur, dans cet exemple "es"
local res2, fallbackTranslator = pcall(function()
return LocalizationService:GetTranslatorForPlayerAsync(player)
end)
-- Utiliser la fonction Translate avec le premier traducteur
if res1 then
local translate1 = translator:Translate(game, "jewels")
print(translate1) -- Sortie attendue en pt : joyas
else
print('GetTranslatorForPlayerAsync a échoué : ' .. translator)
end
-- Utiliser la fonction Translate avec le deuxième traducteur
if res2 then
local translate2 = fallbackTranslator:Translate(game, "jewels")
print(translate2) -- Sortie attendue si l'utilisateur est défini sur 'es' : jóias
else
print('GetTranslatorForPlayerAsync a échoué : ' .. fallbackTranslator)
end
Réagir aux changements de langue des utilisateurs
Les utilisateurs peuvent changer leurs paramètres de langue à tout moment en utilisant leur menu Paramètres dans le jeu. Ce changement de paramètre utilisateur met à jour automatiquement les actifs de localisation non scriptés, tels que les chaînes gérées par traduction automatique, mais il se peut qu'il ne mette pas à jour les modifications de localisation scriptées qui ont déjà été rendues, telles que les images ou les sons de l'interface utilisateur.


Pour garantir que vos actifs localisés par script se mettent à jour correctement, écoutez l'événement GetPropertyChangedSignal pour les changements de la propriété LocaleID de l'instance Translator renvoyée par LocalizationService.GetTranslatorForPlayerAsync. Lorsque vous utilisez LocalizationService.GetTranslatorForPlayerAsync, enveloppez la fonction dans un pcall() en cas d'erreurs.
Le code suivant affiche l'ID Locale de l'utilisateur et l'ID Locale de l'instance Translator pour l'utilisateur lorsque celui-ci change de langue :
local LocalizationService = game:GetService("LocalizationService")
local Players = game:GetService("Players")
local player = Players.LocalPlayer
-- Si GetTranslatorForPlayerAsync réussit, il renverra un traducteur pour le paramètre régional actuel du joueur
local res, translator = pcall(function()
return LocalizationService:GetTranslatorForPlayerAsync(player)
end)
-- Fonction qui est appelée lorsqu'un changement de l'ID de locale du joueur est détecté
local function OnLocaleIdChanged()
print("Le traducteur a changé à : " .. translator.LocaleId)
-- Vous devriez retraduire ici tous les actifs traduits avec les APIs de localisation pour la nouvelle langue du joueur
end
-- Vérifiez si GetTranslatorForPlayerAsync a réussi
if res then
-- Si succès, traduisez les actifs ici en utilisant le traducteur
-- Écoutez un changement dans l'ID de locale du joueur
translator:GetPropertyChangedSignal("LocaleId"):Connect(OnLocaleIdChanged)
else
print('GetTranslatorForPlayerAsync a échoué : ' .. translator)
end
Créer un module TranslationHelper
Lorsque vous chargez des traducteurs en fonction de la langue par défaut du joueur, vous pourriez réutiliser du code. Pour réutiliser le code, configurez un ModuleScript d'aide qui charge en toute sécurité des traducteurs en fonction de la langue par défaut du joueur et inclut des fonctions pour fournir des traductions spécifiques et changer de langues.
Le code suivant implémente un TranslationHelper que vous pouvez copier dans votre propre projet en tant que ModuleScript dans ReplicatedStorage :
local TranslationHelper = {}
local LocalizationService = game:GetService("LocalizationService")
local Players = game:GetService("Players")
-- Variables locales
local player = Players.LocalPlayer
local sourceLanguageCode = "en"
-- Obtenir les traducteurs
local playerTranslator, fallbackTranslator
local foundPlayerTranslator = pcall(function()
playerTranslator = LocalizationService:GetTranslatorForPlayerAsync(player)
end)
local foundFallbackTranslator = pcall(function()
fallbackTranslator = LocalizationService:GetTranslatorForLocaleAsync(sourceLanguageCode)
end)
-- Créer une méthode TranslationHelper.setLanguage pour charger une nouvelle traduction pour le TranslationHelper
function TranslationHelper.setLanguage(newLanguageCode)
if sourceLanguageCode ~= newLanguageCode then
local success, newPlayerTranslator = pcall(function()
return LocalizationService:GetTranslatorForLocaleAsync(newLanguageCode)
end)
-- Ne remplacer le current playerTranslator que si le nouveau est valide (fallbackTranslator reste la langue source du jeu)
if success and newPlayerTranslator then
playerTranslator = newPlayerTranslator
return true
end
end
return false
end
-- Créer une fonction Translate qui utilise un traducteur de secours si le premier échoue à se charger ou à renvoyer avec succès. Vous pouvez également définir l'objet de référence pour qu'il par défaut à l'objet générique
function TranslationHelper.translate(text, object)
if not object then
object = game
end
if foundPlayerTranslator then
return playerTranslator:Translate(object, text)
end
if foundFallbackTranslator then
return fallbackTranslator:Translate(object, text)
end
return false
end
-- Créer une fonction FormatByKey() qui utilise un traducteur de secours si le premier échoue à se charger ou à renvoyer avec succès
function TranslationHelper.translateByKey(key, arguments)
local translation = ""
local foundTranslation = false
-- Essaie d'abord de traduire pour la langue du joueur (si un traducteur a été trouvé)
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
Une fois le module dans ReplicatedStorage, exigez-le depuis un LocalScript pour appeler les fonctions du module. Le code suivant utilise cette fonction d'assistance du module pour traduire une chaîne individuelle :
local ReplicatedStorage = game:GetService("ReplicatedStorage")-- Exiger le module de traductionlocal TranslationHelper = require(ReplicatedStorage:WaitForChild("TranslationHelper"))-- Utilisez les fonctions fournies dans TranslationHelperTranslationHelper.setLanguage("es")local sourceTranslation = TranslationHelper.translate("Écran")print(sourceTranslation) -- Sortie attendue en 'es' : "Pantalla"