playbooks

home / skills / github / awesome-copilot / vscode-ext-localization

vscode-ext-localization skill

/skills/vscode-ext-localization

This skill helps you localize every aspect of VS Code extensions, from settings to messages, across languages.

npx playbooks add skill github/awesome-copilot --skill vscode-ext-localization

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
1.4 KB
---
name: vscode-ext-localization
description: 'Guidelines for proper localization of VS Code extensions, following VS Code extension development guidelines, libraries and good practices'
---

# VS Code extension localization

This skill helps you localize every aspect of VS Code extensions

## When to use this skill

Use this skill when you need to:
- Localize new or existing contributed configurations (settings), commands, menus, views or walkthroughs
- Localize new or existing messages or other string resources contained in extension source code that are displayed to the end user

# Instructions

VS Code localization is composed by three different approaches, depending on the resource that is being localized. When a new localizable resource is created or updated, the corresponding localization for all currently available languages must be created/updated.

1. Configurations like Settings, Commands, Menus, Views, ViewsWelcome, Walkthrough Titles and Descriptions, defined in `package.json`
  -> An exclusive `package.nls.LANGID.json` file, like `package.nls.pt-br.json` of Brazilian Portuguese (`pt-br`) localization
2. Walkthrough content (defined in its own `Markdown` files)
  -> An exclusive `Markdown` file like `walkthrough/someStep.pt-br.md` for Brazilian Portuguese localization
3. Messages and string located in extension source code (JavaScript or TypeScript files)
  -> An exclusive `bundle.l10n.pt-br.json` for Brazilian Portuguese localization

Overview

This skill provides practical guidelines to localize every part of a Visual Studio Code extension. It summarizes the three localization approaches required by VS Code: package metadata, walkthrough content, and in-code strings. Follow these conventions to ensure consistent translations for all supported languages and to meet VS Code extension localization expectations.

How this skill works

The skill explains which files to create or update for each type of localizable resource and the naming conventions to use. For settings, commands, menus, views, and similar items declared in package.json you create package.nls.{lang}.json files. For walkthrough Markdown content you create parallel .{lang}.md files. For strings inside source code you create bundle.l10n.{lang}.json files. It also emphasizes updating localizations whenever resources change.

When to use it

  • Adding or changing extension settings, commands, menus, views, or walkthrough metadata in package.json
  • Translating walkthrough steps, guides, or Markdown-based onboarding content
  • Localizing user-facing strings in JavaScript or TypeScript source files
  • Preparing an extension for multi-language releases or contributing community translations
  • Consistency checks before publishing or during CI validation for localization completeness

Best practices

  • Create one localization file per target language and resource type using exact naming (e.g., package.nls.pt-br.json).
  • Update every language file whenever a new or modified resource appears in the base (usually English) files.
  • Keep translation keys identical to the source keys to avoid lookup failures at runtime.
  • Store walkthrough translations as separate Markdown files next to the original, matching file names with language suffixes.
  • Use bundle.l10n.{lang}.json for in-code strings and call the localization API consistently from source code.

Example use cases

  • Localizing new settings and command labels added to package.json so VS Code shows translated UI text.
  • Providing translated onboarding walkthroughs by adding walkthrough/step.pt-br.md alongside the original Markdown.
  • Extracting user-facing strings from TypeScript into bundle.l10n.fr.json and wiring up the localization loader.
  • Running CI checks that verify each package.nls.*.json contains keys matching package.json entries.
  • Coordinating community-contributed translations by mapping contributors to specific language JSON or MD files.

FAQ

Do I need separate files per language for each resource type?

Yes. VS Code expects distinct localization files per language and resource type (package metadata, walkthrough Markdown, and source bundles).

What happens if a key is missing in a localization file?

VS Code falls back to the original language for that key. Missing keys can produce inconsistent UI translations, so keep files synchronized.