Localize UI elements sample SharePoint Add-in

L’exemple de add-in Core.JavaScriptCustomization vous montre comment utiliser JavaScript pour remplacer la valeur de texte d’un élément d’interface utilisateur SharePoint par une valeur de texte traduite, qui est lue à partir d’un fichier de ressources JavaScript.

Notes

Vous êtes responsable de la maintenance des valeurs de texte traduites dans le fichier de ressources JavaScript.

Important

Les personnalisations basées sur JSLink (rendu côté client) ne sont pas prises en charge dans les expériences modernes. Cela inclut les bibliothèques et les listes modernes, y compris la prise en charge de JSLink dans les composants WebPart d’affichage de liste de pages modernes. Le rendu côté client est pris en charge dans les expériences classiques dans SharePoint Online ou en local.

Cet exemple de code utilise un add-in hébergé par un fournisseur pour :

  • Localisez le titre d’une page de site ou d’un lien de lancement rapide avec des valeurs de texte spécifiques.
  • Conservez une page de site ou le titre du lien Lancement rapide dans une langue principale, et fournissez des versions traduites de la page de site et le titre du lien Lancement rapide dans une autre langue au moment de l’utilisation.
  • Utilisez les fichiers de ressources JavaScript pour la localisation côté client.
  • Lier un fichier JavaScript à un site SharePoint à l’aide d’une action personnalisée.
  • Vérifiez la culture d’interface utilisateur du site, puis chargez les valeurs de texte propres à la culture à partir d’un fichier de ressources JavaScript.
  • Overwrite site page and Quick Launch link titles with culture-specific text values by using jQuery.

Avant de commencer

To get started, download the Core.JavaScriptCustomization sample add-in from the Office 365 Developer patterns and practices project on GitHub.

Avant d’exécuter cet exemple de code, exécutez les étapes suivantes.

Configurer les paramètres de langue sur votre site

  1. Sur votre site d’équipe, choisissez Paramètres > paramètres du site.

  2. Dans l’Administration du site, choisissez les paramètres de langue.

  3. Dans la page Langue Paramètres, dans les autres langues, choisissez les autres langues que votre site doit prendre en charge. Par exemple, choisissez finnois et français, comme illustré dans la figure suivante.

    Capture d’écran de la page des paramètres de langue des paramètres du site

  4. Sélectionnez OK.

Définir la langue d’affichage sur la page de profil de votre utilisateur

  1. Dans le haut de votre site Office 365, choisissez votre photo de profil, puis cliquez sur À mon sujet.

    Capture d’écran de la page de profil de l’utilisateur avec les informations personnelles en surbrillance

  2. On the About me page, choose Edit your profile.

  3. Choisissez les ellipses (...) pour les options supplémentaires, puis choisissez Langue et Région.

  4. Dans Mes langues d’affichage, choisissez une nouvelle langue dans la liste Sélectionner une nouvelle langue, puis choisissez Ajouter. Par exemple, choisissez finnois et français. Vous pouvez déplacer votre langue préférée vers le haut ou vers le bas en choisissant les flèches vers le haut et vers le bas.

    Capture d’écran de la section Langue et région de la page Modifier les détails

  5. Cliquez sur Enregistrer tout et fermer.

Notes

Le rendu de votre site dans la ou les langues sélectionnées peut prendre quelques minutes.

Important

Le modèle CSOM est régulièrement mis à jour avec de nouvelles fonctionnalités. Si le modèle CSOM fournit de nouvelles fonctionnalités pour mettre à jour la page de site ou les titres des liens de lancement rapide, nous vous recommandons d’utiliser les nouvelles fonctionnalités du modèle CSOM au lieu des options abordées ici.

Avant d’exécuter le scénario 2 de cet exemple de code, exécutez les tâches suivantes.

  1. Sur le site web hôte, choisissez MODIFIER LES LIENS.

  2. Choose link.

    Capture d’écran de la page MODIFIER LES LIENS avec le lien en surbrillance

  3. Dans Texte à afficher, entrez Mon entrée delaunch rapide.

  4. Dans Adresse, entrez l’URL d’un site web.

  5. Choose OK > Save.

Créer une page de site

  1. Sur le site web hôte, sélectionnez Pages du site Contenu du > site > Nouveau.
  2. Dans le nouveau nom de page, entrez Hello SharePoint.
  3. Sélectionnez Créer.
  4. Entrez la page Test dans le corps de la page.
  5. Cliquez sur Enregistrer.

Exécuter l’exemple d’application Core.JavaScriptCustomization

