SharePoint Framework - Multilingual Support (Localization)

SharePoint has supported localization in each of its version to help build better content for users worldwide. SharePoint Framework is also not an exception to it. SPFx offers multilingual support with the help of localized resource files as a part of SPFx solution. In this article, we will explore localization options with SPFx.

Overview

SharePoint has supported localization in each of its versions to help build better content for users worldwide. SharePoint Framework is also not an exception to it. SPFx offers multilingual support with the help of localized resource files as a part of an SPFx solution.
 
In this article, we will explore the localization options with SPFx. We will use ReactJS to develop the example.
 
Create SPFx Solution
 
Open the command prompt. Create a directory for SPFx solution.
  1. md spfx-react-localization  
Navigate to the above-created directory.
  1. cd spfx-react-localization  
Run Yeoman SharePoint Generator to create the solution.
  1. yo @microsoft/sharepoint  
Yeoman generator will present you with the wizard by asking questions about the solution to be created.
 
SharePoint Framework Multilingual Support 
Solution Name
 
Hit Enter to have a default name (spfx-react- localization in this case) or type in any other name for your solution.
 
Selected choice - Hit Enter.
 
Target for component
 
Here, we can select the target environment where we are planning to deploy the client web part, i.e., SharePoint Online or SharePoint OnPremise (SharePoint 2016 onwards).
 
Selected choice - SharePoint Online only (latest)
 
Place of files
 
We may choose to use the same folder or create a subfolder for our solution.
 
Selected choice - Same folder
 
Deployment option
 
Selecting Y will allow the app to deployed instantly to all sites and will be accessible everywhere.
 
Selected choice - N (install on each site explicitly)
 
Type of client-side component to create
 
We can choose to create a client-side web part or an extension. Choose the webpart option.
 
Selected choice - WebPart
 
Web part name
 
Hit Enter to select the default name or type in any other name.
 
Selected choice - LocalizeText
 
Web part description
 
Hit Enter to select the default description or type in any other value.
 
Selected choice - Localize SPFx web part
  
Framework to use
 
Select any JavaScript framework to develop the component. Available choices are (No JavaScript Framework, React, and Knockout).
 
Selected choice - React
 
Yeoman generator will perform scaffolding process to generate the solution. The scaffolding process will take a significant amount of time.
 
Once the scaffolding process is completed, lock down the version of project dependencies by running the below command.
  1. npm shrinkwrap  
In the command prompt, type the below command to open the solution in a code editor of your choice.
  1. code .   
Localization Support
 
SPFx solution holds localized texts in "loc" folder. The "mystrings.d.ts" file declares an interface for strings.
  1. declare interface ILocalizeTextWebPartStrings {  
  2.   PropertyPaneDescription: string;  
  3.   BasicGroupName: string;  
  4.   DescriptionFieldLabel: string;  
  5. }  
  6.   
  7. declare module 'LocalizeTextWebPartStrings' {  
  8.   const strings: ILocalizeTextWebPartStrings;  
  9.   export = strings;  
  10. }  
By default, the en-us.js file has localized texts in English. The default locale used by the SharePoint Framework is en-US. To support localization for any language, we need to add js file for each supported language.
 
Localize web part property pane
 
Add file fi-fi.js under “\src\webparts\localizeText\loc\” with localization for Finnish language.
  1. define([], function() {  
  2.   return {  
  3.     "PropertyPaneDescription""Kuvaus",  
  4.     "BasicGroupName""Ryhmän nimi",  
  5.     "DescriptionFieldLabel""Kuvauskenttä"  
  6.   }  
  7. });  
Localize web part content
 
The content inside the web part can be localized in the same way as of web part property pane. For each of the strings to be localized, add a key to the localization TypeScript definition file and localized values in each of the locale JS files.
 
We will localize the button text of the web part.
 
Step 1 - Add key in localization TypeScript definition file
 
Open mystrings.d.ts under “\src\webparts\localizeText\loc\”.
 
Add a key for the button text.
  1. declare interface ILocalizeTextWebPartStrings {  
  2.   PropertyPaneDescription: string;  
  3.   BasicGroupName: string;  
  4.   DescriptionFieldLabel: string;  
  5.   LearnMoreButtonLabel: string;  
  6. }  
  7.   
  8. declare module 'LocalizeTextWebPartStrings' {  
  9.   const strings: ILocalizeTextWebPartStrings;  
  10.   export = strings;  
  11. }  
Step 2 - Add localized values in each of the locale JS files
 
\src\webparts\localizeText\loc\en-us.js
  1. define([], function() {  
  2.   return {  
  3.     "PropertyPaneDescription""Description",  
  4.     "BasicGroupName""Group Name",  
  5.     "DescriptionFieldLabel""Description Field",  
  6.     "LearnMoreButtonLabel""Learn more"  
  7.   }  
  8. });  
\src\webparts\localizeText\loc\fi-fi.js
  1. define([], function() {  
  2.   return {  
  3.     "PropertyPaneDescription""Kuvaus",  
  4.     "BasicGroupName""Ryhmän nimi",  
  5.     "DescriptionFieldLabel""Kuvauskenttä",  
  6.     "LearnMoreButtonLabel""Lisätietoja"  
  7.   }  
  8. });  
Step 3 - Globalization of web part
 
Open \src\webparts\localizeText\components\LocalizeText.tsx and add reference to the localized strings.
  1. import * as strings from 'LocalizeTextWebPartStrings';  
Replace the actual content with the references to localized strings.
  1. export default class LocalizeText extends React.Component<ILocalizeTextProps, {}> {  
  2.   public render(): React.ReactElement<ILocalizeTextProps> {  
  3.     return (  
  4.       <div className={ styles.localizeText }>  
  5.         <div className={ styles.container }>  
  6.           <div className={ styles.row }>  
  7.             <div className={ styles.column }>  
  8.               <span className={ styles.title }>Welcome to SharePoint!</span>  
  9.               <p className={ styles.subTitle }>Customize SharePoint experiences using Web Parts.</p>  
  10.               <p className={ styles.description }>{escape(this.props.description)}</p>  
  11.               <a href="https://aka.ms/spfx" className={ styles.button }>  
  12.                 <span className={ styles.label }>{strings.LearnMoreButtonLabel}</span>  
  13.               </a>  
  14.             </div>  
  15.           </div>  
  16.         </div>  
  17.       </div>  
  18.     );  
  19.   }  
  20. }  
Test web part content and property pane
 
The locale value of spPageContextInfo.currentUICultureName is being used as default locale. On SharePoint local workbench, the default locale used is en-US.
 
Run gulp serve by specifying local parameter:
  1. gulp serve --locale=fi-fi  
SharePoint Framework Multilingual Support 
 
Summary
 
Localization helps to build better content for users worldwide. SharePoint Framework supports localization by maintaining localized values in separate Javascript files per language.