{"id":16781029,"url":"https://github.com/sketchbuch/vscode-ext-localisation","last_synced_at":"2025-10-29T11:38:20.195Z","repository":{"id":57394072,"uuid":"275570503","full_name":"sketchbuch/vscode-ext-localisation","owner":"sketchbuch","description":"Localisation for VSCode Extensions using package.nls.json files.","archived":false,"fork":false,"pushed_at":"2024-01-19T18:50:22.000Z","size":204,"stargazers_count":2,"open_issues_count":3,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-24T18:49:34.248Z","etag":null,"topics":["i18n","javascript","l10n","localisation","localization","nls","npm-package","typescript","vscode","vscode-extension"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/vscode-ext-localisation","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sketchbuch.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-06-28T11:28:57.000Z","updated_at":"2023-08-28T17:47:35.000Z","dependencies_parsed_at":"2024-01-19T19:46:53.594Z","dependency_job_id":"b18b4665-444b-4d16-9e4a-f4c7470e68ae","html_url":"https://github.com/sketchbuch/vscode-ext-localisation","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sketchbuch%2Fvscode-ext-localisation","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sketchbuch%2Fvscode-ext-localisation/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sketchbuch%2Fvscode-ext-localisation/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sketchbuch%2Fvscode-ext-localisation/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sketchbuch","download_url":"https://codeload.github.com/sketchbuch/vscode-ext-localisation/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247947859,"owners_count":21023066,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["i18n","javascript","l10n","localisation","localization","nls","npm-package","typescript","vscode","vscode-extension"],"created_at":"2024-10-13T07:36:32.889Z","updated_at":"2025-10-08T05:43:44.771Z","avatar_url":"https://github.com/sketchbuch.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# VSCode Extension Localisation\n\n**vscode-ext-localisation**\n\nThis packages is for VSCode extension developers to aid in translating their extensions.\n\nVSCode 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.\n\nVSCode 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:\n\n```\n    {\n        \"some-scope.my-key\": \"A translation\"\n    }\n```\n\nWith 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).\n\n```\n    {\n        \"some-scope\": {\n            \"my-key\": \"A translation\"\n        },\n        \"another-scope\": {\n            \"deeper\": {\n                \"deeper-still\": {\n                    \"any-depth\": \"is supported\"\n                }\n            }\n        }\n        \"arrays\": [\n            \"are\",\n            \"also\",\n            \"supported\",\n        ]\n    }\n```\n\nThis was created for my own extensions but maybe you will find it useful for your own.\n\n# Installation\n\n```\n    yarn add vscode-ext-localisation\n```\n\n# How to use\n\nIn your extension's activate() function, call loadTranslations() with the current vscode interface language and the extension path:\n\n```\n    import { getVscodeLang, loadTranslations } from 'vscode-ext-localisation';\n\n    export const activate = (context: vscode.ExtensionContext): void =\u003e {\n        loadTranslations(getVscodeLang(process.env.VSCODE_NLS_CONFIG), context.extensionPath);\n    };\n```\n\nThis 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.\n\nThen, to use a translation, import the t() function and uses it in your code:\n\n```\n    import { t } from 'vscode-ext-localisation';\n\n    const anExampleFunction = (): string =\u003e {\n        // Do stuff...\n        return t('some-scope.an.example.function');\n    }\n```\n\nIf 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.\n\n### Arrays\n\nImport the ta() function and uses it in your code:\n\n```\n    import { ta } from 'vscode-ext-localisation';\n\n    const anExampleFunction = (): string[] =\u003e {\n        // Do stuff...\n        return ta('get.my.array');\n    }\n```\n\n## Placeholders\n\nYou can use placeholders, first define a placeholder in a translation by surrounding it with double curly brackets:\n\n```\n    {\n        \"currentCount\": \"Count: {{count}}\"\n    }\n```\n\nThen pass in an object with the placeholders and their values:\n\n```\n    t('currentCount', { count: 10 })\n```\n\nPlaceholders can be strings or numbers.\n\n## NLS Files\n\nThe nls files need to be in the root of your extension, they are just json files.\n\n**package.nls.json** is the **en** translation file (vscode defaults to english - you can't make another language the default).\n\nOther language files are in the same location but are suffixed with their language code:\n\n**package.nls.de.json**, **package.nls.it.json** etc.\n\nA list of supported language codes can be found here: https://code.visualstudio.com/docs/getstarted/locales\n\n## Examples Usage\n\nSee: **[VSC Workspace Sidebar](https://github.com/sketchbuch/vsc-workspace-sidebar)** as an example.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsketchbuch%2Fvscode-ext-localisation","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsketchbuch%2Fvscode-ext-localisation","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsketchbuch%2Fvscode-ext-localisation/lists"}