Lorsque vous exécutez cet exemple de code, une application hébergée par un fournisseur apparaît, comme illustré dans la figure suivante. Cet article décrit les scénarios 1 et 2, car vous pouvez utiliser les techniques de ces deux scénarios pour fournir des versions localisées de votre page de site et des titres de lien lancement rapide.

Capture d’écran montrant la page d’accueil de l’application Core.JavaScriptCustomization

Scénario 1

Le scénario 1 montre comment ajouter une référence à un fichier JavaScript sur un site SharePoint à l’aide d’une action personnalisée. Le choix du bouton de personnalisation Inject appelle la méthode btnSubmit _ Click dans scenario1.aspx.cs. La méthode btnSubmit _ Click appelle AddJsLink pour ajouter des références à des fichiers JavaScript à l’aide d’une action personnalisée sur le site web hôte.

La figure suivante illustre la page de démarrage du scénario 1.

Capture d’écran de la page d’accueil pour le scénario 1

Notes

Le code dans cet article est fourni tel quel, sans garantie d’aucune sorte, expresse ou implicite, y compris mais sans s’y limiter, aucune garantie implicite d’adéquation à un usage particulier, à une qualité marchande ou une absence de contrefaçon.

La méthode AddJSLink fait partie du fichier JavaScriptExtensions.cs dans OfficeDevPnP.Core. AddJSLink nécessite que vous fournissiez une chaîne représentant l’identificateur à affecter à l’action personnalisée, et une chaîne contenant une liste d’URL délimitée par des points-virgules aux fichiers JavaScript que vous souhaitez ajouter au site web hôte. Notez que cet exemple de code ajoute une référence à Scripts\scenario1.js, qui ajoute un message de barre d’état au site web hôte.

protected void btnSubmit_Click(object sender, EventArgs e)
{
  var spContext = SharePointContextProvider.Current.GetSharePointContext(Context);
  using (var cc = spContext.CreateUserClientContextForSPHost())
  {
      cc.Web.AddJsLink(Utilities.Scenario1Key, Utilities.BuildScenarioJavaScriptUrl(Utilities.Scenario1Key, this.Request));
  }
}

Notes

SharePoint utilise une stratégie de téléchargement minimal pour réduire la quantité de données téléchargées par le navigateur lorsque les utilisateurs naviguent entre les pages d’SharePoint site. Dans scenario1.js, le code suivant garantit que si la stratégie de téléchargement minimal est utilisée sur votre site SharePoint, la méthode RemoteManager_Inject est toujours appelée pour exécuter le code JavaScript afin d’ajouter le message de barre d’état au site web hôte. Pour plus d’informations, reportez-vous à la vue d’ensemble de la stratégie de téléchargement minimal.

if ("undefined" != typeof g_MinimalDownload && g_MinimalDownload && (window.location.pathname.toLowerCase()).endsWith("/_layouts/15/start.aspx") && "undefined" != typeof asyncDeltaManager) {
    // Register script for MDS if possible.
    RegisterModuleInit("scenario1.js", RemoteManager_Inject); //MDS registration
    RemoteManager_Inject(); //non MDS scenario
} else {
    RemoteManager_Inject();
}

Notes

Certains fichiers JavaScript peuvent dépendre d’autres fichiers JavaScript à charger en premier avant de pouvoir s’exécuter et se terminer correctement. La construction de code suivante à partir RemoteManager_Inject utilise la fonction loadScript dans scenario1.js pour charger jQuery d’abord, puis poursuivre l’exécution du code JavaScript restant.

var jQuery = "https://ajax.aspnetcdn.com/ajax/jQuery/jquery-2.0.2.min.js";
    // Load jQuery first, and then continue running the rest of the code.
    loadScript(jQuery, function () {
    // Add additional JavaScript code here to complete your task.
});

Cliquez sur Revenir au site. Comme le montre la figure suivante, le site web hôte affiche désormais un message de barre d’état qui a été ajouté par scenario1.js.

Capture d’écran du message de barre d’état ajouté à un site d’équipe à l’aide de JavaScript

Scénario 2

Le scénario 2 utilise la technique décrite dans le scénario 1 pour remplacer le texte de l’interface utilisateur par du texte traduit lu à partir d’un fichier de ressources JavaScript. Le scénario 2 remplace le titre du lien lancement rapide (Mon lancement rapide) et le titre de la page de site (Hello SharePoint) que vous avez créés précédemment. Le scénario 2 joint un fichier JavaScript qui lit les valeurs de texte traduites à partir de variables dans des fichiers de ressources JavaScript spécifiques à la culture. Le scénario 2 met ensuite à jour l’interface utilisateur.

