The goal of this project is to demonstrate how to group SharePoint documents that are available in multiple languages. These grouped documents, along with their language variations, are then automatically displayed in a web part.
This project is designed for scenarios where you have documents that have been translated into various languages. These documents are related because they are different versions of the same content in different languages. Using the solutions provided in this repository, you can group these related documents. Once grouped, the documents and their translations will be automatically rendered and displayed in a web part, allowing users to easily access the different language versions.
All lists and fields associated with the PuntoBello solution are prefixed with pb_
This project consists of three SharePoint SPFx solutions:
You can find additional information in each respective repository.
All the SPFx solutions are strongly focused on serving multilingual content. Our implementation pattern differs from the standard SPFx approach to enhance SharePoint's multilingual capabilities.
For example, content is always displayed in the specific language of the page. If you have a page translated into various languages, the content on each page will be rendered in that page's language, rather than the user's language, avoiding the mixing of different languages on the same page.
You can translate all the text by adding or updating the files in the loc folder. The default.js file should always be present to ensure a default behavior for the component.
Text-based information is served from the loc folder, as is typical in SPFx solutions. Additionally, we have implemented a default language file (default.js), which will always be used if the corresponding user language file is not present in the SPFx solution.
The current user language is retrieved in two different ways, depending on the type of SPFx solution.
Typically web parts: The language is gathered from the current page language if running in a multilingual SharePoint configuration or from the current site language. The content will be served in this language.
Typically application customizers:
The language is gathered from the current cultureUIName (SPFx property pageContext.cultureInfo.currentUICultureName).
Across all the PuntoBello solutions, we have put considerable effort into enabling you to configure your solutions at build time, so that you can:
- Brand the solution with your specific colors, fonts, etc.
- Deploy the solutions easily on multiple tenants if needed (e.g., dev/test/prod environments).
We have also implemented a mini framework across all solutions, which you can easily extend with additional properties if you want to configure further aspects of the solutions.
https://github.com/diemobiliar/puntobello-installer/ is configured as a submodule und provides a docker image containing build and deploy scripts for SPFx and SharePoint Scripts. When cloning this repository, include the submodule:
git clone --recurse-submodules https://github.com/diemobiliar/puntobello-multilingualdocument.gitAlternatively, configure the submodule after cloning the repository:
git submodule update --initWith the Puntobello Installer, there is the possibility to execute the installation of all artifacts in various variants. These are described below. They are:
Alternatively, your own preferred methods can be used to build and deploy the solutions - see Build and serve Webpart or Extension locally using nvm.
📝 NOTE: The Dockerfile can be used for arm64 or amd64 CPU architectures. The architecture can be set to "arm64" or "amd64" in the devcontainer.json under build.args. The architecture can also be set using the
ARCHargument for use withdocker build. Only arm64 and amd64 are supported. It is set to amd64 if you don't change.
📝 NOTE: If the scripts are executed locally on the client and not in the Dev container, it must be ensured that the prerequisites for building SPFx solutions as well as the corresponding PowerShell modules are installed.
💡 TIP: In order to use the scripts you have to configure login mechanism and other parameters in
./.devcontainer/scripts/config.psm1.Every authentication mechanism is based on the PnP.PowerShell examples. For setting up an Entra ID app registration and its corresponding API permissions, as well as the necessary permissions when using a user, consult the documentation: Connect-PnPOnline and Authentication.
⚠️ Caution: Never commit files containing secrets or passwords!
The Visual Studio Code Dev Containers extension lets you use a container as a full-featured development environment.
💡 TIP: If you're interested in getting started with dev containers, you may find this Dev Containers tutorial helpful. It provides step-by-step instructions to help you get up and running quickly.
- Use Ctrl + Shift + P (on Windows) or Command + Shift + P (on OS X) to run
Dev Containers: Rebuild and Reopen in Container. This builds the container and attaches the project folder to the container with PowerShell and modules loaded. - Run
Deploy-SitesAndLists.ps1to create the SPO sites and lists. The configuration is set in folderspo. If you want to change the target urls of sites and lists, change the configuration in the json files.
- Run
Build-SPWP.ps1in the Dev Container to build the solutions. The script installs every dependencies and creates the sppkg files. These are saved in sharepoint/solution folder of each solution. - Install the solutions in SPO app catalog and sites with the script
Deploy-SPWP.ps1. If you have them already installed, this script can be used to update the solutions as well. - Sites, Lists and Solutions are ready to use.
If you want to test or debug a solution without deploying it in the app catalog, you can use gulp serve in the Dev Container.
📝 NOTE: The Dev container has configured the two default ports 4321 and 35729 for forwarding. If the configuration is different, corresponding parameters must be adjusted in the solutions as well as in the devcontainer.json.
- Trust the dev certificate:
gulp trust-dev-cert - Change to the directory of the solution e.g.
cd ./puntobello-multilingualdocument-spwp. - Set the page urls in config/serve.json.
- Start serving:
gulp serve - Open the configured workbench url to test or debugging the solution.
- Run
docker buildcommand to build the docker container from Dockerfile. Set build argument ARCH to desired CPU architecture (amd64 or arm64).
docker build -t pbspfxtools --build-arg ARCH=amd64 -f ./.devcontainer/Dockerfile ./.devcontainer- Run the deploy script for SPO sites and lists.
docker run -v ${PWD}:/spfx -w /spfx pbspfxtools pwsh -Command "Deploy-SitesAndLists.ps1"- Build the solutions using the build script in the docker container.
docker run -v ${PWD}:/spfx -w /spfx pbspfxtools pwsh -Command "Build-SPWP.ps1"- Deploy the solutions to app catalog and sites using the deploy script in the docker container.
docker run -v ${PWD}:/spfx -w /spfx pbspfxtools pwsh -Command "Deploy-SPWP.ps1"- Run
.\.devcontainer\scripts\Deploy-SitesAndLists.ps1in the root of the project to create the SPO sites and lists. The configuration is set in folderspo. If you want to change the target urls of sites and lists, change the configuration in the json files.
- Run
.\.devcontainer\scripts\Build-SPWP.ps1in to build the solutions. The script installs every dependencies and creates the sppkg files. These are saved in sharepoint/solution folder of each solution. - Install the solutions in SPO app catalog and sites with the script
.\.devcontainer\scripts\Deploy-SPWP.ps1. If you have them already installed, this script can be used to update the solutions as well. - Sites, Lists and Solutions are ready to use.
- Change console to solution folder e.g.
cd ./puntobello-multilingualdocument-spwp. - Run
nvm useto set node version. - Run
npm installto install dependencies. - Run
npm run pbship:devto build the solution or runnpm run start:devto serve for testing or debugging.
- Nicole Beck Dekkara - PuntoBello
- Mattias Bürgi - PuntoBello
- Fabian Hutzli - PuntoBello
- Nello D'Andrea - PuntoBello
This project is licensed under the MIT - see the LICENSE.md file for details
If you find this software useful and incorporate it into your own projects, especially for commercial purposes, we kindly ask that you acknowledge its use. This acknowledgment can be as simple as mentioning "Powered by Die Mobiliar - PuntoBello" in your product's documentation, website, or any related materials.
While this is not a requirement of the MIT License and is entirely voluntary, it helps support and recognize the efforts of the developers who contributed to this project. We appreciate your support!