Localiser avec le script

*Ce contenu est traduit en utilisant l'IA (Beta) et peut contenir des erreurs. Pour consulter cette page en anglais, clique ici.

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.

Anglais (Source) - rbxassetid://2957093606
Espagnol (es) - rbxassetid://2957093671
Portugais (pt) - rbxassetid://2957093727

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éSourceespt
Key_JewelsImage295709360629570936712957093727

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 :

Sourceesespt
ÉcranPantalla2950936712957093727

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 :

ContexteSourcees
workspace.WindowScreen.SurfaceGui.TextLabelÉcranMosquitero
ÉcranPantalla

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 :

ContexteSourcees
workspace.WindowScreen.SurfaceGui.TextLabelÉcranMosquitero
playerGui.ScreenGui.TextButtonÉcranPantalla

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éSourcees
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.

Paramètre de langue dans le jeu
Les utilisateurs peuvent choisir les langues disponibles définies dans le jeu

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 traduction
local TranslationHelper = require(ReplicatedStorage:WaitForChild("TranslationHelper"))
-- Utilisez les fonctions fournies dans TranslationHelper
TranslationHelper.setLanguage("es")
local sourceTranslation = TranslationHelper.translate("Écran")
print(sourceTranslation) -- Sortie attendue en 'es' : "Pantalla"
©2026 Société Roblox. Roblox, le logo Roblox et Powering Imagination font partie de nos marques déposées aux États-Unis et dans d'autres pays.