La figure suivante illustre la page de démarrage du scénario 2.

Capture d’écran de la page d’accueil pour le scénario 2

Comme indiqué, le choix de la personnalisation Inject applique les modifications suivantes au site :

  • Le titre du lien Lancement rapide Mon entrée de lancement rapide est changé en lien Contoso.

  • Le titre de la page SharePoint site Hello est modifié en page Contoso.

    Personnalisations du scénario 2

Notes

Si vos valeurs pour le titre du lien Lancement rapide et le titre de la page de site diffèrent de celles indiquées dans la figure précédente, modifiez les variables quickLauch _ Scenario2 et pageTitle _ HelloSharePoint dans le scenario2.en-us.js ou le scenario2.nl-nl.js du fichier de ressources JavaScript, puis exécutez à nouveau l’exemple de code.

Le scenario2.en-us.js stocke des ressources spécifiques à la culture anglaise (États-Unis). Le scenario2.nl-nl.js stocke des ressources spécifiques à la culture néerlandaise. Si vous testez cet exemple de code à l’aide d’un autre langage, envisagez de créer un autre fichier de ressources JavaScript qui utilise la même convention d’affectation de noms.

Comme dans le scénario 1, btnSubmit _ Click in scenario2.aspx.cs appelle AddJsLink pour ajouter une référence au fichier Scripts\scenario2.js. Dans scenario2.js, la fonction RemoteManager _ Inject appelle la fonction TranslateQuickLaunch, qui effectue les tâches suivantes :

  • Détermine la culture du site à l’aide _ de spPageContextInfo.currentUICultureName.
  • Charge le fichier de ressources JavaScript contenant des ressources propres à la culture qui correspondent à la culture d’interface utilisateur du site. Par exemple, si la culture du site était l’anglais (États-Unis), le scenario2.en-us.js est chargé.
  • Remplace mon entrée de relance rapide par la valeur de la variable quickLauch _ Scenario2 lue à partir du fichier de ressources JavaScript.
function RemoteManager_Inject() {
    var jQuery = "https://ajax.aspnetcdn.com/ajax/jQuery/jquery-2.0.2.min.js";

    loadScript(jQuery, function () {
        SP.SOD.executeOrDelayUntilScriptLoaded(function () { TranslateQuickLaunch(); }, 'sp.js');
    });
}

function TranslateQuickLaunch() {
    // Load jQuery and if complete, load the JS resource file.
    var scriptUrl = "";
    var scriptRevision = "";
    // Iterate over the scripts loaded on the page to find the scenario2 script. Then use the script URL to dynamically build the URL for the resource file to be loaded.
    $('script').each(function (i, el) {
        if (el.src.toLowerCase().indexOf('scenario2.js') > -1) {
            scriptUrl = el.src;
            scriptRevision = scriptUrl.substring(scriptUrl.indexOf('.js') + 3);
            scriptUrl = scriptUrl.substring(0, scriptUrl.indexOf('.js'));
        }
    })

    var resourcesFile = scriptUrl + "." + _spPageContextInfo.currentUICultureName.toLowerCase() + ".js" + scriptRevision;
    // Load the JS resource file based on the user's language settings.
    loadScript(resourcesFile, function () {

        // General changes that apply to all loaded pages.
        // ----------------------------------------------

        // Update the Quick Launch labels.
        // Note that you can use the jQuery  function to iterate over all elements that match your jQuery selector.
        $("span.ms-navedit-flyoutArrow").each(function () {
            if (this.innerText.toLowerCase().indexOf('my quicklaunch entry') > -1) {
                // Update the label.
                $(this).find('.menu-item-text').text(quickLauch_Scenario2);
                // Update the tooltip.
                $(this).parent().attr("title", quickLauch_Scenario2);
            }
        });

        // Page-specific changes require an IsOnPage call.
        // ----------------------------------------------------------

        // Change the title of the "Hello SharePoint" page.
        if (IsOnPage("Hello%20SharePoint.aspx")) {
            $("#DeltaPlaceHolderPageTitleInTitleArea").find("A").each(function () {
                if ($(this).text().toLowerCase().indexOf("hello sharepoint") > -1) {
                    // Update the label.
                    $(this).text(pageTitle_HelloSharePoint);
                    // Update the tooltip.
                    $(this).attr("title", pageTitle_HelloSharePoint);
                }
            });
        }

    });
}

Voir aussi