Localisation avec des scripts

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 au tableau de localisation. Roblox fournit un LocalizationService pour gérer tous les besoins en matière de scripts de localisation. Utilisez le LocalizationService pour les tâches suivantes :

• Localiser les images et les sons.
• Traduire une partie des chaînes.
• Appliquer des traductions dans plusieurs langues.

Si vous utilisez des API de localisation lors de la traduction de votre expérience, restez attentif à tout changement de LocaleID de l'utilisateur afin de réagir aux utilisateurs qui changent de langue au cours d'une expérience.

Lorsque vous réutilisez un code de traduction, vous devez utiliser un ModuleScript TranslationHelper pour gérer les erreurs et les traductions manquantes.

Localiser les images et les sons.

Ne vous arrêtez pas à la localisation du texte de votre expérience. Proposez des images et des sons uniques en fonction du lieu où se trouve l'utilisateur. Pour localiser des éléments, ajoutez d'abord les ID source et cible des éléments au tableau de localisation de votre expérience, puis utilisez l'API de localisation pour récupérer les différents éléments.

Pour commencer à localiser les images et les sons, ajoutez les ID des éléments source et cible à votre tableau de localisation. Les entrées des ID d'éléments dans le tableau de localisation doivent inclure une clé comme identifiant pour être appelées par l'API. Voici un exemple d'entrée dans un tableau de localisation utilisant des ID d'éléments :

Le code suivant remplacera l'ID de l'élément d'un ImageLabel par l'ID d'élément espagnol fourni dans le tableau de localisation :

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

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

-- Load Translator for "es". Wrap the function within a pcall() to protect against failures.
local res, translator = pcall(function()
    return LocalizationService:GetTranslatorForLocaleAsync("es")
end)

if res then
    -- Get asset ID from localization table by referencing the Key
    localizedImageID = translator:FormatByKey("Key_JewelsImage")
    -- Set the image
    localizedImage.Image = "rbxassetid://" .. localizedImageID
else
    print('GetTranslatorForPlayerAsync failed: ' .. translator)
end

Traduire des chaînes

Dans certaines circonstances, vous voudrez peut-être cibler des chaînes spécifiques pour la traduction. Translator:Translate() peut récupérer des entrées spécifiques dans le tableau de localisation en fonction de la chaîne source.

Dans cet exemple, l'entrée de localisation suivante est utilisée :

Le script suivant imprime la traduction espagnole du mot écran dans la fenêtre Sortie :

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

-- Load Translator for "es". Wrap the function within a pcall() to protect against failures.
local res, translator = pcall(function()
    return LocalizationService:GetTranslatorForLocaleAsync("es")
end)

if res then
    -- Use Translate function, providing object context and string
    local sourceTranslation = translator:Translate(game, "Screen")
    print(sourceTranslation) -- Expected Output: "Pantalla"
else
    print('GetTranslatorForPlayerAsync failed: ' .. translator)
end

Utiliser les modifications contextuelles

