Written by

Jayakumar Balasubramaniam

Share

  

Category

see all categories
intranet as a service

Enabling Multilingual/Localization in SharePoint Framework applications

Localization plays key role in every product to engage all type of customers. SharePoint has fulfilled that feature long back and it supports maximum of languages. As like resource files in traditional applications, we do have localized resource files in SharePoint Framework. 

Before proceeding in depth with multilingual concept in SPFx please follow the below articles to get to know about building SharePoint Framework applications. 

How to build SharePoint Framework Applications? 

The following blog posts will help you for sure in detail about building SPFx applications, 

Build SPFx webparts with Angular 4 

Deep Dive into SPFx webparts configuration 

Build SPFx extensions 

Integrating SPFx apps with visual Studio 

Let’s see simple localization implementation to update all the hard-coded labels/buttons/messages. SPFx maintains its localized resource files in the “loc” folder, by default resource file for English (en-us.js) will be there. 

SPFx

The language translation has to be done manually like a key value pair 

define([], function() { 

  return { 

    "PropertyPaneDescription": "Description", 

    "BasicGroupName": "Group Name", 

    "DescriptionFieldLabel": "Description Field" 

  } 

}); 

These values will be converted as a JSON object at runtime and it is imported into the webpart.ts file as below, 

import * as strings from 'DataSharingWebPartStrings';  

SPFx will choose the resource file based on culture name of the user which will be from the below property of the user context  

this.context.pageContext.cultureInfo.currentUICultureName 

Let’s update the keyword translation for the default welcome message in SPFx webparts like below,  

en-us.js 

define([], function() { 

  return { 

    "PropertyPaneDescription": "Description", 

    "BasicGroupName": "Group Name", 

    "DescriptionFieldLabel": "Description Field", 

    "WelcomeMessageHeader":"Welcome to SharePoint", 

    "WelcomeMessageBody":"Customize SharePoint experiences using Web Parts.", 

    "LearnMore":"Learn more" 

  } 

}); 

 

fr-FR.js (French language) 

define([], function() { 

    return { 

      "PropertyPaneDescription": "La description", 

      "BasicGroupName": "Nom de groupe", 

      "DescriptionFieldLabel": "Description du champ",      

      "WelcomeMessageHeader":"Bienvenue dans SharePoint", 

      "WelcomeMessageBody":"Personnaliser les expériences SharePoint à l'aide de composants Web Parts.", 

      "LearnMore":"Apprendre encore plus" 

    } 

  }); 

Keywords should be same for all the language files, only the translation value differs. These new keys have to be declared as a property in the interface which will map against the localized resource file. Interface for the strings is in the mystrings.d.ts file under the loc folder, below is our new properties 

declare interface IDataSharingWebPartStrings { 

  PropertyPaneDescription: string; 

  BasicGroupName: string; 

  DescriptionFieldLabel: string; 

  WelcomeMessageHeader: string; 

  WelcomeMessageBody: string; 

  LearnMore: string; 

} 

declare module 'DataSharingWebPartStrings' { 

  const strings: IDataSharingWebPartStrings; 

  export = strings; 

} 

The welcome message in render method will look like below, 

public render(): void { 

    this.domElement.innerHTML = ` 

      <div class="${ styles.dataSharing }"> 

        <div class="${ styles.container }"> 

          <div class="${ styles.row }"> 

            <div class="${ styles.column }"> 

              <span class="${ styles.title }">${strings.WelcomeMessageHeader}</span> 

              <p class="${ styles.subTitle }">${strings.WelcomeMessageBody}</p> 

              <p class="${ styles.description }">${escape(this.properties.description)}</p> 

              <a href="https://aka.ms/spfx" class="${ styles.button }"> 

                <span class="${ styles.label }">${strings.LearnMore}</span> 

              </a> 

            </div> 

          </div> 

        </div> 

      </div>`; 

  } 

 

Hard coded message values are replaced with the locale strings properties, so if the user language changes you no need to update anything in the code except adding new keywords in resource files. 

SharePoint Intranet Software

How to test localization in SharePoint Framework? 

If there is no resource file to map with current user’s culture, then English will be the default language. Below are the possible two ways to test the localization in SPFx without changing the currentUICultureName, 

1. By simply running the below command, where we will force the application to use the specified language 

gulp serve --locale=fr-FR 

Let’s go with the first approach now to see our language translation for the welcome message in French with the below command, 

Frenchgulp serve –locale=fr-FR 

gulp serve

If you want to run it again in English, simply run the gulp serve command since default language is English 

SharePoint Workbench

 

2. By updating the webpart configuration and this method will work only in the debug mode. Open the ./config/write-manifests.json file and add the property debugLocale with the language which you want to test. 

{ 

 "cdnBasePath": "<!-- PATH TO CDN -->", 

 "debugLocale": "nl-nl" 

} 

Now SPFx assumes default language is nl-nl you simply run the workbench with the command gulp serve to see your changes. 

If you have any questions/issues about this article, please let me know in comments.

Jayakumar Balasubramaniam

Written by Jayakumar Balasubramaniam

A technology evangelist working on Microsoft 365, SharePoint & Azure. Gets my hands dirty with latest and greatest of SharePoint, Azure & front-end frameworks. Currently working with “Hubfly – A unified digital workplace” as a Product Engineer. Getting in to the depth of the domain & technology, with my eyes for perfection, ensures that the product releases go right every time.