estruyf / vscode-spfx-localization

SharePoint Framework Localization Resources Extension

SharePoint Framework Localization Resources Extension

This extension for Visual Studio Code makes it easier to work with locale resource files in SharePoint Framework projects. The extension has the ability to export all locale labels to a CSV/XLSX file to make translations easier to process. Once the CSV/XLSX file is complete, the data could be imported.

Besides the CSV/XLSX import and export functionality. The extension allows you to quickly add new locale labels, importing the resource dependency reference to your file and showing the locale label values while hovering over their name in code.

What can this extension do for you?

Export to CSV file

With the CSV/XLSX export functionality, you can export a single or all known resources to a CSV/XLSX file. The structure of this CSV/XLSX file looks as follows:

key;Locale <locale>;<Resource key found in config.json>
DescriptionLabel;Description;x

If you have multiple resource files and want to use the same key/labels, you can use the value x to specify for which resources the key is intended.

Import from a CSV/XLSX file

Once you exported to a CSV/XLSX file, that file becomes the master. Which means, if you are going to import from the CSV/XLSX file, it will overwrite the already existing {locale}.js files in your project.

If you set the spfxLocalization.autoCsvExport setting to true (by default it is set to false). The extension will automatically export the labels to the CSV/XLSX file when you create a new label with the Create new resource key action.

Import the resource dependency reference

With the SPFx import localization strings dependency action, you can quickly add the resource dependency reference to your file.

Creating a new resource key

Creating new resource keys was never easier. Select the text in your code, and use the SPFx create and insert localization key for selected text to create and insert the new label to your code.

What with multiple localized resources?

When multiple localization resources are available (retrieved from the config.json file), it will propose you which one to import or add your keys.

Here is a sample of my config.json file:

Quickly check the resource value

By hovering over the resource value used in your TypeScript or React code, a hover panel appears to show you the known values:

Extension settings

The extension has the following settings which you can configure to your own preference:

Setting name	Description	Type	Default value
spfxLocalization.csvFileLocation	The location of the SPFx locale labels CSV/XLSX file.	string	./spfx-locale.csv
spfxLocalization.csvDelimiter	The delimiter to use in the CSV/XLSX file.	string	;
spfxLocalization.autoCsvExport	Specify if you want to automatically export to the CSV/XLSX file when creating new labels.	boolean	false
spfxLocalization.localeFileExtension	Specify the extension type of the localization files. Default is JavaScript, but you can be changed to TypeScript.	enum	"js" | "ts"
spfxLocalization.csvUseBom	Use UTF8 BOM marker for CSV/XLSX files. Can be useful on Windows to make UTF8 CSV/XLSX files recognizable by Excel for example.	boolean	false
spfxLocalization.csvUseComment	Enable comment column in CSV/XLSX. You can use this column for notices, such as "translated" or "new".	boolean	false
spfxLocalization.csvUseTimestamp	Auto-fill timestamp column with current timestamp when new strings are added.	boolean	false

How to use this extension

Export to CSV/XLSX

• Start by opening the command prompt:
  • Windows ⇧+ctrl+P
  • Mac: ⇧+⌘+P
• Type: SPFx export locale labels to CSV/XLSX and press enter
• Select for which resource(s) you want to start the export

Import from CSV/XLSX

• Start by opening the command prompt:
  • Windows ⇧+ctrl+P
  • Mac: ⇧+⌘+P
• Type: SPFx import locale labels from CSV/XLSX and press enter
• Select for which resource(s) you want to start the import

Import resource module to the current file

• Right-click in the editor
• Click on SPFx import localization strings module
• Select the localized resource to import (if multiple are available, otherwise it will take the first one)

OR

• Start by opening the command prompt:
  • Windows ⇧+ctrl+P
  • Mac: ⇧+⌘+P
• Type: SPFx import localization strings module and press enter
• Select the localized resource to import (if multiple are available, otherwise it will take the first one)

Create a new locale label

• Right-click in the editor
• Click on SPFx create localization key
• Provide the name of the key to create
• Provide the value for the locale label
• Select the localized resource to where the label will be created

OR

• Start by selecting some text in your code
• Open the command prompt:
  • Windows ⇧+ctrl+P
  • Mac: ⇧+⌘+P