Dans certains cas, une chaîne peut avoir plusieurs significations. Par exemple, le mot « screen » peut désigner aussi bien un « computer screen » (écran d'ordinateur) qu'une « window screen » (moustiquaire), mais les traductions espagnoles sont complètement différentes.

La colonne Contexte du tableau de localisation permet de spécifier des traductions par le biais de modifications contextuelles. Spécifiez l'objet en jeu dans votre tableau de localisation comme dans l'exemple suivant :

Le script suivant utilise une modification contextuelle pour donner la priorité à une traduction spécifique :

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

-- Load Translator for "es". Wrap the function within a pcall() to protect against failures.
local res, translator = pcall(function()
    return LocalizationService:GetTranslatorForLocaleAsync("es")
end)

if res then
    -- use Translate function, providing object context and string
    local sourceTranslation = translator:Translate( workspace.WindowScreen.SurfaceGui.TextLabel, "Screen")
    print(sourceTranslation) -- Expected Output: Mosquitero
else
    print('GetTranslatorForPlayerAsync failed: ' .. translator)
end

Contextes multiples

En cas de contextes multiples, le service de localisation compare les relations entre les objets dans le champ Contexte de droite à gauche, en utilisant la correspondance la plus appropriée.

Par exemple, un tableau de localisation dans votre expérience peut inclure les entrées suivantes de chaînes source partagées :

Si la chaîne « écran » est ajoutée à un objet playerGui.ScreenGui.TextLabel dans votre expérience, le service de localisation propose « Mosquitero » comme traduction espagnole car c'est la correspondance contextuelle la plus proche.

Paramètres de substitution

Lorsque vous utilisez des paramètres pour traduire un contenu dynamique, définissez les valeurs dans un tableau et passez-le en tant qu'argument par l'intermédiaire de l'API.

Dans cet exemple, l'expérience dispose d'un tableau de localisation comportant les entrées suivantes :

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

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

-- Load Translator for "es". Wrap the function within a pcall() to protect against failures.
local res, translator = pcall(function()
    return LocalizationService:GetTranslatorForLocaleAsync("es")
end)

if res then
    -- Set the parameter value in "Key_Prize_1" to 100
    local keyTranslation1 = translator:FormatByKey("Key_Prize_1", {100})
    print(keyTranslation1) -- Expected Output: 100 joyas

    -- Set multiple parameters to 500 and 100 by name
    local keyTranslation2 = translator:FormatByKey("Key_Prize_2", {AmountCash=500, NumJewels=100})
    print(keyTranslation2) -- Expected Output: $500.00 dinero y 100 joyas
else
    print('GetTranslatorForPlayerAsync failed: ' .. translator)
end

Changer de langue

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

L'exemple de code suivant configure un traducteur avec un code de pays manuel et un traducteur supplémentaire basé sur les paramètres régionaux de l'utilisateur :

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

-- Local variables
local player = Players.LocalPlayer

-- Load Translator for "pt". Wrap translator functions within a pcall() to protect against failures.
local res1, translator = pcall(function()
    return LocalizationService:GetTranslatorForLocaleAsync("pt")
end)

-- Load second Translator with Player's locale, in this example "es"
local res2, fallbackTranslator = pcall(function()
    return LocalizationService:GetTranslatorForPlayerAsync(player)
end)

-- Use Translate function with first Translator
if res1 then
    local translate1 = translator:Translate(game, "jewels")
    print(translate1) -- Expected Output in pt: joyas
else
    print('GetTranslatorForPlayerAsync failed: ' .. translator)
end

-- Use Translate function with second Translator
if res2 then
    local translate2 = fallbackTranslator:Translate(game, "jewels")
    print(translate2) -- Expected Output in if user is set to 'es': jóias
else
    print('GetTranslatorForPlayerAsync failed: ' .. fallbackTranslator)
end

Réagir aux utilisateurs qui changent de langue

Les utilisateurs peuvent modifier la langue de leur expérience à tout moment grâce aux Paramètres. Ce changement de paramètre utilisateur met automatiquement à jour les éléments de localisation non scriptés, tels que les chaînes gérées par traduction automatique, il se peut cependant qu'il ne mette pas à jour les modifications de localisation scriptées qui ont déjà été effectuées, telles que les images ou les sons de la GUI.

Pour garantir la mise à jour adéquate de vos éléments localisés, écoutez l'événement GetPropertyChangedSignal concernant les modifications de la propriété LocaleID de l'instance Translator renvoyée par LocalizationService.GetTranslatorForPlayerAsync. Lors de l'utilisation de LocalizationService.GetTranslatorForPlayerAsync, entourez la fonction d'un pcall en cas d'erreur.

L'exemple de code suivant imprime l'ID local de l'utilisateur et l'ID local de l'instance Traducteur de l'utilisateur lorsque ce dernier change de langue :

local LocalizationService = game:GetService("LocalizationService")
local Players = game:GetService("Players")
local player = Players.LocalPlayer

-- If GetTranslatorForPlayerAsync succeeds, it will return a Translator for player's current locale
local res, translator = pcall(function()
    return LocalizationService:GetTranslatorForPlayerAsync(player)
end)

-- Function that gets called when change in player's locale ID is detected
local function OnLocaleIdChanged()
    print("Translator has changed to: " .. translator.LocaleId)
    -- You should re-translate any assets translated with Localization APIs to the player's new language here
end

-- Check if GetTranslatorForPlayerAsync succeeded
if res then
    -- If succeeded, translate assets here using translator
    -- Listen for a change in player's locale ID
    translator:GetPropertyChangedSignal("LocaleId"):Connect(OnLocaleIdChanged)
else
    print('GetTranslatorForPlayerAsync failed: ' .. translator)
end

Créer un module TranslationHelper

Lorsque vous chargez des traducteurs basés sur les paramètres régionaux par défaut de l'utilisateur, vous pouvez réutiliser le code. Pour réutiliser le code, créez un assistant ModuleScript qui charge les traducteurs en toute sécurité en fonction des paramètres régionaux par défaut du lecteur et inclut des fonctions permettant de fournir des traductions spécifiques et de 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")

-- Local variables
local player = Players.LocalPlayer
local sourceLanguageCode = "en"

-- Get translators
local playerTranslator, fallbackTranslator
local foundPlayerTranslator = pcall(function()
    playerTranslator = LocalizationService:GetTranslatorForPlayerAsync(player)
end)
local foundFallbackTranslator = pcall(function()
    fallbackTranslator = LocalizationService:GetTranslatorForLocaleAsync(sourceLanguageCode)
end)

-- Create a method TranslationHelper.setLanguage to load a new translation for the TranslationHelper
function TranslationHelper.setLanguage(newLanguageCode)
    if sourceLanguageCode ~= newLanguageCode then
        local success, newPlayerTranslator = pcall(function()
            return LocalizationService:GetTranslatorForLocaleAsync(newLanguageCode)
        end)

        --Only override current playerTranslator if the new one is valid (fallbackTranslator remains as experience's source language)
        if success and newPlayerTranslator then
            playerTranslator = newPlayerTranslator
            return true
        end
    end
    return false
end

-- Create a Translate function that uses a fallback translator if the first fails to load or return successfully. You can also set the referenced object to default to the generic game object

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

-- Create a FormatByKey() function that uses a fallback translator if the first fails to load or return successfully

function TranslationHelper.translateByKey(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)
        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 se trouve dans ReplicatedStorage, sollicitez-le à partir d'un LocalScript pour appeler les fonctions du module. Le code suivant utilise la fonction d'aide de ce module pour traduire une chaîne particulière :

local ReplicatedStorage = game:GetService("ReplicatedStorage")

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

-- Use the functions provided in TranslationHelper
TranslationHelper.setLanguage("es")
local sourceTranslation = TranslationHelper.translate("Screen")
print(sourceTranslation) -- Expected Output in 'es': "Pantalla"