One of the things hardest things when creating and maintaining a product is localization. It requires a lot of testing, validation and follow-up. In SharePoint Framework projects it is no different, maybe even a bit harder, as the localization files are created per component. This means that you might have to take care of duplicate localization keys and labels.
Back in July 2019, I wrote about a way to simplify the localization process by using only one localization file in your project.
I would still recommend this approach/solution when you are mainting only one project with multiple components. When your solutions eventually expands and exists of X number of components, it might be easier to split them up in separate projects. This splitting comes with a price, as that means that yet again you have to maintain multiple localization files over different projects.
Info: At Valo, we split up our projects/components based on their functionality and modules. Another reason why we do this is to speed up the project build times. For example, a project with five web parts is much slower than a project with only one web part.
When we first started creating our project(s) structure, we knew that localization was going to be difficult to maintain. That is why internally we created our own CLI and localization process which allows us to easily import and export all the localization keys and labels. All of this is done during our builds. The keys and labels are automatically propagated to the projects they belong to.
Info: During our development phase, we only have to take care of English keys/labels. The other localization files will automatically be generated by our localization process during the builds.
The Excel file in the above picture is used as our central location for managing all these keys and their corresponding labels. This approach works great, but I’m not going to lie. There is still some manual work required to check if you don’t have any duplicate keys or similarities which could be merged.
Looking for a better experience
As the product keeps on growing and new keys are required, we had to find a better solution. The most important thing of the new solution had to be an easy way to share the keys and labels. Another plus would be to easily check for duplicated keys.
Right at that time when I was looking for a better solutions, the long-awaited library component feature in SharePoint Framework became available in beta. This feature is now in GA since SPFx version
1.9 and provides a way of sharing code between other projects.
Info: Here you can find a tutorial of how you can create your first library component: library component tutorial.
Tip: Lerna is a great tool for managing projects which use the library component functionality.
As I already mentioned, Sharing is key for our localization story. We need that easy way of sharing keys through all our projects, so this makes the library component an ideal for what we were looking for.
How it’s implemented
The way it is implemented is by creating a new project with a library component, once you have such a project, do the following things:
- Create a new loc folder in the library component folder (not necessary, but it separates your component source and the localization files)
- Create an
en-us.jswith the following contents:
- Create a
mystrings.d.tsfile with the following contents:
- Add a localization reference in your
- Once these things are in place, all we have to do is to update the code of the library component itself.
As you can see, this is simple, but this is not all.
Normally when you are working with localization, you will add keys to the localization JS file and
mystrings.d.ts file. To simplify this process, I created an extra script which runs during a build and creates an
enum and generates all keys and comments to quickly see what the localization key will return. This means you no longer have to update the
mystrings.d.ts file with all the keys as the
enum will be used in the project.
Another advantage of generating the
enum file is that you don’t have to worry about duplicate keys, as it can only have unique keys.
The script which I use is a gulp task in a created in a seperate file
gulpfile.generatelocalkeys.js with the following content:
To use this script, add in your
gulpfile.js file the following line:
Important: Be sure to put it before the
Once you have all of this in place and run a build/bundle, it will automatically generate the
Important: Make sure to update the file references in the gulp task to that of your project or write some extra code to automatically find the path from the
When the localization key
enum is generated. All we have to do in our projects when we want to add a localization key is the following:
Besides that, the localization keys can now be shared in all your projects, there have to be less files loaded when loading a page. Normally you would have one localization file which requires to be loaded per web part. With this solution only one localization file will be loaded for all of them.