Localisation avec des scripts

Vous pouvez utiliser les API de localisation pour des tâches de traduction spécialisées qui ne sont pas gérées automatiquement par ajouter des traductions à la table de localisation. Roblox fournit un LocalizationService pour gérer toutes les besoins de scripting de localisation. Utilisez le LocalizationService pour les tâches suivantes :

• Localiser les images et les sons.
• Traduire une partie des chaînes individuelles .
• Appliquer les traductions à partir de plusieurs langues .

Si vous utilisez des API de localisation lors de la traduction de votre expérience, écoutez les modifications de l'ID de localisation de l'utilisateur pour réagir aux utilisateurs qui changent de langue pendant qu'ils sont dans une expérience.

Lors de la réutilisation du code de traduction, vous devriez utiliser un TranslationHelperModuleScript pour gérer les erreurs et les traductions manquantes.

Localiser les images et les sons

Ajoutez de la localisation au-delà du texte dans votre expérience en fournissant des images et des sons uniques basés sur le lieu d'un utilisateur. Pour localiser les ressources, ajoutez d'abord les ID de ressource source et cible à la table de localisation de votre expérience puis utilisez l'API de localisation pour obtenir les différentes ressources.

Pour commencer à localiser les images et les sons, ajoutez vos sources et cibles à votre table de localisation. Les entrées de l'ID de la ressource dans la table de localisation doivent inclure un 0> clé 0> comme identifiant pour être appelées par l'API.

Ce qui suit est une entrée d'exemple dans une table de localisation en utilisant des ID de ressources :

Le code suivant remplacera l'ID de la ressource d'un ImageLabel par l'ID de la ressource espagnole fourni dans la table de localisation :

local ReplicatedStorage = game:GetService("ReplicatedStorage")
local LocalizationService = game:GetService("LocalizationService")

-- Variable local
local localizedImageID
local localizedImage = Instance.new("ImageLabel")

-- Chargez le traducteur pour "es". Wrap the function within a pcall() to protect against failures.
local res, translator = pcall(function()
	return LocalizationService:GetTranslatorForLocaleAsync("es")
end)

if res then
	-- Obtenez l'ID de la ressource à partir de la table de localisation en référençant la clé
	localizedImageID = translator:FormatByKey("Key_JewelsImage")
	-- Définir l'image
	localizedImage.Image = "rbxassetid://" .. localizedImageID
else
	print('GetTranslatorForPlayerAsync failed: ' .. translator)
end

Traduire des chaînes individuelles

Dans certaines situations, vous voudrez peut-être cibler des chaînes individuelles pour la traduction. Translator:Translate() peut récupérer des entrées individuelles sur la table de localisation en fonction de la chaîne source.

Dans l'exemple suivant, la sélection de localisation suivante est utilisée :

Le script suivant imprimera la traduction espagnole de « Screen » dans la Fenêtre de sortie :

local ReplicatedStorage = game:GetService("ReplicatedStorage")
local LocalizationService = game:GetService("LocalizationService")

-- Chargez le traducteur pour "es". Wrap the function within a pcall() to protect against failures.
local res, translator = pcall(function()
	return LocalizationService:GetTranslatorForLocaleAsync("es")
end)

if res then
	-- Utilisez la fonction Traduire, qui fournit un contexte d'objet et une chaîne
	local sourceTranslation = translator:Translate(game, "Screen")
	print(sourceTranslation) -- Sortie attendue : "Pantalla"
else
	print('GetTranslatorForPlayerAsync failed: ' .. translator)
end

Utiliser les contextes d'annulation

Il y a quelques 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 complètement différentes.

La colonne Contexte de la table de localisation est utilisée pour spécifier les traductions par le biais d'une modification contextuelle. Spécifiez l'objet dans le jeu sur votre table de localisation comme dans l'exemple suivant :

Le script suivant utilise une覆盖 contextuelle pour prioriser une traduction spécifique :

local ReplicatedStorage = game:GetService("ReplicatedStorage")
local LocalizationService = game:GetService("LocalizationService")

-- Chargez le traducteur pour "es". Wrap the function within a pcall() to protect against failures.
local res, translator = pcall(function()
	return LocalizationService:GetTranslatorForLocaleAsync("es")
end)

if res then
	-- utiliser la fonction Traduire, qui fournit un contexte d'objet et une chaîne
	local sourceTranslation = translator:Translate( workspace.WindowScreen.SurfaceGui.TextLabel, "Screen")
	print(sourceTranslation) -- Sortie attendue : Mosquito
else
	print('GetTranslatorForPlayerAsync failed: ' .. translator)
end

Multiples contextes

Dans le cas de plusieurs contextes, le service de localisation compare les relations d'objet dans le champ contextuel à partir de droite à gauche , en utilisant le correspondrele plus proche.

Par exemple, une table de localisation dans votre expérience peut avoir les entrées suivantes des chaînes de données partagées :

Si la chaîne « Screen » est ajoutée à un playerGui.ScreenGui.TextLabel objet dans votre expérience, le service de localisation affiche « Mosquitero » comme la traduction espagnole en tant que correspondrele plus proche.

Paramètres de substitution

Lors de l'utilisation de paramètres pour traduire du contenu dynamique, définissez les valeurs dans une table et transmettez la table en tant qu'argument à travers l'API.

Dans cet exemple, l'expérience a une table de localisation avec les entrées suivantes :

Utilisez l'exemple de code suivant pour traduire ces chaînes avec des valeurs de paramètre :

local ReplicatedStorage = game:GetService("ReplicatedStorage")
local LocalizationService = game:GetService("LocalizationService")

-- Chargez le traducteur pour "es". Wrap the function within a pcall() to protect against failures.
local res, translator = pcall(function()
	return LocalizationService:GetTranslatorForLocaleAsync("es")
end)

