Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/sketchbuch/vscode-ext-localisation

Localisation for VSCode Extensions using package.nls.json files.
https://github.com/sketchbuch/vscode-ext-localisation

i18n javascript l10n localisation localization nls npm-package typescript vscode vscode-extension

Last synced: 3 months ago
JSON representation

Localisation for VSCode Extensions using package.nls.json files.

Awesome Lists containing this project

README 

        
# VSCode Extension Localisation



**vscode-ext-localisation**



This packages is for VSCode extension developers to aid in translating their extensions.



VSCode already localises an extension's package.json file using nls files, this package also lets you use the same files to localise the rest of your extension as well.



VSCode localises package.json using key/values in nls files but these are flat - you can't structure the translations. If you want to scope the translations they have to still be one key:



```

    {

        "some-scope.my-key": "A translation"

    }

```



With this extension you can structure your translations **for the rest** of your extension anyway you want (basically anywhere where you use the t() function to access translations).



```

    {

        "some-scope": {

            "my-key": "A translation"

        },

        "another-scope": {

            "deeper": {

                "deeper-still": {

                    "any-depth": "is supported"

                }

            }

        }

        "arrays": [

            "are",

            "also",

            "supported",

        ]

    }

```



This was created for my own extensions but maybe you will find it useful for your own.



# Installation



```

    yarn add vscode-ext-localisation

```



# How to use



In your extension's activate() function, call loadTranslations() with the current vscode interface language and the extension path:



```

    import { getVscodeLang, loadTranslations } from 'vscode-ext-localisation';



    export const activate = (context: vscode.ExtensionContext): void => {

        loadTranslations(getVscodeLang(process.env.VSCODE_NLS_CONFIG), context.extensionPath);

    };

```



This will load the translations for the active language. If the vscode language ever changes, vscode will restart and call the activate() function again, loading the correct language. If the language has no translation the default english translation will be used instead.



Then, to use a translation, import the t() function and uses it in your code:



```

    import { t } from 'vscode-ext-localisation';



    const anExampleFunction = (): string => {

        // Do stuff...

        return t('some-scope.an.example.function');

    }

```



If the english nls translation file does not exist loadTranslations() will throw an error - it is the minimum required translation file in order to use this package.



### Arrays



Import the ta() function and uses it in your code:



```

    import { ta } from 'vscode-ext-localisation';



    const anExampleFunction = (): string[] => {

        // Do stuff...

        return ta('get.my.array');

    }

```



## Placeholders



You can use placeholders, first define a placeholder in a translation by surrounding it with double curly brackets:



```

    {

        "currentCount": "Count: {{count}}"

    }

```



Then pass in an object with the placeholders and their values:



```

    t('currentCount', { count: 10 })

```



Placeholders can be strings or numbers.



## NLS Files



The nls files need to be in the root of your extension, they are just json files.



**package.nls.json** is the **en** translation file (vscode defaults to english - you can't make another language the default).



Other language files are in the same location but are suffixed with their language code:



**package.nls.de.json**, **package.nls.it.json** etc.



A list of supported language codes can be found here: https://code.visualstudio.com/docs/getstarted/locales



## Examples Usage



See: **[VSC Workspace Sidebar](https://github.com/sketchbuch/vsc-workspace-sidebar)** as an example.