• Type: SPFx create localization key and press enter
• Provide the name of the key to create
• Provide the value for the locale label
• Select the localized resource to where the label will be created

Create a new locale label by selecting text

• Start by selecting some text in your code
• Right-click in the editor
• Click on SPFx create and insert localization key for selected text
• Provide the name of the key to create
• Select the localized resource to where the label will be created

OR

• Start by selecting some text in your code
• Open the command prompt:
  • Windows ⇧+ctrl+P
  • Mac: ⇧+⌘+P
• Type: SPFx create and insert localization key for selected text and press enter
• Provide the name of the key to create
• Select the localized resource to where the label will be created

Editor context menu

All the actions are also available from the editor its context menu.

When you select text, the add and insert action becomes available:

Feedback and snippet ideas

Feedback and ideas are always welcome. Please submit them via creating an issue in the project repository: issue list.

vscode-spfx-localization's Issues

Export to CSV doesn't work right for strings with nested objects

After running "SPFx export locale labels to CSV", the generated CSV has broken keys and values for nested objects.

Input en-us.js:

define([], function() {
  return {
    "Prop1":"string",
    "Group1":{
      "Group1Prop1":"string",
      "Group1Prop2":"string"
    }
   }
});

Input myStrings.d.ts:

declare interface ICustomizerStrings {
  Prop1:string;
  Group1:{
    Group1Prop1:string;
    Group1Prop2:string;
  }
}

declare module 'CustomizerStrings' {
  const strings: ICustomizerStrings;
  export = strings;
}

Output spfx-locale.csv:

key;Locale en-us;CustomizerStrings
Prop1;string;x
Group1;{;x
Group1Prop1;string;x
Group1Prop2;string;x

Maybe it is not an issue, but more like a feature request.

Feature request: "Find unused localization strings"

It would be nice if the extension could find all localization strings that are not used in the code.
This would help to keep the translation files clean.

That could be probably done by iterating all files and checking if a string is used there or not
Could be a trivial text seatch (like "strings.xxx" or something smarter than that actually checks the syntax)
I would be happy already with full-text search.

Suggestion: option for resource file mapping

To simplify future integration with other tools (consider some online tools for example) I would suggest making the "resource" column optional. Also, it's not really useful for the case when you have JUST ONE resource file and you still have to put "x" in every row. I mean, this one looks odd, especially in case there is only one file:

I would suggest to keep supporting this way of mapping, but make it optional, with the following alternatives:

• if there is only one resource file, just use that.
• a file name can be used to map to the resource. Meaning, if you have multiple resource files, you (may) have multiple CSV files. If there is a CSV file that matches the resource file, use that.
• In case of Excel, a worksheet name can be used as resource name. So if there is a worksheet with matching name, use that.

Also this will make the structure of the file more "natural" for the newcomers.

Where does the extension find the {locale}.js files?

Extension is finding resource files somewhere and I have no idea where. I've added 2 new locales (it-it and nl-nl), and attempting to generate the translation CSV and it is not adding those two locales. To troubleshoot, I've removed the lib folder referenced in config.json completely

and also the loc folder under /src. Still it is finding the files somewhere, so the question is where? It is even displaying error, but still generating the csv.

UPDATE: After having removed the loc folder and lib folder and restarting VS Code, it finally stopped generating the CSV from ghost files but now it fails to include any translation (even after re-adding the loc files and rebuilding the package) in the CSV file.

And now after trying this a few times, it suddenly now includes all locales in the CSV. There is clearly some caching somewhere making this very unproductive to use.

Excel format support

After using the extension for a couple of years, I'd like to improve it by adding Excel format support.
Basically, it's just about an optional change of CSV => XLSX.

In Excel file, you can set width, colors, add comments to rows, etc, that is not possible with CSV, you have to resize the columns every time you edit.

As the next step, integration with some online list could be good.

I'm adding a PR to support Excel format.
To activate, just change in the extension of the file in the settings:

@estruyf would appreciate if you could look at this 😄

Export csv file include unwanted spaces

When I export to CSV, the coding style does not trim spaces.

For example, let's say I have this strings:

define([], function () {
    return {
        MyStringWithASpace : "my value 1",
        MyString: "my value 2"
    };
});

Leads to :

key;Locale en-us;Locale fr-fr;LocalizeTestWebPartStrings;Comment;Timestamp
MyString;;my value 2;x;;2022-03-16T21:38:36
MyStringWithASpace ;;my value 1;x;;2022-03-16T21:38:36

As you can, the exported key includes a space behind the name from the locale module.

It's worse if multiple locale files has not exactly the same format, it can leads to two rows in the CSV file:

key;Locale en-us;Locale fr-fr;LocalizeTestWebPartStrings;Comment;Timestamp
MyString;my value 2;my value 2;x;;2022-03-16T21:42:12
MyStringWithASpace;my value 1;;x;;2022-03-16T21:42:12
MyStringWithASpace  ;;my value 1;x;;2022-03-16T21:42:30

This is also true in the other way. Importing a CSV file that includes such spaces generate differents keys:

Literally (spaces are exactly these ones) :

declare interface ILocalizeTestWebPartStrings {
    MyString: string;
    MyStringWithASpace: string;
MyStringWithASpace  : string;
}

Translations not included in generated CSV

After doing "SPFx export locale labels to CSV", the generated CSV is missing the actual translations. Using 1.2.2 of your tool and VSCode 1.32.3. What could be causing this?

Output

key;Locale en-us;Locale fi-fi;projectFoldersStrings
UIPropsGroupCommon;;;x

Input fi-fi.js

define([], function() {
  return {        
    UIPropsGroupCommon: "Yleiset asetukset"
  }
});

Input en-us.js

define([], function() {
  return {    
    UIPropsGroupCommon: "Common settings"
  }
});

mystrings.d.ts

declare interface IProjectFoldersStrings {
  UIPropsGroupCommon: string;
}

declare module 'projectFoldersStrings' {
  const strings: IProjectFoldersStrings;
  export = strings;
}

Suggestion: automatically add import on string extraction

A minor improvement:
When you use "extract string from selection", it may happen that there is no import of the strings file into the current file yet.
So, you have to import the strings file as a next step, which is IMHO annoying. It would be nice if the extension automatically imported the strings file on extraction (if needed).

Sort all strings (in particular, strings.d.ts) according to the CSV (alphabetically)

Now when you add a new string, it is added to the beginning of the file in strings.d.ts, but in the middle in .js files when you generate. But when you generate it is added according to the CSV order. So it's a bit messy.

It would be great to have consistency here, so that the extension always follows the same when adding strings.
Otherwise, this produced a lot of "noise" if you check the difference with the previous version afterwards.

CSV UTF8 BOM marker option

It would be nice to have a BOM marker option added. Now if you double-click the CSV file, Excel on Windows does not open it properly if the file contains non-ASCII UTF8 characters. So you may need to open it in Excel by specifically selecting UTF8 encoding.

What is BOM: https://en.wikipedia.org/wiki/Byte_order_mark

So an option in the extension settings could be great.
Will see if I could add this myself if yes then probably will come up with a PR :)

Feature request: comments for CSV translations

Would be great to have one more column in CSV "comment".

In real project, it's often very useful to have comments for translated strings. This can be "please review", "needs improvment", "not used", "used in placx XYZ", etc. Most translation/localization tools support this functionality. Lingobit, ResX Translator, etc.
Also, can be used to mark "not yet translated" strings for example.

WSL

Hi, there is some way to use this exetension in a WSL VSCode Environment? When I try to use, always appears:

Command 'SPFx create and insert localization key for selected text' resulted in an error (command 'extension.spfxLocalizationInsertKey' not found)

Multiline strings are not working

CSV can contain multiline values like this (notice the quotes around the last value, this AFAIK is legal for CSV). At least Excel read/writes something like this just fine:

I am a single line value,"I am a 
multi line value"

Basically, reading, writing, and extraction seem to all break at multiline strings 😞
By extraction I mean something like this:

Updating MyStrings.d.ts when importing CSV

Environment: React + Typescript.

Now if you import a CSV file (run a command to import), the string "definition" typescript file is not updated.
Means, if there are new keys added to CSV, they are not added to MyStrings.d.ts file (i.e. only the JavaScript files are updated).

Is it expected to work this way (why?) or it is just a missing feature?