if res then
	-- Définissez la valeur du paramètre « Key_Prize_1 » à 100
	local keyTranslation1 = translator:FormatByKey("Key_Prize_1", {100})
	print(keyTranslation1) -- Production 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) -- Production attendue : 500.00 $ en espèces et 100 bijoux
else
	print('GetTranslatorForPlayerAsync failed: ' .. translator)
end

Changement de langue

Dans certains cas, vous voudrez peut-être afficher les traductions d'autres langues dans votre expérience. Vous pouvez configurer un nouveau traducteur avec un code de pays différent en utilisant LocalizationService:GetTranslatorForLocaleAsync() .

L'exemple de code suivant définit un traducteur avec un code de pays manuel et un traducteur basé sur les paramètres de langue globaux de l'utilisateur :

local ReplicatedStorage = game:GetService("ReplicatedStorage")
local LocalizationService = game:GetService("LocalizationService")
local Players = game:GetService("Players")

-- Variable local
local player = Players.LocalPlayer

-- Chargez le traducteur pour «pt». Wrap traducteur functions within a pcall() to protect against failures.
local res1, translator = pcall(function()
	return LocalizationService:GetTranslatorForLocaleAsync("pt")
end)

-- Chargez le deuxième Traducteur avec le lieu de résidence du joueur, dans cet exemple "es"
local res2, fallbackTranslator = pcall(function()
	return LocalizationService:GetTranslatorForPlayerAsync(player)
end)

-- Utiliser la fonction Traduire avec le premier Traducteur
if res1 then
	local translate1 = translator:Translate(game, "jewels")
	print(translate1) -- Output attendu dans pt: joyas
else
	print('GetTranslatorForPlayerAsync failed: ' .. translator)
end

-- Utiliser la fonction Traduire avec le deuxième Traducteur
if res2 then
	local translate2 = fallbackTranslator:Translate(game, "jewels")
	print(translate2) -- Production attendue dans si l'utilisateur est réglé sur « es » : jóias
else
	print('GetTranslatorForPlayerAsync failed: ' .. fallbackTranslator)
end

Réagir aux utilisateurs qui changent de langue

Les utilisateurs peuvent modifier leurs paramètres de langue à tout moment en utilisant leur menu de paramètres dans l'expérience. Ce paramètre d'utilisateur change automatiquement les ressources de localisation non scriptées, telles que les chaînes gérées par la traduction automatique, mais peut ne pas mettre à jour les ressources de localisation scriptées qui ont déjà été rendues, telles que les images et les sons GUI.

Pour vous assurer que vos ressources localisées mises à jour correctement, écoutez l'événement GetPropertyChangedSignal pour les modifications dans la propriété LocaleID de la instance Translator retournée par Class.

L'exemple de code suivant imprime l'ID local de l'utilisateur et l'ID local de l'instance de Traducteur pour l'utilisateur lorsque l'utilisateur 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 lieu actuel du joueur
local res, translator = pcall(function()
	return LocalizationService:GetTranslatorForPlayerAsync(player)
end)

-- Fonction qui s'exécute lorsque l'ID de la langue du joueur est modifié
local function OnLocaleIdChanged()
	print("Translator has changed to: " .. translator.LocaleId)
	-- Vous devriez traduire à nouveau n'importe quelle ressource traduite avec les API de localisation vers la nouvelle langue du joueur ici
end

-- Vérifier si GetTranslatorForPlayerAsync a réussi
if res then
	-- Si vous y êtes parvenu, traduisez les ressources ici en utilisant le traducteur
	-- Écoutez pour un changement dans l'identifiant de la langue du joueur
	translator:GetPropertyChangedSignal("LocaleId"):Connect(OnLocaleIdChanged)
else
	print('GetTranslatorForPlayerAsync failed: ' .. translator)
end

Créer un module de traduction

Lorsque vous chargez des traducteurs en fonction de la langue par défaut du joueur, vous pourriez réutiliser du code. Pour réutiliser du code, configurez un ModuleScript aideur qui charge en sécurité les traducteurs en fonction de la langue par défaut du joueur et inclut des fonctions pour fournir des traductions spécifiques et changer de langue.

L'exemple de 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")

-- Variable local
local player = Players.LocalPlayer
local sourceLanguageCode = "en"

-- Obtenez des 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 pas écraser le nouvel outil de traduction si le nouvel outil est valide (fallbackTranslator reste comme langue source de l'expérience)
		if success and newPlayerTranslator then
			playerTranslator = newPlayerTranslator
			return true
		end
	end
	return false
end

-- Créez une fonction de traduction qui utilise un traducteur par défaut si le premier échec le chargement ou le retour avec succès. Vous pouvez également définir l'objet de référence par défaut à l'objet de jeu 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éez une fonction par clé qui utilise un traducteur par défaut si la première échec de chargement ou de retour avec succès

function TranslationHelper.translateByKey(key, arguments)
	local translation = ""
	local foundTranslation = false

	-- Tentez d'abord de traduire dans 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 que le module est dans ReplicatedStorage, exigez-le à partir d'un LocalScript pour appeler les fonctions du module. Le code suivant utilise la fonction d'aide du module pour traduire une chaîne individuelle :

local ReplicatedStorage = game:GetService("ReplicatedStorage")

-- Exige un module de traduction
local TranslationHelper = require(ReplicatedStorage:WaitForChild("TranslationHelper"))

-- Utilisez les fonctions fournies dans TranslationHelper
TranslationHelper.setLanguage("es")
local sourceTranslation = TranslationHelper.translate("Screen")
print(sourceTranslation) -- Expected Output in 'es': "Pantalla"